docs: name both causes of next: null in the state-introspection prose

[os-zhuang]

Fixes#11049

What

next: null on the state-introspection route has two causes; both published prose sites named only the first. This names both, at each site.

The dispatcher computes the answer as:

constnext=from===undefined ? null : legalNextStates(schema,field,from);

(packages/runtime/src/domains/meta.ts:245, and the same line at packages/rest/src/rest-server.ts:6279.) So null means either no state_machine rule governs the fieldorthe caller omitted ?from=. A reader who calls without from got null and, from the docs, concluded the object declares no state machine. For the skill that misreading is the expensive one: it is the corpus an AI author works from, and the wrong conclusion is "this object has no lifecycle to respect".

Oracle: the repo already asserts the correct semantics on the QA side — docs/qa/platform-checklist/areas/api-backend.json (clause on the dispatcher meta state route): "?from omitted returns next:null (no from ⇒ no transition table), a field with no FSM returns next:null". This PR is prose catching up to a fact the checklist already pins, not an open question.

Scope refinement — the in-code bullet was already correct

The issue lists the state-machine.mdxin-code bullet as part of the defect. Verified against main: it is not. legalNextStates is declared

exportfunctionlegalNextStates(objectSchema: {validations?: unknown[]}|undefined|null,field: string,currentState: string,): string[]|null

currentState is required, and the function returns null only when no matching state_machine rule exists. The from-omitted cause is created by the HTTP dispatcher short-circuiting before it calls the function — it is not a property of the function. Adding "or when ?from= is omitted" to the in-code bullet would have made that line newly wrong. Only the Over HTTP bullet is edited.

Governed surface

This PR touches skills/** (the published skill catalog), so the whole PR is a governed surface: opened as draft, no auto-merge, human merge only. Review requested from @os-zhuang.

Skill file size readings

Budget for the skill file was ≤3 net added lines.

Reading	Before	After	Delta
skills/objectstack-automation/SKILL.md whole file (lines)	984	985	+1
Published bundle, all 11 SKILL.md (lines)	10505	10506	+1
skills/objectstack-automation/SKILL.md (tokens)	12528	12541	+13
Published bundle (tokens)	117907	117920	+13

The binding constraint here was not the line budget but check-skills-token-ratchet — the ceiling for this file is 12543 with only 60 bytes of headroom over the base. A first draft of the skill edit came in 66 bytes over and the ratchet failed it (over by 17 tokens); the wording was tightened rather than the ceiling touched. Ceilings are shrink-only and maintainer-only to loosen — none was modified. Final verdict line:

✓ check-skills-token-ratchet: skills/objectstack-automation/SKILL.md is 12541 tokens (ceiling 12543; headroom 2).
✓ check-skills-token-ratchet: 11 published SKILL.md within their ceilings.

Changeset

Docs/skills prose only — no package behavior changes, nothing to publish. Carried by the skip-changeset label per repo convention rather than a changeset file.

Gates

Families derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack against the actual change set (2 paths) — 19 matched families, all run locally plus check:nul-bytes. All 20 green, run after the final commit at 639babe on a clean tree:

cross-package-test-inputs · doc-anchors · doc-authoring · doc-formula-expressions · doc-security-posture · docs-audit-scope · docs-redirects · spec check:empty-state · spec check:liveness · pm-governed-merges · published-readme-links · role-word · skill-compatibility · skill-frame-sync · spec check:strictness-ledger · spec check:variant-docs · check-cross-package-test-inputs.mjs · check-doc-frontmatter.mjs · check-skills-token-ratchet.mjs · check:nul-bytes

Files changed

• content/docs/protocol/objectql/state-machine.mdx (+1/-1) — the Over HTTP bullet only
• skills/objectstack-automation/SKILL.md (+2/-1) — the existing Introspection parenthetical

Generated by Claude Code

---

Generated by Claude Code