fix: correct actor.json version examples and clarify input schema linkage

[DaveHanns]

Summary

Three documentation gaps that collectively mis-teach agents and humans writing Actors from scratch:

F35 — dataset_schema page has 3 non-functional 1.0.0 examples

sources/platform/actors/development/actor_definition/dataset_schema/index.md shows three inline actor.json examples with "version": "1.0.0". The platform rejects 3-part SemVer at the admission gate POST /v2/acts/{id}/versions (MAJOR.MINOR only, each 0–99 — empirically reconfirmed 2026-06-21 against throwaway Actor vXEV76d7g0dyKXdPB).

Fix: replace all three with "1.0", plus add a :::warning admonition at the top of the page linking the actor.json reference.

F40 — academy tutorial teaches schema-file creation in isolation

sources/academy/platform/deploying_your_code/input_schema.md walks the reader through creating an input_schema.json file but never mentions how to reference it from .actor/actor.json. Agents extrapolate "the file exists, that's the contract" — relying on the platform's auto-discovery fallback, which is officially deprecated per input_schema/specification.md line 21.

Fix: add a new "Reference the schema in actor.json" section showing both the path-reference (recommended) and inline forms, plus a :::note admonition flagging auto-discovery as deprecated. Inserted between the existing schema example and the "Final thoughts" section.

F40 sub-patch — actor_json.md reference page demotes auto-discovery

sources/platform/actors/development/actor_definition/actor_json.md line 83 (the input field row) treated auto-discovery as an equally-valid path. Reordered the description to lead with the inline-or-path-reference forms, mark them as the recommended pattern, and demote auto-discovery to a backwards-compat note, mirroring the language in specification.md.

Diffstat

sources/academy/platform/deploying_your_code/input_schema.md   | 48 ++++++++++++++++++++++
sources/platform/actors/development/actor_definition/actor_json.md  |  2 +-
sources/platform/actors/development/actor_definition/dataset_schema/index.md  | 12 ++++--
3 files changed, 58 insertions(+), 4 deletions(-)

Verification

grep -n '"version": "1\.0\.0"' sources/platform/actors/development/actor_definition/dataset_schema/index.md
# → returns nothing after this PR

Test plan

• CI green (Docusaurus build)
• Admonition renders cleanly (:::warning and :::note are supported in the existing docs stack)
• Internal anchors {#reference-in-actor-json} and the link to ../actor_json.md resolve

Refs

• chocholous/apify-evals F35, F36, F40
• Companion PR: fix: tighten actor.json version regex to match platform admission apify-shared-js#655 (tighten the regex this doc warns about)

🤖 Generated with Claude Code

[apify-service-account]

✅ Preview for this PR (commit e4b3adf) is ready at https://pr-2662.preview.docs.apify.com (see action run).