docs: Boost version provenance, OpenAPI spec refresh

_includes/feature-notes/boost.mdx

@@ -1,2 +1,2 @@
-:::info Added in `v1.39`
+:::info Added in `v1.38`
 :::

static/specs/README.md

@@ -19,17 +19,84 @@ its models, so it defines the API rather than describing it after the fact.
 
 ### Refreshing it
 
-**Do not edit this file by hand** — an edited copy would describe an API that
+**Do not edit this file by hand.** An edited copy would describe an API that
 Weaviate does not implement. Replace it whole, from the newest
-`v*/openapi-for-docs` branch:
+`v*/openapi-for-docs` branch.
+
+**A weekly job owns this.**
+[`.github/workflows/openapi_spec_refresh.yml`](../../.github/workflows/openapi_spec_refresh.yml)
+resolves the newest `v*/openapi-for-docs` branch, downloads the spec, checks that
+it really is a Swagger document with paths, and compares it byte for byte against
+the committed copy. When they differ it opens or updates a PR on branch
+`chore/refresh-openapi-spec`, carrying the `info.version` and path-count delta in
+the body so review is a glance rather than a diff of 11,000 lines. It runs
+Sundays at 21:00 UTC and never commits to `main`, so a human still reviews before
+the published API contract changes, and this copy lags upstream by at most a week
+plus review time.
+
+It sorts candidate branches numerically on major and minor version, so it will
+not pin itself to an old release the way a lexical sort would, where `v1-9` sorts
+as greater than `v1-10`.
+
+To refresh without waiting for Sunday, run it from the repository's Actions tab,
+or dispatch it from the command line:
 
 ```bash
-# BRANCH is the whole branch name, slash included: v1-39/openapi-for-docs
-gh api "repos/weaviate/weaviate/contents/openapi-specs/schema.json?ref=${BRANCH}" \
-  -H "Accept: application/vnd.github.raw" > static/specs/weaviate-openapi.json
+gh workflow run openapi_spec_refresh.yml
 ```
 
-Refreshing is manual, so this copy can lag the newest Weaviate release.
+**If the job appears to do nothing**, its header comment records the two usual
+causes. The repository or organization needs "Allow GitHub Actions to create and
+approve pull requests" enabled, or the final step fails with a 403 from
+`gh pr create`. And a push made with `GITHUB_TOKEN` does not start other
+workflows, so the PR it opens arrives without the usual build and link checks.
+Close and reopen that PR to run them before merging.
+
+**Refreshing by hand.** Use this for a one-off or an urgent refresh, or when you
+are debugging the job itself. It is the same sequence the workflow follows.
+
+First find the newest branch. The refspec pattern keeps the versioned branches
+and drops the unversioned `openapi-for-docs`, and `sort -V` orders them
+numerically, putting the newest last:
+
+```bash
+git ls-remote --heads https://github.com/weaviate/weaviate.git "refs/heads/v*/openapi-for-docs" \
+  | awk '{print $2}' | sed 's|refs/heads/||' | sort -V
+```
+
+Then fetch, validate, and only then install:
+
+```bash
+BRANCH=v1-39/openapi-for-docs
+
+gh api "repos/weaviate/weaviate/contents/openapi-specs/schema.json?ref=$BRANCH" \
+  -H "Accept: application/vnd.github.raw" > /tmp/weaviate-openapi.json
+
+python3 -c "
+import json
+spec = json.load(open('/tmp/weaviate-openapi.json'))
+print('version:', spec['info']['version'], '| paths:', len(spec['paths']))
+"
+
+mv /tmp/weaviate-openapi.json static/specs/weaviate-openapi.json
+```
+
+Edit only the branch name after the `=`. Both the assignment and the `$BRANCH`
+reference are correct as written. Do not paste a branch name into a `${...}`
+placeholder instead: `${v1-39/openapi-for-docs}` is not a placeholder but a valid
+parameter expansion, meaning "the value of `$v1`, or `39/openapi-for-docs` if
+`$v1` is unset", so the shell silently asks GitHub for the wrong ref.
+
+**Why the temp file matters.** `>` truncates the target before `gh` runs, and
+`gh api` writes its error body to stdout, so redirecting straight onto
+`static/specs/weaviate-openapi.json` overwrites a good spec with a 141-byte
+GitHub 404 object. `gh` does exit non-zero, but the file is already gone by then.
+Fetching to a temp file keeps the committed copy intact until you have seen what
+arrived.
+
+Check the printed version against the branch you asked for, and the path count
+against the copy you are replacing. `git diff --stat` should then show a
+spec-to-spec diff of a few hundred lines, not a whole-file deletion.
 
 ### Why it is served the way it is