Document SchedulingMetadata for generator and plugin authors

[eric-tramel]

Priority Level

Medium

Epic: #645
Depends on: #641, #646, #653
Related: #646, #653, #654, #657, #660
Target branch: epic/645-async-scheduling while the epic is active.

Source of Truth

Specification details live in PR #658 under plans/645/, especially architecture.md, contracts.md, migration-and-cleanup.md, and issue-map.md. This issue tracks the plugin-facing documentation slice and gates only.

Documentation Scope

Document how generator and plugin authors should use SchedulingMetadata without depending on scheduler internals.

This issue owns:

• when to override get_scheduling_metadata();
• the public meaning of metadata fields that land in Add opt-in SchedulingMetadata for generator resource scheduling #641;
• safe fallback behavior via the final metadata error type, if present;
• examples for custom/model-alias generators;
• clear language that metadata is descriptive input, not admission policy or queue control;
• cross-links to plugin/generator authoring docs and Document async scheduling architecture, capacity, and operations #660 architecture docs.

This issue does not own full operator/developer architecture docs; #660 owns that.

Quality Gates

• Docs match the final Add opt-in SchedulingMetadata for generator resource scheduling #641/Ingest SchedulingMetadata into async scheduler grouping #646/Remove legacy SchedulingHintResolver after SchedulingMetadata ingestion #653 names.
• Docs do not present SchedulingHintResolver, FairTaskQueue, TaskAdmissionController, request-admission internals, or legacy throttle names as plugin APIs.
• Docs include at least one minimal custom generator example and one fallback/error example if the API supports it.
• Docs build/check workflow passes.

Validation

Run the repository docs validation workflow for the touched docs surface. If this lands under fern/, use the DataDesigner docs workflow. Run stale-term searches over docs/current public surfaces for the removed scheduler/request-admission names called out in plans/645/migration-and-cleanup.md.