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

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

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

Enumerating them was most of the work, because the version churn hides the
signal: #1457 alone is 309 files, of which 307 of the 366 added lines are
`version:` frontmatter bumps. Stripping those leaves very little, and most of
what remains was already covered.

## flyte get devbox (new in 2.6.2, DOC-1447)

Verified new rather than reworded: present at released tag v2.6.2
(cli/_get.py:864-895), zero occurrences at v2.6.1. The devbox page taught
start, stop and delete but had no way to answer "did it come up?", which is
the question a reader has at exactly that point in the page. Added as its own
section between starting and configuring, with --no-probes and the
`-of json-raw` form.

## Fetching a report after the run (DOC-1362)

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. Also
covers the root-action distinction, which is the part 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, which is the signal that flagged this
delta as material in the first place.

All three signatures verified against v2.6.2 rather than 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

- Artifacts (#1373/#1424's headline delta, 7 new reference pages): shipped
  yesterday as the user-guide artifacts section, docs#1454.
- Default pool/queue deletability (#1457): queues.md already documents the new
  semantics including the run.default_queue guard.
- TaskTemplate and 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.

Co-Authored-By: docsy <docsy@union.ai>
Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>

* docs: fix three defects found reviewing this PR

hf_token_key=None (regen #1424 changed the type to str | None with "Pass None
to prefetch public models anonymously"): prefetching-models still told every
reader to go create a secret, including readers prefetching a public model who
need none. Verified in _hf_model.py:883, where a falsy hf_token_key attaches no
secret to the task.

Action name in the fetch-a-nested-report example: "my-subtask" reads as though
you pass the task's function name. Nested actions are named by
ActionID.new_sub_action_from as base36(md5(parent, inputs hash, task hash, call
seq)), a 25-character generated string, so the example silently fails to
resolve. Replaced with a real generated name and added the discovery command,
flyte get action <run-name>, which the section did not mention.

Note the first fix proposed here was name="a1", on the grounds that a0, a1, ...
is established elsewhere in the docs. It is not: interacting-with-runs shows
only a0 and hedges it as "usually called a0". Only the root is a0, so a1 would
have swapped one wrong example for another.

flyte get devbox version gate: the command is new in 2.6.2 (0 occurrences in
v2.6.1:src/flyte/cli/_get.py, 8 in v2.6.2), and the next section on the same
page gates --devbox at 2.6.1. A 2.6.1 reader following the new section got "no
such command" with no explanation.

Co-Authored-By: docsy <docsy@union.ai>
Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>

---------

Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
Co-authored-by: docsy <docsy@union.ai>

Author: ppiegaze

content/user-guide/apps/serve-and-deploy-apps/prefetching-models.md

@@ -61,6 +61,8 @@ If the model requires authentication:
 The default value for `hf_token_key` is `HF_TOKEN`, where `HF_TOKEN` is the name of the Flyte secret containing your
 HuggingFace token. If this secret doesn't exist, you can create a secret using the [flyte create secret CLI](../../tasks/task-configuration/secrets).
 
+Public models need no token at all. Pass `hf_token_key=None` to prefetch anonymously, and no secret is attached to the prefetch task.
+
 ### With resources
 
 By default, the prefetch task uses minimal resources (2 CPUs, 8GB of memory, 50Gi of disk storage), using

content/user-guide/get-started/run-modes/running-devbox.md

@@ -84,6 +84,31 @@ This pulls the necessary containers and starts a local Flyte instance. Once read
 The first start may take a few minutes while Docker images are downloaded.
 {{< /note >}}
 
+## Check the devbox status
+
+> [!NOTE]
+> `flyte get devbox` requires flyte 2.6.2 or later.
+
+To see whether the devbox is up, and where it is:
+
+```bash
+flyte get devbox
+```
+
+This reports the run state, the UI and image registry endpoints, the container image version in use, and where the cluster keeps its state on disk. It is the quickest way to tell a devbox that is still starting from one that is ready.
+
+Add `--no-probes` to skip the readiness probe and the container resource sample, which makes the check faster and works offline:
+
+```bash
+flyte get devbox --no-probes
+```
+
+For a machine-readable report, pass an output format to the top-level command:
+
+```bash
+flyte -of json-raw get devbox
+```
+
 ## Configure
 
 Create a config file that points to the devbox:

content/user-guide/tasks/task-programming/reports.md

@@ -187,3 +187,46 @@ if __name__ == "__main__":
 > The report contains only what you explicitly `log()` or `replace()`. Returning a value whose type has a renderer attached does **not** by itself add it to the report — render the value and log the HTML, as shown above.
 
 Flyte's SDK also implements a few renderers of this kind internally — for pandas and PyArrow DataFrames and for Markdown strings. These aren't exposed as public API (only the `flyte.types.Renderable` protocol is), so treat them as examples of the same pattern rather than importable helpers.
+
+## Fetching a report after the run
+
+Everything above is about *writing* a report from inside a task. To *read* a finished report from outside the run, for example to embed it in a notebook or attach it to a CI job, fetch it through the remote API:
+
+```python
+import flyte
+from flyte.remote import Run
+
+flyte.init_from_config()
+
+run = Run.get("my-run-name")
+html = run.get_report()
+```
+
+`get_report()` returns the report as an HTML string. It requests a signed download link for the report artifact and downloads the contents, so the call needs an initialized client.
+
+By default it returns the report for the latest attempt. Pass `attempt` to fetch an earlier one:
+
+```python
+html = run.get_report(attempt=1)
+```
+
+`Run.get_report()` returns the report of the run's **root action**. A run whose tasks call other tasks has a report per action, so to fetch the report for a nested action, use `flyte.remote.Action.get_report()` on that action instead:
+
+```python
+from flyte.remote import Action
+
+action = Action.get(run_name="my-run-name", name="6n505tdw46zu7fpmgtui1r1uw")
+html = action.get_report()
+```
+
+Nested actions are named deterministically from the parent action, the task identity, the inputs and the call sequence, so the name is a generated string rather than the task's function name. List the actions in a run to find the one you want:
+
+```bash
+flyte get action my-run-name
+```
+
+Both are synchronous by default. From async code, call the `.aio` variant:
+
+```python
+html = await run.get_report.aio()
+```