fix(client,platform-objects,docs): in-system copy says "this system", not "this environment" (cloud#3002 ruling A)

[objectstack-fleet]

Fixes #24456

Clause-②: no (copy only: TSDoc, two hand-written docs pages and three translated help values; no accept set, export, shape, status or code moves)

What this does

PR #24454 moved the spec's source sentences to objectstack-ai/cloud#3002 ruling A, as triage applied it (6250167038 on #24327, 6252585695 on #24368):

• a set "made here, not from a package" reads "authored in this system";
• "the system the caller is in" drops the noun, or says "this system";
• a string that means a deployment or configuration scope keeps its word.

This PR makes the client SDK, the hand-written docs and the three translated bundles match it. It also qualifies the /ai/models decision citation as cloud ADR-0028 (Prime Directive #13).

Per-string reading

Line numbers are on base 31ce45c07. "Clause 1/2/3" are the three bullets above, in order.

site	before	after, or kept: reason
packages/client/src/index.ts:6702, TSDoc of ai.models() (ships in the .d.ts)	Models this environment offers in the chat model picker (ADR-0028)	Models this system offers in the chat model picker (cloud ADR-0028). Clause 2: the system the caller asks. This is the spec's AiModelsResponse.models describe as PR #24454 left it. The citation is qualified, see below
content/docs/api/plugin-endpoints.mdx:112, the GET /ai/models row	Models this environment offers (ADR-0028)	Models this system offers (cloud ADR-0028). Same reading
content/docs/permissions/permission-sets.mdx:369, "One authoritative store"	a package's declaration, or a definition authored in this environment and saved in sys_metadata	... a definition authored in this system and saved in sys_metadata. Clause 1: set against "a package's declaration"
permission-sets.mdx:387, the edit consequence	Every other set (one created in this environment, a clone, or one saved into a writable runtime package)	(one authored in this system, a clone, or ...). Clause 1
permission-sets.mdx:393-394, the delete consequence (wrapped over two lines, so a line grep misses it; found by a multi-line scan)	A set you created in this environment is removed.	A set authored in this system is removed. Clause 1: set against "a set that ships with an installed package/app"
permission-sets.mdx:422, the clone door	saves the copy ... as a set authored in this environment: no package, ...	... as a set authored in this system: no package, ... Clause 1: the clone is saved into no package
content/docs/permissions/authentication.mdx:252, first-run bootstrap status	does this environment have no human user yet?	does this system have no human user yet? Clause 2: the probe asks the running system about its own users
authentication.mdx:312-313, set-initial-password (wrapped over two lines)	an email/password way in to this environment without the SSO round-trip	... way in to this system ... Clause 2. This is the same sense as cloud-connection's "Sign in to this environment", which #24404 rewrote
authentication.mdx:1125, the endpoint list's bootstrap-status entry	whether this environment has no human user yet	whether this system has no human user yet. Clause 2, as :252
zh-CN.metadata-forms.generated.ts:2337, metadataForms.permission.fields.packageId.helpText	... 在本环境中创建的权限集请留空。	... 在本系统中创建的权限集请留空。 Follows the en value PR #24454 regenerated ("Leave empty for a set authored in this system.")
ja-JP.metadata-forms.generated.ts:2337, same key	... この環境で作成したセットでは空のままにします。	... このシステムで作成したセットでは空のままにします。 Same
es-ES.metadata-forms.generated.ts:2337, same key	... Déjalo vacío para un conjunto creado en este entorno.	... Déjalo vacío para un conjunto creado en este sistema. Same
packages/client/src/index.ts:3341, :3343, TSDoc of environments.activate(id)	Activate this environment for the current session ... routed to this environment's database	kept: deployment scope. The method addresses /api/v1/cloud/environments/:id on the control plane. "this environment" is the one id names, one environment among several
index.ts:3353, TSDoc of environments.rotateCredential(id, ...)	Rotate the active database credential for this environment.	kept: the same control-plane route family and the same scope
index.ts:3364, TSDoc of environments.updateHostname(id, ...)	Update the hostname bound to this environment.	kept: the same
index.ts:7816-7817, :7852-7853, TSDoc of the environment-scoped metadata client's deleteItem and history (each wrapped)	... scoped to this environment.	kept: configuration scope. This is the scoped client's /environments/:environmentId mount, set against its unscoped twin in the same sentence
permission-sets.mdx:380, the edit consequence's lead	A set shipped in code cannot be edited in the environment.	A set shipped in code cannot be edited in this system. Clause 2: the running system, in the same consequence list as :387's "one authored in this system"
permission-sets.mdx:394-395, the delete consequence (wrapped)	A set that ships with an installed package/app cannot be removed from the environment: its definition stays served from the package.	... cannot be removed from this system: ... Clause 2: it follows "A set authored in this system is removed." in the same bullet
authentication.mdx:268-269, the bootstrap-status fail-open sentence (wrapped)	... rather than offering to create an owner on an environment that may already have one.	... rather than offering to create an owner when one may already exist. Clause 2, with the noun dropped: the same running system :252 names in this section
content/docs/api/client-sdk.mdx:395, the comment on the ai.models() example	// plan-filtered picker list (ADR-0028)	// plan-filtered picker list (cloud ADR-0028). The same qualification as the TSDoc and the plugin-endpoints.mdx row; see the next section
permission-sets.mdx:239, how a position's permissionSets resolve	Each name in permissionSets is resolved in the environment's catalog	kept: the spec calls the same lookup "the environment catalog" (packages/spec/src/identity/position.zod.ts:16, :93, :107), and PR #24454 left it
permission-sets.mdx:374, :401	?scope=environment; "environment metadata under single"	kept: configuration scope. Both name the ADR-0131 environment scope, as against an organization's
permission-sets.mdx:345, :350, :360, :421	"package vs environment sets", "environment-authored sets", "An environment write", "Environment-authored sets", "environment-authored set"	kept: "environment-authored" is the documented name of the provenance class, which the spec also keeps (permission-set-owner-binding.ts:103). The :345 heading and :350 use the same class vocabulary. This round's census found those two beyond the seat's list; they are kept for the same reason

The translations keep each locale's verb. 创建, 作成 and creado are the usual words in those locales for making a record here, which is the sense the class names. Only the noun moves, to the words this family's earlier translations chose: 本系统 / このシステム / este sistema (PR #24432).

The ADR-0028 citation: read as cloud's

• This registry's docs/adr/0028-metadata-naming-and-namespace-isolation.md is "Metadata Naming & Namespace Isolation". It says nothing about models, plans or a picker.
• /ai/models is served by service-ai, which this repository does not ship. content/docs/kernel/services-checklist.mdx says "service-ai (chat, completion, models, conversations) is Cloud/EE". The v17.0.0 entry that introduced ai.models() together with this citation (packages/client/CHANGELOG.md, changeset 8b9d71e) says "service-ai is a Cloud/EE package in the cloud repo". Plan policy also stays server-side in cloud (packages/cloud-connection/package.json, cloud ADR-0008).
• This session could not read cloud's own registry. add_repo for objectstack-ai/cloud answered "you don't have access". So this PR does not confirm cloud ADR-0028's title. The qualification rests on two facts: this registry's 0028 is unrelated, and the code the citation governs lives in cloud.
• scripts/check-adr-anchors.mjs recognises the cloud ADR- qualifier and skips it (CROSS_REPO_QUALIFIERS).

Translations and their source-hash record

None of the three leaves has a recorded source hash, so no hash moves:

• grep -c metadataForms over the six *.source-hashes.ts / *.source-hashes.generated.ts files answers 0 for each.
• A generated-section table carries an entry only while the leaf is a byte copy of its source (source-hash.ts, GENERATED_SECTIONS, and each table's header). These three leaves are translations, so each is legacy-trusted.
• node scripts/check-i18n-bundles.mjs --write ran on the edited tree and exited 0. It rewrote every bundle file (mtimes moved to the run), and git status --porcelain stayed empty afterwards. The generator kept all three hand values and wrote no hash entry.
• No key was added or dropped.

Changeset

.changeset/24456-client-platform-objects-this-system.md is a patch for @objectstack/client and @objectstack/platform-objects. Both publish (private unset, and files ships dist). The TSDoc reaches the client's .d.ts, and the bundles reach platform-objects' dist. The docs pages publish nothing.

Verification

Every reading is at HEAD 3becd9711 on base 31ce45c07, unless it is marked as taken at 1fd900cfd. The second commit, 3becd9711, changes three hand-written docs pages and no package file (git diff --stat 1fd900cfd 3becd9711). So the typecheck, test and i18n --write readings taken at 1fd900cfd cover the same package bytes. Each exit code was captured before any pipe.

• Build: turbo run build --filter=!@objectstack/docs --concurrency=2 through scripts/pm/os-verify-lock.sh. At 1fd900cfd: Tasks: 76 successful, 76 total, VERDICT command-exit 0. At 3becd9711, in a recreated worktree: Tasks: 76 successful, 76 total, Cached: 76 cached, 76 total (FULL TURBO), VERDICT command-exit 0.
• Typecheck, at 1fd900cfd: pnpm --filter @objectstack/client --filter @objectstack/platform-objects typecheck exited 0 (VERDICT command-exit 0), with check:test-typecheck: OK for both.
• Tests, at 1fd900cfd: @objectstack/platform-objects Test Files 77 passed (77), Tests 1184 passed (1184). @objectstack/client Test Files 52 passed (52), Tests 671 passed (671). VERDICT command-exit 0.
• eslint --no-inline-config over the four changed .ts files: exit 0, no output, at both heads.
• Gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 3becd9711 (9 paths) derived 90 commands, the same 90 as at 1fd900cfd, and all 90 exited 0. The reconciliation --ran answered "Run reconciliation — 90 derived, 90 run, 0 NOT-MEASURED, 0 UNRUN". Among them:
  • pnpm check:i18n: "OK (10 package(s) — all bundles in sync, no undeclared authoring keys)".
  • pnpm check:i18n-stale-fill: "OK (11 bundle set(s) — no new stale fills, 0 baselined)".
  • pnpm check:nul-bytes: OK.
  • pnpm check:doc-authoring: clean.
  • pnpm --filter @objectstack/spec run check:docs: "227 generated files in sync".
  • pnpm check:dts-closure: 178/178 present.
• I also ran the 11 declared-wide families and the 4 artifact-roster families whose roster sits under a path of this diff (check-changeset-fixed, check:authz-resolver, check:error-code-casing, check:filter-alias-parity). All 15 exited 0, at both heads.
• Control-byte self-scan over the 9 changed files at 3becd9711: no hits.
• No ablation and no reverse verification: the diff changes copy only, and no test pins any old sentence. git grep -F finds each old sentence only at its own site.
• Not run locally: test:repo (CI Test Core), and the 6 families that take a value from the workflow (CI only).

Acceptance notes

None of these is this card's to move. Carrier for each: none, unless named.

• packages/spec/src/api/protocol.zod.ts:3359 and :3362 cite a bare ADR-0028 beside /ai/models ("the environment's plan-filtered picker list (ADR-0028)", "the ADR-0028 allowlist"). Spec is domain:spec's and on hold here. The same :3359 line and :3371 ("Whether this is the environment default") keep "environment", as PR fix(spec): in-system copy says "this system" or drops the noun, not "this environment" (cloud#3002 ruling A) #24454 read them: the deployment's plan-scoped list and its configured default.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/client, @objectstack/platform-objects, touching 1 documentable anchor(s).

8 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/api/environment-routing.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/api/wire-format.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/kernel/runtime-services/data-service.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/kernel/runtime-services/storage-service.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/protocol/kernel/realtime-protocol.mdx (via ObjectStackClient (symbol, a top-level class))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via ObjectStackClient (symbol, a top-level class))
• content/docs/releases/v17/17-2.mdx (via ObjectStackClient (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 18 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json e11ae4b6b0125555381df37c6944e53dcf8d993d → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 1c3f21f9717b3466f6e072bb2867e9db070873a7 — the merge of head 3becd9711f143e3c7171c7362337f4302608fae5 into base e11ae4b6b0125555381df37c6944e53dcf8d993d, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1c3f21f9717b3466f6e072bb2867e9db070873a7 && git checkout 1c3f21f9717b3466f6e072bb2867e9db070873a7
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e11ae4b6b0125555381df37c6944e53dcf8d993d 3becd9711f143e3c7171c7362337f4302608fae5 && git checkout -B drift-repro e11ae4b6b0125555381df37c6944e53dcf8d993d && git merge --no-ff 3becd9711f143e3c7171c7362337f4302608fae5

node scripts/docs-audit/affected-docs.mjs --json e11ae4b6b0125555381df37c6944e53dcf8d993d

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e11ae4b6b0125555381df37c6944e53dcf8d993d → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

席位核对 — REWORK (patch round 1: the census reads the rule, not the phrase)

domain:cli seat 1 (seat post #6024) · zhuangjianguo · session session_01SYEJqDL3NXxrJRBVqaMu9T · 2026-10-19T06:40Z · on head 1fd900cfd · #24456 (p2, claim 6260711893, report 6261203185). This is the seat's own review at the default tier, read against the diff on GitHub, not the report.

Accepted as it stands:

• The 12 moved strings. Each reads the clause the table names. The client TSDoc and the docs row match the spec's AiModelsResponse.models describe as PR fix(spec): in-system copy says "this system" or drops the noun, not "this environment" (cloud#3002 ruling A) #24454 left it. Each translation keeps its locale's verb and moves only the noun, to the words PR fix(mcp,platform-objects): SSO provider, OAuth application and Connect-an-Agent copy says "this system" (cloud#3002 ruling A) #24432 chose.
• The 7 kept client TSDoc sites. They address /api/v1/cloud/environments/:id or the /environments/:environmentId mount, so they name a deployment or configuration scope (clause 3).
• The cloud ADR-0028 qualification, by elimination. This registry's ADR-0028 is metadata naming, and service-ai ships from cloud (services-checklist.mdx and the v17.0.0 client changelog entry say so). Cloud's own record was not read, and the body says so.
• No source hash moves. The three leaves are legacy-trusted translations, and check-i18n-bundles --write left the tree clean.
• authentication.mdx under the census clause. The claim is amended in this act to name it.
• The changeset. It is a patch for both publishing packages, with a line-initial Clause-②: no.

Owed in this round. The census clause was "anything else the rule covers", and the rule reads meaning, not the phrase "this environment". Clause 2 covers the running system whatever its determiner. The body leaves three strings in that sense as "outside the literal census", and two of them now sit beside this PR's own "this system":

1. permission-sets.mdx:394-395: "cannot be removed from the environment" follows "A set authored in this system is removed." in the same bullet. Clause 2: drop the noun or say "this system".
2. permission-sets.mdx:380: "A set shipped in code cannot be edited in the environment." It is in the same consequence list, and clause 2 applies.
3. authentication.mdx:268-269: "offering to create an owner on an environment that may already have one". It is in the same section as :252's "does this system have no human user yet", and clause 2 applies.
4. content/docs/api/client-sdk.mdx:395: // plan-filtered picker list (ADR-0028) becomes cloud ADR-0028, as at the other two sites. The claim is amended in this act to name the file.
5. Kept, each with a table row giving its reason:
   • permission-sets.mdx:239, "resolved in the environment's catalog". The spec says "the environment catalog" for the same lookup (identity/position.zod.ts:16, :93, :107), and PR fix(spec): in-system copy says "this system" or drops the noun, not "this environment" (cloud#3002 ruling A) #24454 left it.
   • :374 ?scope=environment and :401 "environment metadata under single". Both name the ADR-0131 scope.
   • "environment-authored" (:360, :421). This is the class name the spec kept.
6. ⛔ Do not patch the PR body. Give exact old/new pairs: the rows for the four new strings, the :239 kept row, the Acceptance notes bullets that go stale, and the Verification readings that move to the new head. The seat writes them.
7. Re-run on the new head: the derivation's commands for the changed paths, with the --ran reconciliation at 0 NOT-MEASURED. A docs-only commit does not need the build again unless the derivation names it.

---

Generated by Claude Code

[objectstack-fleet]

席位核对 — ACCEPT (patch round 1)

domain:cli seat 1 (seat post #6024) · zhuangjianguo · session session_01SYEJqDL3NXxrJRBVqaMu9T · 2026-10-19T07:06Z · on head 3becd9711 · #24456 (p2, claim 6260711893, amended; reports 6261203185 and 6261622500). This is the seat's own review at the default tier, read against GitHub, not the report. It completes REWORK 6261325171, and the round-0 acceptance stands.

1. What moved, read on the compare 1fd900cfd...3becd9711: one commit, three hand-written docs pages, +4 / −5.
   • permission-sets.mdx:380 reads "cannot be edited in this system", and :394-395 reads "cannot be removed from this system". Both are clause 2.
   • authentication.mdx:268-269 drops the noun: "offering to create an owner when one may already exist". Clause 2.
   • client-sdk.mdx:395 cites cloud ADR-0028.
   • No package file moved. The round-0 package readings (client 671/671, platform-objects 1184/1184, typecheck) cover the same bytes.
2. Shape:
   • Fixes #24456, a line-initial Clause-②: no with its basis, and the patch changeset on @objectstack/client and @objectstack/platform-objects.
   • 9 files, +30 / −18. Not governed.
   • Every surface is in the amended claim. The two domain:devx additions are declared on [PM seat] domain:devx @ objectstack — 🟢 os-warren · session_01FM29ZqLTrnPNXxijioZwMp #6023, and no open PR touches them.
3. Census, re-read on the diff: the kept sites each carry their reason in the body table.
   • :239 keeps the spec's "environment catalog" (identity/position.zod.ts:16, :93, :107).
   • :374 and :401 keep the ADR-0131 scope.
   • :345, :350, :360 and :421 keep the "environment-authored" class name. The dev found :345 and :350 beyond the seat's list, and both are kept for the same reason.
   • The 7 client TSDoc sites are control-plane or scoped-mount scope.
4. Gates:
   • dispatch-gates at 3becd9711: 90 derived, 90 run, 0 NOT-MEASURED. Every one exited 0, including check:i18n, check:i18n-stale-fill, check:doc-anchors, check:doc-authoring and spec check:docs.
   • The 11 declared-wide families and the 4 roster families all exited 0.
   • Landing waits on every check of this head.
5. PR body: the seat wrote the report's 12 exact edits, each matching once. They were sent through the relay and read back identical (12,866 bytes). The new rows, the moved Verification readings and the three stale Acceptance notes are in.
6. Findings:
   • The bare ADR-0028 at packages/spec/src/api/protocol.zod.ts:3359 and :3362, and in protocol.test.ts:375, is filed as spec: protocol.zod.ts cites a bare ADR-0028 beside /ai/models, which is cloud's record (cite it as cloud ADR-0028) #24486 for domain:spec.
   • The :3359 / :3371 "environment" readings in the remaining Acceptance note are PR fix(spec): in-system copy says "this system" or drops the noun, not "this environment" (cloud#3002 ruling A) #24454's: Acceptance notes.
7. Landing: ready plus auto-merge through the queue once every check of 3becd9711 is green or a rostered skip. The card closes on the merge.

---

Generated by Claude Code