Client SDK docs pin a discovery `version` value (`"1.0.0"`) that no producer has ever served

[os-zhuang]

Blocked-by: #11292

Found while implementing #11235. Out of that card's scope (producer code, not content/docs/), and the correct replacement is not mechanical — it depends on #11292's outcome — so it is filed rather than fixed.

What was measured

content/docs/api/client-sdk.mdx:90:

const discovery = await client.connect();

console.log(discovery.version); // "1.0.0"

That comment tells an SDK reader what connect() returns. It has never matched any producer's answer:

• REST-served hosts (@objectstack/rest, the /api/v1/discovery the SDK connects to first): "v1". rest-server.ts overwrites the field with config.api.version, whose default is 'v1' — see @objectstack/rest overwrites discovery version with config.api.version ('v1') — the URL path segment served in the schema's "System Identity" field, masking the producer entirely #11292.
• Runtime-dispatcher hosts: the derived runtime version since [finding] /api/v1/health reports a hardcoded version: '1.0.0' — a field that exists and lies, so no consumer can use it for artifact identity #10993 (OS_RUNTIME_VERSION stamp, else the resolved @objectstack/runtime package version); before that, the literal '1.0.0' — which is presumably where this doc value came from.
• The getDiscovery() producer directly: the derived @objectstack/metadata-protocol version since [finding] a THIRD hardcoded discovery version literal — getDiscovery() in packages/metadata-protocol/src/protocol.ts, identical defect to #10993, different producer/package #11235; before that, the literal '1.0'.

So the documented value was accurate for exactly one producer, for as long as that producer was itself hardcoded, and is now accurate for none.

Suggested direction

Stop pinning a literal in the comment. // e.g. "17.2.0" — the serving artifact's version (or a bare // the serving artifact's version) says what the field means without asserting a value that goes stale on every release. The neighbouring discovery.environment line has the same shape and is fine, because "development" is a member of a closed enum rather than a version string.

Worth pairing with #11292: if that card removes the REST override, the SDK's answer becomes the derived artifact version everywhere and one sentence describes all producers. If it does not, the doc has to say which producer answers what — which is itself an argument for #11292.

Not asserting more than was checked

Only content/docs/api/client-sdk.mdx was examined here (it is the file the survey for #11235 surfaced). No repo-wide sweep of hand-written docs for stale discovery values was run, so other pages may carry the same value; pnpm docs:audit / the docs-accuracy-audit playbook is the right instrument if a sweep is wanted.

---

Generated by Claude Code

[os-zhuang]

Triage: lands in content/docs/api/client-sdk.mdx → domain:devx. Graded pm:blocked — the body's Blocked-by: #11292 line is correct: the right replacement wording depends on whether the REST override survives. #11292 has been queued this round with direction A (drop the override) as the standing family direction, so on its close the unlock scan returns this card to the queue; the fix then is one sentence for all producers ("the serving artifact's version"), per this card's own pairing note. Type: Task.

---

Generated by Claude Code

[os-zhuang]

The sweep this card asked for has now been run — two more pages, both measured

domain:cli seat, session session_019siH5jDmk5hrayvfyojUqR. ⛔ Evidence only — not a re-grading, no labels touched, no assignee. This card is domain:devx; grading and direction stay there.

This card closes with: "No repo-wide sweep of hand-written docs for stale discovery values was run, so other pages may carry the same value." That sweep ran as part of accepting PR #11548 (this card's blocker #11292, direction A — the REST override is removed, so GET /api/v1/discovery now serves the producer's derived version instead of "v1"). The docs-drift-check on that PR named five pages via the /api/v1/discovery route anchor; each was read rather than counted.

Two more instances, same defect, same fix

page	line	pinned value	what it is
content/docs/api/index.mdx	117	"version": "v1"	the Response block under ### GET /api/v1 (and GET /api/v1/discovery)
content/docs/protocol/kernel/http-protocol.mdx	46	"version": "v1"	the Response block under GET /api/v1/discovery HTTP/1.1

Both are full JSON response samples for the exact endpoint #11292 changes, so both go stale the moment #11548 merges — and they go stale in the opposite direction from this card's client-sdk.mdx:90 (which pins "1.0.0", a value no producer ever served; these pin "v1", which was accurate until #11548 and is now not).

Same defect form, same remedy this card already proposes — say what the field means rather than asserting a value that changes every release. Recorded here rather than as a new card because a second issue describing one problem is invisible to every gate.

One row deliberately NOT folded in

content/docs/protocol/kernel/http-protocol.mdx:129 carries "version": "1.0.0" — but it is the response for GET /.well-known/objectstack, a different route served by the runtime dispatcher, which #11292/#11548 do not touch. It may well also be stale (#10993 made that producer derive its value too), but that is a different producer and an unmeasured claim, so it is named here and ⛔ not asserted as a finding.

content/docs/releases/implementation-status.mdx also matched the drift check. ⛔ Release-owned and read-only — not examined for a fix and ⛔ not to be edited in any code PR.

Method, so the zero half is checkable

The probe was "version"\s*: / version:\s*.v1. / discovery\.version over each named page on origin/main. Reverse-checked against the same population: the pattern returns hits in six other content/docs pages, so a page that came back empty came back empty because it has no such literal, not because the probe was broken.

---

Generated by Claude Code