feat(spec): offer object.imageField in Studio's object form beside nameField

[objectstack-fleet]

Fixes #21765

Clause-②: no

Item 3 of the card, under the director seat's ruling A (5989738766): Studio's object form now offers imageField, the record's picture, as a plain text row beside nameField. Items 1 and 2 landed in PR #21824. With this PR, the card's last open item is done.

What changed

• The form row (packages/spec/src/data/object.form.ts): one { field: 'imageField', type: 'text', colSpan: 1, helpText } row directly after nameField. It has the same face as nameField, for the same reason: the value names one of the object's own fields, and the registry has no own-field picker. The row adds no picker and no validator. refuseNonPictureImageField at parse stays the one judge, and its refusal at save is what an author sees. The helpText says what the parse accepts: a field of this object whose type is image or avatar. Left empty, there is no record picture and no placeholder. The metadata form's text input writes no key when cleared (objectui SchemaForm.tsx at the pin 0abd4f9f8769: onChange(e.target.value || undefined)), so "empty" in the helpText means the key is unset, which the parse reads as no picture.

• The stale ledger row (metadata-form-zod-reconciliation.test.ts): the imageField omit row in the declared-not-enforced group is deleted. No other row moves.

• The catalogs: the four packages/platform-objects/src/apps/translations/*.metadata-forms.generated.ts files were regenerated with node scripts/check-i18n-bundles.mjs --write. The zh-CN / ja-JP / es-ES label and helpText leaves were then written in place, since translated-locale values are hand-written in those files (AGENTS.md, Documentation Guardrails). A second --write kept them and dropped the six provenance entries the first extract had added to the three *.source-hashes.generated.ts companions. Those companions are byte-unchanged in this diff.

• The pin (metadata-form-declared-rows.pin.test.ts): three tests. A lit and dark control for the locator. The key is offered once, as a text row with no widget. It sits directly after nameField, in the same section, at the same colSpan. The reconciliation test proves only that the key is offered somewhere on the form; it reads neither the control nor the position, so this pin covers what it misses. No test title or string carries a tracker id.

• Two measured counts in platform-objects were re-taken, both forced by the new row:

  • the object form's open-section leaf population: 114 → 116 (object-collapsed-sections-echo-decisions.test.ts);
  • the catalog-wide translated-label control: 659 → 660 per locale (object-lifecycle-panel-echo-decisions.test.ts).

  The openEchoes reading stays at zero.

• Changeset: @objectstack/spec patch and @objectstack/platform-objects patch (below).

⛔ No Zod change, no liveness change, no new gate or ledger class.

The reconciliation test: predicted, then measured

Predicted before writing: red without the form row, green with it. Measured on the committed state, with scripts/ablation-replace.mjs in wrap mode and a trap restore proven by blob equal to HEAD:

state	reading
row deleted, form row present (this PR, c730a8c598)	2 files, 87 passed (87)
row deleted, form row removed (anchor 1 → 0, blob d867e358e5e5 → a67cdaed2b22)	3 failed / 84 passed: object.(root): accepted by the Zod but unauthorable in the form … expected [ 'imageField' ] to deeply equal [], plus the two new pin tests. Restored: blob d867e358e5e5 == HEAD, git diff HEAD empty
control: the stale row planted back beside the form row	1 failed / 75 passed: object.(root).imageField: the form offers it now — drop the ledger entry. Restored: blob 2a7c49dca958 == HEAD

The first attempt at the control leg was a no-op. The tool refused it before running anything, because the replacement text contained its own anchor. It was redone with a non-overlapping replacement, which is the reading above.

What ships

Each package was built and its dist/ grepped, with a positive control:

• @objectstack/spec: the new helpText is in 8 dist files; the control, nameField's helpText, is in 8.
• @objectstack/platform-objects: the new en helpText is in 6 dist files, the control in 6. The zh-CN, ja-JP and es-ES labels are in 6 each, matched on literal or unicode-escaped text.

Both packages publish the change, so both get patch. skip-changeset does not apply.

Verification (final head 9f6b177875)

• pnpm --filter @objectstack/spec exec vitest run --project local --maxWorkers=2: Test Files 614 passed | 1 skipped (615), Tests 18385 passed | 1 skipped | 1 todo. The skipped file is scripts/root-entry-type-nameability.pin.test.ts, which is gated by OS_EXPECT_ROOT_NAMEABILITY.
• pnpm --filter @objectstack/spec run typecheck: exit 0. tsc -p tsconfig.test.json --listFilesOnly compiles object.form.ts and both changed spec tests.
• pnpm --filter @objectstack/platform-objects exec vitest run --maxWorkers=2: 59 files, 949 passed. Run before the two counts were re-taken, it gave exactly two failures: expected 116 to be 114 and zh-CN positive control: expected 660 to be 659. Typecheck: exit 0.
• metadata-forms-vocabulary.test.ts: 5 passed. pnpm check:i18n: exit 0, platform-objects in sync (11 bundle(s)). pnpm check:i18n-coverage: exit 0, 13 config(s), 621 baselined untranslated string(s), none new.
• pnpm --filter @objectstack/spec run check:generated: exit 0 (15 artifacts).
• Gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 87 commands from 10 paths against the merge base 8832655af. All 87 were run on 9f6b177875. --ran reconciliation: 87 derived famil(ies) accounted for — 87 run, 0 NOT-MEASURED. Four spec gates first exited 3 (PREREQUISITE NOT MET: the dist predated a test-title edit). They exited 0 after pnpm --filter @objectstack/spec build, and the record keeps that last reading.
• eslint --no-inline-config --format json on the 9 changed TS files: 9 files, 0 errors, 0 warnings. The population is eslint.config.mjs:971 (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}). Linting is not type-aware (no parserOptions.project), so untouched files' verdicts cannot move.

Acceptance notes

• Surface, stated. The claim named object.form.ts, the reconciliation test, the four catalogs and a changeset. Three more files changed:
  • metadata-form-declared-rows.pin.test.ts holds the pin the dispatch asked for (item 4).
  • The two platform-objects echo-decision tests carry the counts the row moves. Those count lines are the ones PR feat(spec): give the 45 declared-but-unoffered scalar metadata keys a form row each #19673 moved when it added rows to the same section. A reviewer who reads them as outside the surface can say so.
  • No platform-objects source or object file moved, and no other catalog key changed.
• The authored leaves live in the generated catalogs themselves, so no further file joins the surface for them.
• origin/main gained one commit after the branch point (2799155678, test titles in packages/spec/src/data/). It touches none of this PR's paths.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/data-modeling/objects.mdx (via imageField (literal, a string literal in sections))

What this run could not see

• 2 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 — 138 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 5b2d189e28d5563cbcaa84ac912219017692ea97 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from f4557641cd356d55a85d83df7a06356af149ad51 — the merge of head 9f6b17787539e545969e24b2871a2e1af72a9988 into base 5b2d189e28d5563cbcaa84ac912219017692ea97, 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 f4557641cd356d55a85d83df7a06356af149ad51 && git checkout f4557641cd356d55a85d83df7a06356af149ad51
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 5b2d189e28d5563cbcaa84ac912219017692ea97 9f6b17787539e545969e24b2871a2e1af72a9988 && git checkout -B drift-repro 5b2d189e28d5563cbcaa84ac912219017692ea97 && git merge --no-ff 9f6b17787539e545969e24b2871a2e1af72a9988

node scripts/docs-audit/affected-docs.mjs --json 5b2d189e28d5563cbcaa84ac912219017692ea97

⚠️ 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 5b2d189e28d5563cbcaa84ac912219017692ea97 → pass the list as
args.docs, on the commit named under Which tree this was computed on.