docs: document spawnableBy agent definitions - #810

What this feature does

The spawnableBy agent definition field controls which factory agents may spawn a target agent, with foreman-only defaults, explicit allowlists, and an empty-list opt-out. Shipped in v0.2026.09.23.14.34.stable_01 (2026-09-23).

Summary

Documents the public spawnableBy Factory definition field on the existing syntax reference page. The wording is grounded in the live public JSON Schema and the production parser and dispatch behavior.

Changes

Factory definition syntax

• Added the field to the agent frontmatter list.
• Documented its array type, declared-agent name validation, uniqueness constraint, omission behavior, empty-list behavior, exact allowlist behavior, and explicit self-spawning.
• Added a focused YAML example.

Verification

• python3 .agents/skills/style_lint/style_lint.py --changed - Passed with no errors; reported three pre-existing unrecognized-term warnings on unchanged lines.
• npm run build - Passed.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only - Passed; 4,309 internal links checked and none broken.
• python3 .agents/skills/doc_quality_policy/check_compression_contract.py src/content/docs/factories/factory-as-code.mdx --content-type reference - Passed.
• git diff --check - Passed.
• trunk check src/content/docs/factories/factory-as-code.mdx - Unavailable because Trunk is not installed in the sandbox.

Unverified claims

None — the field, defaults, allowed references, constraints, and production enablement were verified against the live public schema and source.

Documentation risk

Risk: engineering-review-required
Rationale: Documents the spawnableBy Factory agent definition field, including allowlist and default behavior.
Source files consulted: logic/factoryfile/schema/v1alpha1/agent.schema.json@949d788c66f8fde15869a2976eda67d9303913c4, logic/factoryfile/v1alpha1.go@13231865fc2e3e659dda3c8473603d747fac6a0d, model/types/service_account.go@949d788c66f8fde15869a2976eda67d9303913c4, config/prod.yaml@1158064fa0e2f3ec9986e4722f34af4a810753a9
Engineering review status: pending
Docs override: none

Additional context

• Content design plan omitted because this is a missing entry in an existing reference list, which the docs contract exempts.
• No reviewer requested because source-owner resolution returned no owner for the consulted files.
• Originating request: Slack thread.

Co-Authored-By: Oz oz-agent@warp.dev