doc gen updates

CLAUDE.md

@@ -38,11 +38,11 @@ Direct. TypeSafe publishes an OpenAPI 3.1.0 document at `https://api.typesafe.ai
 - **Engine typing** - UPDATE marshals every SET value as a string; INSERT and EXEC send typed JSON; EXEC cannot carry a boolean. Documented for completeness; no method here uses those verbs.
 - **Content unions** - the vendor's `string | object | array (| null)` unions on `state`, `instructions`, criteria descriptions and the score legend are lowered to `string` in `pre_normalize.mjs` (9 sites) before provider-utils normalize, which would otherwise leave `additionalProperties: true` and `items: {}` on a `type: string` property. On the SQL surface those values are always strings.
 - **Docs examples** - three-statement agent-loop blocks (context, decision, action) against verified sibling-provider surfaces, plus a few plain SELECTs and a shell quick start. Facts a routine can compute stay in SQL; Jev is asked the judgment, one atomic question at a time, with the policy in `criteria` (finding 13). `bin/validate-docs-examples.sh` runs every block before a docs publish: typesafe live, the other providers routed with dummy credentials through a registry clone (finding 12). Known provider facts the examples depend on: aws `cidr_ipv_4`, aws list params as JSON arrays, k8s needs `KUBE_HOST`.
-- **Docgen** - `bin/patch-provider-utils.mjs` (npm `postinstall`) adds `select` to docgen's required-body-params allowlist and lists a SELECT method's naive body properties in the Parameters table, so the `evaluate` page documents `state`, `model`, `questions` as required and its SELECT example routes (provider-utils 0.7.10 still lacks it; the first two edits are carried from the anthropic and gemini builds). `sanitize-docs.mjs` keeps `<br />` line breaks in description cells.
+- **Docgen** - `bin/patch-provider-utils.mjs` (npm `postinstall`) adds `select` to docgen's required-body-params allowlist and lists a SELECT method's naive body properties in the Parameters table, so the `evaluate` page documents `state`, `model`, `questions` as required and its SELECT example routes (provider-utils 0.7.11 still lacks it; the first two edits are carried from the anthropic and gemini builds). `sanitize-docs.mjs` keeps `<br />` line breaks in description cells.
 
 ## Toolchain rules
 
-- Latest `@stackql/provider-utils` (0.7.10), `@stackql/pgwire-lite` (1.0.2) and `@apidevtools/swagger-parser` (13.1.0) at build time (check npm before starting: `npm view @stackql/provider-utils version`); Docusaurus `^3.10.x`. Node >= 22.19 (Node 20 reached end of life in April 2026; swagger-parser 13 needs 22.19), `type: module`. `js-yaml` stays on 4.x: provider-utils emits with js-yaml 4, and v5 drops the default export, removes the `quotingType` dump option and changes scalar quoting, so that bump is a coordinated change with provider-utils. `package-lock.json` pins what CI installs; a toolchain bump is an explicit commit that regenerates the artifacts and re-checks `bin/patch-provider-utils.mjs` (it prints PATTERN NOT FOUND when upstream moves).
+- Latest `@stackql/provider-utils` (0.7.11), `@stackql/pgwire-lite` (1.0.2) and `@apidevtools/swagger-parser` (13.1.0) at build time (check npm before starting: `npm view @stackql/provider-utils version`); Docusaurus `^3.10.x`. Node >= 22.19 (Node 20 reached end of life in April 2026; swagger-parser 13 needs 22.19), `type: module`. `js-yaml` stays on 4.x: provider-utils emits with js-yaml 4, and v5 drops the default export, removes the `quotingType` dump option and changes scalar quoting, so that bump is a coordinated change with provider-utils. `package-lock.json` pins what CI installs; a toolchain bump is an explicit commit that regenerates the artifacts and re-checks `bin/patch-provider-utils.mjs` (it prints PATTERN NOT FOUND when upstream moves).
 - Linux, macOS or WSL: GNU make + bash, a `stackql` binary (`$STACKQL`, `./stackql`, then PATH; `bin/start-server.sh` downloads one if none is found), Python 3 and yarn. The Makefile is the operator surface (`make help`). Engine facts in NOTES.md were verified against stackql v0.12.732 (any-sdk v0.6.0-alpha01).
 - The two provider-utils CLI entry points are npm scripts invoked through `node` (never `.bin` shims); flags go after `--`.
 
@@ -91,7 +91,7 @@ Never run tests against a production account.
 
 ## Docs and publish
 
-`make docs` (generate with `--snake-case-aliases`, then `sanitize-docs`) and `make website`; `website/docs` is committed after every regeneration so pages stamp with their regeneration date. Publishing to the registry is a separate, human-in-the-loop step (push the generated provider dir to `providers/src` in a feature branch of `stackql-provider-registry`, follow the release flow, verify with `make smoke-live`).
+`make docs` (generate with `--snake-case-aliases` and `--source-project`, the repository URL in the Makefile variable `SOURCE_PROJECT`, then `sanitize-docs`) and `make website`; `website/docs` is committed after every regeneration so pages stamp with their regeneration date. Publishing to the registry is a separate, human-in-the-loop step (push the generated provider dir to `providers/src` in a feature branch of `stackql-provider-registry`, follow the release flow, verify with `make smoke-live`).
 
 ## Writing conventions
 

Makefile

@@ -29,6 +29,7 @@ VERSION := v00.00.00000
 OPENAPI_DIR := provider-dev/openapi
 SERVICES_DIR := $(OPENAPI_DIR)/src/$(PROVIDER)
 PROVIDER_DIR := $(SERVICES_DIR)/$(VERSION)
+SOURCE_PROJECT ?= https://github.com/stackql-registry/stackql-provider-$(PROVIDER)
 SOURCE_DIR := provider-dev/source
 CONFIG_DIR := provider-dev/config
 GRAPHQL_DIR := provider-dev/source-graphql
@@ -153,13 +154,17 @@ smoke-read-only: venv ## live catalog read only - no evaluation is billed
 
 # -------------------------------------------------------------------- docs
 
-docs: ## generate the website docs (snake_case surface), then sanitize for MDX
+# --source-project (provider-utils >= 0.7.11) adds a "source project" row to the
+# Provider Summary admonition on the landing page, linking the repository name
+# to SOURCE_PROJECT (override it on the command line for a fork).
+docs: ## generate the website docs (snake_case surface, source project link), then sanitize for MDX
 	npm run generate-docs -- \
 	  --provider-name $(PROVIDER) \
 	  --provider-dir ./$(PROVIDER_DIR) \
 	  --output-dir ./website \
 	  --provider-data-dir ./provider-dev/docgen/provider-data \
-	  --snake-case-aliases
+	  --snake-case-aliases \
+	  --source-project $(SOURCE_PROJECT)
 	npm run sanitize-docs
 
 website: ## build the docusaurus microsite (vendors the shared stackql config first)

NOTES.md

@@ -2,7 +2,7 @@
 
 The memory of the build: numbered findings with evidence (what was measured, against what, what was decided and why), the blockers only a live run can resolve, and the testing requirements. A future refresh reads this before touching a rule. Cross-build findings from the sibling providers (see the skill's reference-repos.md) are reused, not re-derived - cited by repo rather than restated.
 
-Sources: the pinned spec snapshot (`provider-dev/downloaded/typesafe-v1.json`, upstream sha256 `a191f8a7df6b...`, fetched 2026-10-02), the vendor documentation (`https://docs.typesafe.ai/llms.txt` is the index; every page serves markdown at its `.md` URL), unauthenticated probes of `api.typesafe.ai` (2026-10-02, before an account existed), the first live run against a dev account with purchased credits (2026-10-05, finding 12), the mock API in `tests/integration/`, stackql v0.12.732 (any-sdk v0.6.0-alpha01) under WSL, `@stackql/provider-utils` 0.7.10, and the anthropic, gemini, openai and supabase sibling builds.
+Sources: the pinned spec snapshot (`provider-dev/downloaded/typesafe-v1.json`, upstream sha256 `a191f8a7df6b...`, fetched 2026-10-02), the vendor documentation (`https://docs.typesafe.ai/llms.txt` is the index; every page serves markdown at its `.md` URL), unauthenticated probes of `api.typesafe.ai` (2026-10-02, before an account existed), the first live run against a dev account with purchased credits (2026-10-05, finding 12), the mock API in `tests/integration/`, stackql v0.12.732 (any-sdk v0.6.0-alpha01) under WSL, `@stackql/provider-utils` 0.7.11, and the anthropic, gemini, openai and supabase sibling builds.
 
 ## Findings
 
@@ -93,7 +93,7 @@ So at this engine version the provider-level block is not consulted (the provide
 
 **Question.** Does the generated documentation show `state`, `model` and `questions` as required for `evaluate`?
 
-**Evidence.** provider-utils 0.7.10 `src/docgen/resource/methods.js getRequiredBodyParams` builds required params from `requestBody.required` only for insert / update / replace / exec access types, and `examples/select-example.js` builds the SELECT example's WHERE from `parameters` only. The anthropic build (`factory/patch-provider-utils.mjs`) and the gemini build hit the same gap on 0.7.7 and 0.7.9 and carry a two-edit patch; the anchors are unchanged in 0.7.10.
+**Evidence.** provider-utils 0.7.10 `src/docgen/resource/methods.js getRequiredBodyParams` builds required params from `requestBody.required` only for insert / update / replace / exec access types, and `examples/select-example.js` builds the SELECT example's WHERE from `parameters` only. The anthropic build (`factory/patch-provider-utils.mjs`) and the gemini build hit the same gap on 0.7.7 and 0.7.9 and carry a two-edit patch; the anchors are unchanged in 0.7.10 and 0.7.11. 0.7.11 (bumped 2026-10-06) changes docgen only: a `--source-project` flag adds a `source project` row to the landing page's Provider Summary admonition, linking the repository name to the URL; `make docs` passes it from the Makefile variable `SOURCE_PROJECT`.
 
 **Decision.** `bin/patch-provider-utils.mjs`, run as the npm `postinstall` hook, applies the same two edits plus a third of its own in `parameters.js` (the body properties of a SELECT-routed naive method are listed in the Parameters table, where the Methods table's required-param links point); all three are idempotent and the script exits non-zero with PATTERN NOT FOUND when upstream moves. With it the `evaluate` page documents `model`, `questions` and `state` as required parameters with the vendor's descriptions, and its generated SELECT example carries them in the WHERE clause. `sanitize-docs.mjs` additionally keeps docgen's `<br />` line breaks in description cells as tags instead of escaping them to text (the two multi-paragraph operation descriptions would otherwise show literal `<br />`). Remove the hook once a provider-utils release includes `select` in the allowlist.
 

README.md

@@ -131,12 +131,12 @@ The smoke suite (`tests/smoke_test.py`, pystackql) mirrors the vendor's quick-st
 ## 6. Docs
 
 ```bash
-make docs        # generate website/docs (snake_case surface) and sanitize for MDX
+make docs        # generate website/docs (snake_case surface, source project link) and sanitize for MDX
 make website     # yarn install && yarn build (vendors the shared stackql/docusaurus-config)
 make website-start
 ```
 
-`provider-dev/docgen/provider-data/headerContent1.txt` is the landing-page front matter and pitch; `headerContent2.txt` is the getting-started page (installation, scope, authentication, evaluations as SELECT, models and aliases, rate limit and retries, example queries). `bin/patch-provider-utils.mjs` (npm `postinstall`) patches provider-utils' docgen so the `evaluate` method documents its three required body fields (in the Methods and Parameters tables) and its SELECT example routes. `website/provider.js` carries the site identity; `website/static/CNAME` the hostname `typesafe-provider.stackql.io`. Commit `website/docs` after every regeneration.
+`provider-dev/docgen/provider-data/headerContent1.txt` is the landing-page front matter and pitch; `headerContent2.txt` is the getting-started page (installation, scope, authentication, evaluations as SELECT, models and aliases, rate limit and retries, example queries). `bin/patch-provider-utils.mjs` (npm `postinstall`) patches provider-utils' docgen so the `evaluate` method documents its three required body fields (in the Methods and Parameters tables) and its SELECT example routes. `website/provider.js` carries the site identity; `website/static/CNAME` the hostname `typesafe-provider.stackql.io`. Commit `website/docs` after every regeneration. The Makefile variable `SOURCE_PROJECT` (default: this repository's GitHub URL) is passed to docgen as `--source-project` and becomes the `source project` link in the landing page's Provider Summary; override it on the `make` command line for a fork.
 
 To publish the site: rename `.github/workflows/prod-web-deploy.yml.disabled` and `test-web-deploy.yml.disabled`, enable GitHub Pages (source: GitHub Actions) and add the DNS record:
 

bin/patch-provider-utils.mjs

@@ -4,7 +4,7 @@
 // hook so a fresh `npm install` / `npm ci` is always patched before
 // `make docs`.
 //
-// Upstream gap (provider-utils 0.7.10, the same in 0.7.7 and 0.7.9): docgen
+// Upstream gap (provider-utils 0.7.11, the same in 0.7.7, 0.7.9 and 0.7.10): docgen
 // builds a method's "Required Params" from `parameters` plus
 // requestBody.required, but ONLY for insert / update / replace / exec access
 // types (src/docgen/resource/methods.js getRequiredBodyParams), and the

package.json

@@ -28,7 +28,7 @@
   "dependencies": {
     "@apidevtools/swagger-parser": "^13.1.0",
     "@stackql/pgwire-lite": "^1.0.2",
-    "@stackql/provider-utils": "^0.7.10",
+    "@stackql/provider-utils": "^0.7.11",
     "js-yaml": "^4.1.0",
     "pluralize": "^8.0.0"
   },

website/docs/index.md

@@ -27,6 +27,7 @@ The `typesafe` provider maps the TypeSafe AI API (`https://api.typesafe.ai`) to
 
 total services: __2__  
 total resources: __2__  
+source project: __[stackql-provider-typesafe](https://github.com/stackql-registry/stackql-provider-typesafe)__  
 
 :::