docsy(v2): document tracked local runs (--tracked / --tracked-strict)

[ppiegaze]

The gap

Regen #1424 published --tracked, --tracked-strict and flyte create config --local-tracked in the generated CLI reference, but no narrative page mentioned any of them. Two pages were actively misleading as a result:

• run-command-options.md opens with "The flyte run command provides the following options:" and an exhaustive table that lists --local but not --tracked.
• running-locally.md and the run-modes comparison table describe local runs as leaving no trace on the control plane, which is exactly what --tracked changes.

Surfaced by the review of #1459, which claimed the four API regens left two narrative gaps. This was a third.

Publish gate: cleared

This PR was drafted on 2026-08-19 under a "do not merge until released" hold. That hold was already stale when it was written, and is now released.

Gate	Evidence
Released	The reporter landed as flyte-sdk@f1f80a69 on 2026-08-11. The first tag containing it is v2.5.20, published to PyPI 2026-08-12 — a week before this PR was drafted. The docs site is pinned at v2.6.13.0.
Reachable	trackedRuns.enabled: true for staging, canary and production in both services: cloud:executions/deploy/values-{staging,canary,production}.yaml (registers TrackedRunService) and cloud:dataproxy/deploy/dataproxy.yaml trackedRunsEnabled (serves tracked-run metadata from the per-env control-plane bucket). No per-org gate.

Verified against fetched origin/main at unionai/cloud@d3f7660474.

What I verified, and where

All against fetched origin/main, not a local checkout and not memory. Re-verified 2026-09-03 against flyte-sdk@1a0d78f7, eleven releases after the original pass; every row still holds.

Claim	Source
--tracked implies --local; needs endpoint, project, domain	src/flyte/cli/_run.py tracked field + _run.py:524-526
--tracked-strict only valid with --tracked; raises otherwise	_run.py:528-529
Reports actions, attempts, phases, inputs, outputs, reports, cache status	src/flyte/_persistence/_remote_reporter.py record_*, _upload_terminal_artifacts
Logs are not reported	no log-link path anywhere in _remote_reporter.py
Best-effort: never fails or blocks the local run	_remote_reporter.py module docstring; bounded retries + bounded terminal flush
Auto-name local-<8 hex>; user names <=30 chars, no leading u/r	generate_tracked_run_name, validate_tracked_run_name (_remote_reporter.py:96-122)
local.tracked / local.tracked_strict config keys	src/flyte/config/_internal.py; cli/_create.py:477,575
Console link printed at start	src/flyte/_run.py; remote/_client/controlplane.py
Tracked runs appear under their own nav section, not in Runs	cloud:clientsv2/src/components/NavPanel/NavItemConfigs.tsx — TrackedRunsLink (display text "Tracked Runs", href /domain/<d>/project/<p>/tracked-runs) is defined separately from RunsLink; the Runs list has no tracked-run handling
flyte run hello runs a built-in example with no files	flyte-sdk#1496, merged 2026-09-01; src/flyte/cli/_hello.py; present in the pinned CLI reference at flyte run hello

Two claims were settled by running the CLI rather than reading it, on flyte 2.6.13 in an empty directory:

$ flyte run --local hello
  Using the built-in example from .../flyte-hello-<user>/task/hello.py
  Completed Local Run   Outputs: ActionOutputs(o0=14.0)

$ flyte run --tracked hello
  Completed Local Run
  Path: https://<tenant>/v2/domain/development/project/<project>/tracked-runs/local-ffa90918
  Outputs: ActionOutputs(o0=14.0)

That confirms both that hello composes with --tracked, and the /tracked-runs/ URL shape.

Design calls made, and why

Tracking is documented as a modifier on local execution, not a fourth run mode. --tracked implies --local and the task still runs in the local Python process, so a peer page next to Local/Devbox/Remote would misrepresent it. It lands as a section in running-locally.md plus an option section in run-command-options.md.

This is the taxonomy problem DOC-1343 predicted: a run that executes on your laptop but registers with the control plane is locally executed and remotely visible, a combination the current Local/Devbox/Remote vocabulary cannot express. DOC-1326 should ratify this framing before it is encoded in style-spec.md.

Gated to the union variant. flyteorg/flyte carries only the flyteidl2 protos and generated stubs for TrackedRunService and has no server implementation; it is implemented in unionai/cloud. Verified no leakage on the rebased build: the flyte variant contains zero occurrences of "tracked" across all three pages, the union variant has them.

No rows added to the shared options table. #1439 established the precedent of documenting Union-only run options in a gated section rather than duplicating the table, and adding union-only rows to a shared table would be a variant-safety bug.

Open question for eng

Self-hosted enablement is undocumented and may not work. (Corrected 2026-09-03: this was previously filed against Self-managed, which was the wrong audience. Self-managed runs the customer's data plane against Union's control plane, where tracked runs is already enabled — see the publish-gate table above. The gap is self-hosted, where the customer operates the control plane too.)

The dataproxy gate trackedRuns.enabled is "Dark by default" (cloud:dataproxy/config/config.go:48-53). The self-hosted control-plane values (cloud:infra/terraform/envs/staging/adam-selfhosted/control-plane/values.yaml) set no trackedRuns key, the chart default is enabled: false (dataproxy/deploy/values.yaml), and the tenant chart exposes only trackedRunsRateLimit, no enablement value. So a self-hosted operator appears to have no supported way to turn this on.

If that is right, the self-hosted deployment docs (#932) need the Helm value and a prerequisite note. Not blocking this PR — the pages here are +union-gated and self-hosted has no published page to carry the caveat yet.

Checks

Full make dist green on the rebased branch (both variants, 1m17s), asset references clean (43,758 checked, 0 missing), variant gating re-verified in the built output. Rendered HTML inspected: the new "Tracked Runs" paragraph and the hello block render as top-level siblings inside the gated section.

Also found

DOC-1439 "Missing documentation for tracked runs feature" (Triage, unlabelled) duplicates DOC-1343. Recommend closing it as Duplicate. Your call, not mine.

---

— docsy · automated docs agent · DOC-1343

[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-1462-docsy-v2-tracked-run.docs-dog.pages.dev
This commit	https://f45574bc.docs-dog.pages.dev
Commit SHA	427b914e64f5ad0d1a2931e557bf7496781f02c5

Updated automatically on every push.

[Copilot]

🟡 Changes recommended

A couple of small documentation clarity issues (missing prerequisite context for --tracked and ambiguous “console” wording in the run-modes table) should be addressed to avoid reader confusion.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR closes a narrative documentation gap for Union-only “tracked local runs” by adding flyte run --tracked/--tracked-strict guidance and updating the local run-mode docs so they no longer imply that local runs are always invisible to the control plane.

Changes:

• Add Union-variant documentation for --tracked / --tracked-strict, including naming rules and flyte create config --local-tracked configuration keys.
• Update the “Run locally in Python” page to describe tracked runs, where they appear in the console UI, and how they behave when reporting fails.
• Update the Union run-modes comparison table to reflect that local runs can be visible in the console when --tracked is used.

File summaries

File	Description
content/user-guide/tasks/task-deployment/run-command-options.md	Adds Union-only sections and option-table entries for tracked local runs and related config keys.
content/user-guide/get-started/run-modes/running-locally.md	Updates the local execution guide to explain tracked runs, visibility in the console, and related commands/links.
content/user-guide/get-started/run-modes/_index.md	Updates the Union run-modes comparison table to reflect console visibility for local runs via --tracked.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Lite

---

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