docs: Build, API and operations pages up to ObjectStack 17.7

[objectstack-fleet]

Fixes #330

What this does

Ten English pages are brought up to ObjectStack 17.7.0, the current npm latest. Each claim was checked against the 17.x release notes on objectstack origin/main 54770208. Where a note could disagree with the current docs, the published 17.7.0 tarballs from npm settled it: @objectstack/cli, runtime, rest, objectql, service-automation, formula, spec, service-settings, plugin-auth, core and types. The current objectstack docs already describe 18.0.0-next in places, for example double-brace text holes in flows and .env loading in os migrate. Neither is in 17.7.0, so nothing from those parts of the docs was copied in.

Card rows: fixed or falsified, with the line each rests on

#	Row	Verdict	Where	Rests on
1	Changelog 17.2–17.7; policy row "minors: backward-compatible"	fixed	resources/changelog.mdx	v17/index.mdx (the "minors by version number, not by blast radius" callout); each note's Highlights
2	Per-release upgrade steps	fixed, widened to 17.0–17.7	operate/upgrade.mdx, new ## Version-specific steps at the end; :3 and :6 untouched (#295)	each note's ## Upgrade checklist
3	query.cursor	fixed	reference/rest-api.mdx data table and example	17-0.mdx "The query request surface sheds five inert keys"; 17.7.0 FindDataResponseSchema is object / records / total / hasMore
4	Closed error.code set	fixed	reference/rest-api.mdx Error envelope	17-0.mdx "Error codes are one SCREAMING_SNAKE vocabulary"; 17-1 #9106 (declaredCode)
5	One flow status table	fixed	reference/rest-api.mdx Automation + Flow status table; build/automation/flows.mdx (its trigger URL was already right, so it gains the status table only)	17-1.mdx "The flow doors answer real HTTP statuses"; 17.7.0 runtime classifyFlowRefusal (404 / 409 / 422 / 400)
6	Compound metadata addressing	fixed	reference/rest-api.mdx Metadata	17-3.mdx "Compound metadata addressing is retired"
7	Saved-report stack	fixed in rest-api.mdx and configure/email.mdx:9; falsified for views.mdx:247	—	17-5.mdx: "The report metadata kind, datasets and the analytics service are unchanged". The Console still renders report metadata: objectui packages/plugin-report, a dependency of apps/console. Line 247 points at that surface, not at the removed /api/v1/reports stack, so it stays
8	Public form needs sharing.enabled: true	fixed	reference/rest-api.mdx Public forms (the views.mdx sample already had it)	17-7.mdx "Public forms"
9	end node outcome, refused run status	fixed	build/automation/flows.mdx node table and new "Ending a run" section	17-4 Highlights; the 17.7.0 engine stamps refused at the end node (FlowRefusalSignal)
10	OS_AUTOMATION_SCHEDULED_WORK_ENABLED	fixed, with a caveat	build/automation/flows.mdx Scheduled; reference/environment-variables.mdx Runtime services	17-5.mdx "Scheduled work is off until a deployment turns it on"; 17.7.0 resolveScheduledWorkEnabled (unset means off). Whether the ObjectOS image sets it: NOT MEASURED, no public source. The pages say so plainly
11	Stored flow with a packaged flow's name	fixed	build/automation/flows.mdx Visual builder	17-6.mdx "Flows: one rule decides which flow is packaged"
12	Static readonly stripped on insert too	fixed	build/data/validation-rules.mdx:47	17-4.mdx "A static readonly field is stripped from a non-system INSERT"
13	One-hop lookup; current_user.can()	fixed	validation-rules.mdx new "Reading a related record"; reference/cel.mdx new "Permission checks" and a current_user row	17-5.mdx New capabilities. Measured: 17.7.0 evaluates a validation rule with record and previous only (objectql checkPredicate), so current_user is an unknown variable there and the rule fails closed. The page says so rather than suggesting can() in a rule
14	Localization formats retired	fixed	configure/localization.mdx	17-7.mdx "Four Localization settings are retired"; the 17.7.0 settings manifest has Region and Finance sections
15	OS_ALLOW_LAX_*; OS_PLATFORM_OWNER_EMAIL	fixed	reference/environment-variables.mdx	17-0.mdx (action params, value shapes); 17-3 checklist (walled boot refusal, measured); 17-5.mdx "Identity, sessions and platform administration". Each variable's reader was found in the 17.7.0 code
16	The os migrate family	fixed	reference/cli.mdx, new "Database migrations"	subcommands listed from the 17.7.0 CLI tarball (dist/commands/migrate/*); flags from each command's static flags

Also corrected on the same pages

• validation-rules.mdx: the tip said a broken rule is "logged and skipped". 17.7.0 fails closed instead: "a rule that cannot be evaluated fails closed, it is never skipped". An unevaluable requiredWhen or readonlyWhen refuses the write too (17.5).
• flows.mdx: decision mode: 'inclusive' (17.5), and an api flow needs a config.secret (17.5).
• rest-api.mdx: a by-id write to a row the caller cannot read answers 404 (17.7). /meta/:type/:name/layers replaces the deprecated ?layers=true. The action routes are /actions/:object/:action (plus /:recordId) and /actions/:action, the routes the 17.7.0 runtime mounts.
• environment-variables.mdx: the retired OS_LOCALIZATION_* names, and the in-memory boot store, which is refused (17.7).
• changelog.mdx 17.1, following the seat's note from Access, audit and approval pages predate ObjectStack 17.0–17.6: masking, record-view audit, deactivation, query-door FLS, the guest baseline and approval visibility are missing or wrong #329 / docs: align access, audit and approval pages with ObjectStack 17.0–17.7 #331. Record-view auditing (AuditPlugin's readAudit) and the read-only approval tier (recordReaderVisibleObjects) are switched on only by constructor options the ObjectOS runtime does not set. The 17.1 entry now says ObjectOS does not expose them, instead of linking Audit Logs and Approvals, which (correctly) do not describe them. The 17.6 audit bullet notes 17.7's view_all_audit_log. The 17.4 upgrade step limits the org-less API key refusal to isolated: in the 17.7.0 core, group admits such a key.
• Two items the seat forwarded, folded into this PR:
  • rest-api.mdx: "each action is also exposed to the AI as a tool" was wrong. In 17.7.0 an action reaches agents only when its author sets ai: { exposed: true } with an ai.description of 40 characters or more, on a headless type (script, flow or api): the materialisesAsTool and HEADLESS_ACTION_TYPES checks in the 17.7.0 rest package, and the spec's ActionAiSchema.
  • cli.mdx: os create example was retired in 17.4 (17-4.mdx, #16483). The 17.7.0 CLI's RETIRED_TEMPLATES answers it with an error naming os init and exits 1. The page now documents only os create plugin.
• Release-note links use the canonical host, https://objectstack.ai/docs/releases/v17/17-N. Sources: objectstack apps/docs/lib/site.ts SITE_ORIGIN, and the docs. host listed as a redirecting alias in scripts/check-published-readme-links.mjs. Live fetch: NOT MEASURED, because this container's proxy refuses objectstack.ai.

Locale siblings deleted (the #256 criterion)

13 translated files and 3 generated ones go:

• rest-api: de, es, fr, ja, ko, zh-Hans, plus zh-Hant
• validation-rules: zh-Hans, plus zh-Hant
• email: de, es, fr, ja, ko, zh-Hans, plus zh-Hant

Each English correction removes or reverses a capability claim the sibling still makes:

• rest-api: cursor paging, the /flows/* routes, the /reports/* routes and the sectioned metadata routes.
• validation-rules: "insert exempt" and "a broken rule is skipped".
• email: scheduled-report emails.

gen-zh-hant.mjs pruned the zh-Hant files; none was deleted by hand. No locale file was edited.

Gates (local, on head aaa4eb9)

Gate	Result
node apps/docs/scripts/gen-zh-hant.mjs --check	exit 0: 51 generated files match
npm ci --prefix .github/scripts/doc-samples … then node .github/scripts/check-doc-samples.mjs	exit 0: 79 pages, 101 pass, 10 not a spec sample, 2 opted out. Negative control: a refused end with no message fails the gate (exit 1)
pnpm turbo run type-check --continue (shared lock)	exit 0, cache miss
pnpm turbo run build (shared lock)	exit 0
pnpm turbo run test (shared lock)	exit 0, a cache hit: the ci-scripts tests read no content
check-positioning.mjs / check-locale-surface.mjs / check-search-locales.mjs (after build)	exit 0 / 0 / 0
Ownership (--name-status --no-renames, with TRANSLATION_BOT_LOGIN set for the run)	exit 0: 16 translation artifacts deleted, none added or modified
Freshness / Output	exit 0 / 0
Every new in-page anchor, checked in the built en HTML	21 of 21 present

CI on aaa4eb9: build success, including "Worker bundle fits the size budget" and "The docs site renders — smoke-check a local preview". Node floor success; Ownership & freshness success; Deploy docs skipped (PR).

Acceptance notes

• Out of scope, noted, not filed. reference/runtime-capabilities.mdx:41-52 says a requested capability whose package is missing "logs a warning and continues". The 17.x CLI docs say a declared service capability fails the boot instead. I did not check this against the ObjectOS image. Carrier: none.
• The objectstack docs' automation/flows.mdx callout "the engine and runner halves follow" is stale for the engine half: 17.7.0 stamps refused. That is objectstack's page, not this repo's. Carrier: none.
• A validation rule that names current_user fails closed at run time (measured with the 17.7.0 formula engine). Whether os validate refuses it at authoring is NOT MEASURED.
• Open questions for the seat, all on the ObjectOS image itself:
  • the image's default for OS_AUTOMATION_SCHEDULED_WORK_ENABLED
  • how a Self-Managed operator runs the os migrate data steps and the 17.3 sys_record_share backfill against the licensed image (ObjectStack ships the backfill only as a library function)
  • how the operator rotates the JWT signing keys that 17.7 asks for

---

Generated by Claude Code

[objectstack-fleet]

席位核对

ACCEPT: PR #333 for #330 · 2026-10-16T04:48Z · seat repo:objectos, session session_01CXCwzqwMhkphKoBC11oPSz. Implemented-by: os-dev subagent, branch claude/issue-330-build-api-ops-17x. Reviewed-by: this seat.

Shape.

• Draft, base main (76988da), head aaa4eb9, mergeable_state: clean, assignee os-tesla.
• The first line is Fixes #330. A full-body scan finds no other closing keyword.
• Files: 26 — 10 English pages inside the claim's surface, and 16 deleted locale siblings. +761/−2550, under the 3000-line line. No governed path is touched. operate/upgrade.mdx:3 and :6 are untouched, as the claim required for [Decision] One name for the self-managed edition: "ObjectOS Enterprise" (positioning, 8 pages) vs "ObjectOS Self-Managed" with Business single-node and Enterprise under it (License & Pricing, Deploy) #295.

Checks pinned to aaa4eb9: build success (every step, including docs samples, size budget and the rendered-page smoke check), Node floor success, Ownership & freshness success. Deploy docs skipped (PR event).

Prose, checked against the 17.x release notes on objectstack origin/main and the 17.7.0 tag (4e4e8814):

• Upgrade steps: I spot-checked these against the release notes; each item appears in the release it is filed under.
  • http_request_errors_total (17.2); planSysRecordShareOrganizationBackfill (17.3);
  • "⚠️ The dry run writes" (17.6, notes line 1597);
  • os secret rewrap, account_not_linked, FORM_NOT_FOUND, METADATA_CONFLICT and unmapped-columns (17.7).
  • Release dates: 17.4.0 on 09-09, 17.5.0 on 09-29, 17.6.0 on 10-02 and 17.7.0 on 10-06, all matching npm.
• REST error vocabulary: the closed set is the StandardErrorCode catalog plus the ADR-0112 extension ledger (spec/src/api/error-code-ledger.zod.ts). That ledger registers VALIDATION_FAILED (with fields[], :302) and CONCURRENT_UPDATE, and demotes unregistered spellings to declaredCode (:86-91). The PR's wording ("one closed SCREAMING_SNAKE vocabulary … declaredCode") is accurate.
• Flow codes and the routes:
  • the flow status codes FLOW_DISABLED, FLOW_NO_START_NODE and FLOW_FAILED are present;
  • /meta/:type/:name/layers and /automation/_status are present;
  • hasMore is the list envelope.
• Seat notes folded: the changelog's 17.1 bullets now mark record-view auditing and the read-only approval tier as open-runtime capabilities that ObjectOS does not expose. The REST action-tool claim now states the ai.exposed opt-in, and os create example is recorded as retired.
• Falsified, correctly: the views.mdx:247 row. The report metadata kind survives 17.5, so the page keeps it.

Locale siblings: 16 deleted (rest-api ×7, validation-rules ×2, email ×7). Each English page now removes or reverses a capability claim — cursor paging, the route table, the insert exemption for read-only fields, scheduled reports — so the criterion of ruling 5989567068 holds. The other changed pages have no siblings.

Open questions: three, about the ObjectOS image's own contract (the default of OS_AUTOMATION_SCHEDULED_WORK_ENABLED, the operator entry point for os migrate, and the mechanism for rotating JWT keys). The PR ships the honest caveat on each. They go to the maintainer as one card and do not block this PR.

Landing. Non-governed and under the size line. The seat marks the PR ready. ❗ Merging to main publishes production, and the merge is a human's.

---

Generated by Claude Code

[objectstack-fleet]

维护者速读

这个 PR 共 3311 行（+761 / −2550），超过了 3000 行的人工合并线（2026-09-18 的裁定；objectstack#20153）。其中约 2550 行是删除，主要是删掉那些已经过时、要从英文重新生成的 zh-Hans / zh-Hant 兄弟页。英文正文的改动集中在 changelog 17.2–17.7、升级指南的分版本步骤，以及 rest-api、cel、env-vars、cli、flows、validation-rules、email、localization 这几页。

按规则，席位要等 os-zhuang 或 hotlong 在 GitHub 上提交 Approve 评审之后才能落地；另一种落地方式是维护者自己合并。席位的 ACCEPT 在 6208314656，验收的 head 是 aaa4eb9。

席位自查：这个 PR 不该由席位翻成 ready。翻之前没有跑尺寸闸，这是席位的失误。PR 保持 ready 不动，免得你合并时多点一步。

---

Seat note (English)

This PR is 3311 changed lines, over the 3000-line human-merge line, so it needs an APPROVE review from an account in GOVERNED_APPROVERS (os-zhuang, hotlong) before the seat may land it. A maintainer's own merge is the other landing. Review requested; needs-user-decision added. Seat slip: the PR was flipped ready without the size gate being read first; it stays ready so a maintainer merge is one click.

---

Generated by Claude Code