docsy(v2): document the two narrative gaps left by four API regens

[ppiegaze]

Summary

Closes the narrative half of the accumulated docsy:api-surface-delta backlog: docs#1262, #1373, #1424 (DOC-1362) and #1457 (DOC-1447).

Four regens, two gaps in this PR. Enumerating them was most of the work, because version churn buries the signal — #1457 alone is 309 files, of which 307 of the 366 added lines are version: frontmatter bumps. Strip those and little remains; most of what does was already covered.

[!IMPORTANT] Scope corrected after review
The original framing of this PR ("four regens, two gaps") was too confident on two counts, both found by an independent review of this branch and both now recorded below rather than left implicit.

1. A third gap existed: tracked local runs (--tracked / --tracked-strict / --local-tracked, regen docs(api-reference): regenerate API docs (automated) #1424) had no narrative coverage anywhere. It is now drafted in #1462, held under the publish gate because the feature is unreleased.
2. The backlog is five regens, not four. docs(api-reference): regenerate API docs (automated) #1442 is in the docsy:api-surface-delta label set and was excluded here without explanation. See "The fifth regen" below.

Three defects in this PR's own content were also found and are fixed in the latest commit.

Gap 1 — flyte get devbox (new in 2.6.2)

Verified new, not reworded: present at released tag v2.6.2 (cli/_get.py:864-895), zero occurrences at v2.6.1.

running-devbox.md taught start, stop and delete but gave no way to answer "did it come up?" — which is the reader's question at exactly that point in the page. Added as its own section between starting and configuring, covering --no-probes and flyte -of json-raw get devbox.

Gap 2 — fetching a report after the run

reports.md covered writing a report from inside a task and said nothing about reading one afterwards. That is a different reader task (pull a finished report into a notebook or a CI job) and it was uncovered.

Documents Run.get_report(), the attempt argument, and the .aio variant. It also covers the distinction most likely to bite: Run.get_report() returns the root action's report, so a run whose tasks call other tasks needs Action.get_report() for a nested one. The SDK's own docstring was amended to redirect readers there, and that redirect is what flagged this delta as material in the first place.

Signatures verified against v2.6.2, not inferred: Run.get(name), Action.get(run_name=, name=), Run.get_report(attempt=) with a real .aio attribute.

What was already covered — recorded so it is not redone

Delta	Status
Artifacts (#1373/#1424 headline, 7 new reference pages)	Shipped yesterday as the user-guide artifacts section, #1454
Default pool/queue deletability (#1457)	queues.md already documents the new semantics, including the run.default_queue guard
TaskTemplate, DeployedAppEnvironment (#1262)	Already referenced in how-task-deployment-works.md and how-app-deployment-works.md
AsyncFunctionTaskTemplate (#1262)	Deliberately not documented. Its own docstring says it is "automatically created when an asynchronous function is decorated with the task decorator" — users never write it, so zero narrative mentions is correct, not a gap
Run recovery --recover / --recover-from / --force-rerun-action / --allow-missing-outputs (#1373/#1424)	Uncovered on main, but claimed: in flight as #1439. Omitting it from this table was the record gap, not the work
Tracked local runs --tracked / --tracked-strict / --local-tracked (#1424)	Was missed. Now #1462, held until the feature ships
hf_token_key: str → str | None (#1424)	Was missed. prefetching-models.md sent readers of public models to create a secret they do not need. Fixed in this PR
Grafana agent instrumentation register_instrumentor etc. (#1373/#1424)	Already covered in integrations/grafana-agent-observability/
flyte.load_plugin_config, flyte.load_interactive_ctx (#1424)	Advanced extension surface, deliberately skipped. Recording the decision so the next pass does not re-derive it

The fifth regen (#1442), and why it is not folded in

gh pr list --label "docsy:api-surface-delta" returns #1262, #1283 (v1), #1373, #1424, #1442, #1457. #1442 (2.6.0 → 2.6.1, material) spun DOC-1442, which covered only flyte create config --devbox (shipped as #1453). Its other delta was never dispositioned: flyteplugins.ray.AutoscalerOptionsConfig (new page) and RayJobConfig.autoscaler_options (new parameter).

integrations/ray/_index.md documents enable_autoscaling but has no autoscaler_options row, so the knob that configures the feature the page already teaches is undocumented. That is a real gap.

It is not folded in here because #1458 is currently editing that same page. Folding it in would collide. It gets its own ticket, sequenced after #1458 merges.

Fixes applied after review

Fix	Why
hf_token_key=None documented on prefetching-models.md	The page told every reader to create a secret. Verified at _hf_model.py:883: a falsy hf_token_key attaches no secret
Nested action name in the Action.get_report() example	name="my-subtask" reads as the task's function name. Nested actions are base36(md5(...)), a 25-char generated string, so the example could not resolve. Replaced with a real name, plus flyte get action <run-name> to discover it
flyte get devbox version note	New in 2.6.2 (0 occurrences at v2.6.1, 8 at v2.6.2), while the next section on the page gates --devbox at 2.6.1. A 2.6.1 reader hit "no such command"

One proposed fix was rejected on verification: the nested-action example was to become name="a1", on the grounds that a0, a1, … is established elsewhere in the docs. It is not. interacting-with-runs.md shows only a0 and hedges it as "usually called a0". Only the root action is a0, so a1 would have replaced one wrong example with another.

Note on reviewing regen PRs

Two things make these easy to under-review, worth knowing:

• The GitHub API's files array caps at 100, so docs(api-reference): regenerate API docs (automated) #1457's UI file count understated it by 3× (really 309).
• gh pr diff refuses above 300 files outright, so the diff has to be taken locally from the base and head SHAs. That is the same threshold at which Copilot structurally opts out of regen PRs — the automated reviewer disappears at exactly the size where a human is least likely to read the diff.

---

— docsy · automated docs agent · DOC-1362 · DOC-1447

[github-actions]

GHA build & deploy preview

Built by .github/workflows/build-pr.yml and deployed to the docs CF Pages project by .github/workflows/deploy-pr-preview.yml.

Branch alias	https://pr-1459-docsy-v2-regen-narra.docs-dog.pages.dev
This commit	https://02f3b290.docs-dog.pages.dev
Commit SHA	ae49b1984d86ff025e1c8e3b99a9c38ff88c09b6

Updated automatically on every push.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds documentation for retrieving generated reports via the remote API, checking devbox status via CLI, and prefetching public HuggingFace models without requiring a token/secret.

Changes:

• Document fetching a run/action report HTML via Run.get_report() / Action.get_report() (including attempts and async usage).
• Add a “Check the devbox status” section documenting flyte get devbox and output formats.
• Clarify that public HF models can be prefetched anonymously with hf_token_key=None.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
content/user-guide/tasks/task-programming/reports.md	Adds instructions/examples for fetching reports from completed runs/actions via the remote API.
content/user-guide/get-started/run-modes/running-devbox.md	Documents flyte get devbox status checks, faster checks, and machine-readable output.
content/user-guide/apps/serve-and-deploy-apps/prefetching-models.md	Notes how to prefetch public models without attaching a secret.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.