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

* docs: document tracked local runs (--tracked / --tracked-strict)

Regen #1424 published --tracked, --tracked-strict and
flyte create config --local-tracked in the generated CLI reference, but no
narrative page mentions them. A reader searching the user guide for "tracked"
finds nothing, and running-locally describes local runs as leaving no trace on
the control plane, which --tracked changes.

Document tracking as a modifier on local execution rather than a fourth run
mode, since --tracked implies --local and the task still executes in the local
Python process:

- run-command-options: a --tracked / --tracked-strict section covering what is
  reported (actions, attempts, phases, inputs, outputs, reports, cache status),
  what is not (logs stay in the terminal), the best-effort reporting policy and
  why strict mode exists, the run-name contract (<=30 chars, no leading u or r,
  auto-named local-<id>), and the local.tracked config key.
- running-locally: a "Track local runs in the console" section, plus a note on
  the "What works locally" table, which otherwise implies local runs are
  invisible to the control plane.
- run-modes/_index: the union comparison table listed "No (TUI only)" under
  Flyte UI for local execution, which is no longer accurate.

Gated to the union variant: flyteorg/flyte carries only the flyteidl2 protos
and generated stubs for TrackedRunService, with no server implementation. It is
implemented in the Union control plane.

NOT FOR MERGE until tracked runs is released. Drafted under the publish gate.

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

* docs: scope the tracked-run naming rules as additive

The two rules validate_tracked_run_name enforces (<=30 chars, no leading u or
r) are specific to tracked runs. Phrasing them as the naming contract read as
exhaustive, which would mislead a reader who then hits the separate --name
charset behavior reported in DOC-1425 (unresolved: no eng verdict, and the
constraint is not in the SDK or in Union CreateRun, which rejects only a
leading 'u').

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

* docs: name the Tracked Runs section, and add the zero-file example

Two corrections to the tracked-runs pages, both verified against
unionai/cloud@origin/main and by running the CLI.

Where tracked runs appear. Both pages said a tracked run shows up
"alongside" or "next to" your remote runs, which reads as the Runs list.
It is not: clientsv2/src/components/NavPanel/NavItemConfigs.tsx defines
TrackedRunsLink as its own sidebar item pointing at
/domain/<domain>/project/<project>/tracked-runs, separate from RunsLink,
and the Runs list has no tracked-run handling at all. Running
`flyte run --tracked hello` printed a link ending
/project/<project>/tracked-runs/local-ffa90918. A reader following the
old wording looks in the wrong list, so both pages now name the section.

The zero-file path. `flyte run hello` landed in flyte-sdk #1496 on
2026-09-01 and is already in the pinned CLI reference. It writes a
built-in example to a scratch directory and runs it, so
`flyte run --tracked hello` takes someone from a fresh config to a run
in the console without writing a file first. Verified by execution on
flyte 2.6.13, not by reading: local and tracked both complete with
ActionOutputs(o0=14.0).

Co-Authored-By: docsy <docsy@union.ai>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017CJ89R9ri86y11FFhPdVJV
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>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 3 people

content/user-guide/get-started/run-modes/_index.md

@@ -50,7 +50,7 @@ The same task code runs unchanged across all three modes. Start with local execu
 |--------|-------------------|--------|--------|
 | **⚡️ Execution** | In-process Python | Containerized, local Docker | Containerized, cloud |
 | **🐳 Docker required** | No | Yes | No (remote build) |
-| **💻 Flyte UI** | No (TUI only) | Yes (`localhost:30080`) | Yes |
+| **💻 Flyte UI** | TUI, or the console with `--tracked` | Yes (`localhost:30080`) | Yes |
 | **📦 Container images** | Ignored | Built locally | Built locally or remotely |
 | **🔀 Parallelism** | Sequential | Cluster-level | Cluster-level |
 | **⭐️ Best for** | Fast iteration, debugging | Testing container builds, full Flyte features | Production, GPUs, scale |

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

@@ -122,6 +122,34 @@ persists the inputs and outputs of every task run locally, so you can always go
 flyte start tui
 ```
 
+{{< variant union >}}
+{{< markdown >}}
+
+## Track local runs in the console
+
+A local run normally leaves no trace on the control plane. Add `--tracked` and the run still executes on your machine, but its progress is reported to {{< key product_name >}} so you can watch it in the console:
+
+```bash
+flyte run --tracked hello.py main
+```
+
+Tracked runs appear in the console under **Tracked Runs**, which is its own section in the project sidebar. They are not listed under **Runs**, which shows runs the platform executed for you.
+
+The command prints a link to the run when it starts. Tracking covers the run's actions and attempts, their phases, and their inputs, outputs, reports and cache status. Logs are not reported, so `print()` output stays in your terminal.
+
+Reporting never gets in the way of the run itself: if the control plane is unreachable, the failure is logged and your local run finishes normally.
+
+If you do not have a workflow to hand yet, `hello` runs a built-in one and needs no files at all:
+
+```bash
+flyte run --tracked hello
+```
+
+Use `flyte create config --local-tracked` to track every local run without passing the flag. For the full option reference, including strict reporting and run-name rules, see [Run command options](../../tasks/task-deployment/run-command-options).
+
+{{< /markdown >}}
+{{< /variant >}}
+
 ---
 
 ## What works locally
@@ -137,6 +165,16 @@ Most Flyte features work in both local and remote execution. The table below sum
 | **Plugins** | Same decorators and APIs as remote. Secrets come from environment variables. | [Integrations](../../../api-reference/integrations/_index) |
 | **Secrets** | Read from `.env` files or environment variables. No `flyte create secret` needed. | [Secrets](../../tasks/task-configuration/secrets) |
 
+{{< variant union >}}
+{{< markdown >}}
+
+> [!NOTE] Visibility is the exception
+> With `--tracked`, a local run also reports its state to the control plane and appears in the console.
+> See [Track local runs in the console](#track-local-runs-in-the-console).
+
+{{< /markdown >}}
+{{< /variant >}}
+
 ---
 
 ## Local to devbox/remote

content/user-guide/tasks/task-deployment/run-command-options.md

@@ -29,6 +29,19 @@ The `flyte run` command provides the following options:
 | `--run-project`             |       | text   | *from config*             | Execute deployed task in this project (`deployed-task` only). |
 | `--run-domain`              |       | text   | *from config*             | Execute deployed task in this domain (`deployed-task` only).  |
 
+{{< variant union >}}
+{{< markdown >}}
+
+These additional options are available on {{< key product_name >}}:
+
+| Option             | Short | Type | Default | Description                                                              |
+|--------------------|-------|------|---------|--------------------------------------------------------------------------|
+| `--tracked`        |       | flag | `false` | Run the task locally while reporting run state to the control plane.     |
+| `--tracked-strict` |       | flag | `false` | Fail the run if reporting fails. Requires `--tracked`.                   |
+
+{{< /markdown >}}
+{{< /variant >}}
+
 ## `--project`, `--domain`
 
 **`flyte run --domain <DOMAIN> --project <PROJECT> <PATH>|deployed-task <TASK_NAME>`**
@@ -80,6 +93,54 @@ flyte run my_example.py my_task --input "test_data"
 - **Resource constraints**: When remote resources are unavailable or expensive
 - **Data locality**: When working with large local datasets
 
+{{< variant union >}}
+{{< markdown >}}
+
+## `--tracked`, `--tracked-strict`
+
+**`flyte run --tracked <PATH> <TASK_NAME>`**
+
+The `--tracked` option runs the task on your machine, exactly as `--local` does, while reporting the run's progress to the control plane so that you can follow it in the {{< key product_name >}} console. It implies `--local`, so you do not need to pass both:
+
+```bash
+flyte run --tracked my_example.py my_task --input "test_data"
+```
+
+The run appears under **Tracked Runs** in the project sidebar, a separate section from **Runs**. To try it without writing a file first, use the built-in example:
+
+```bash
+flyte run --tracked hello
+```
+
+Because the run is reported to the control plane, `--tracked` needs an endpoint, project and domain in your configuration, and it cannot be combined with a remote run.
+
+Tracking reports the run's actions and attempts, their phases, and their inputs, outputs, reports and cache status. Logs are not reported: your task's output stays in the terminal where you launched the run.
+
+Reporting is best-effort by design. If the control plane is slow or unreachable, the failure is logged and the local run continues to completion, so tracking never blocks or fails work that would otherwise have succeeded. To debug reporting itself, add `--tracked-strict`, which turns any reporting failure into a loud run failure:
+
+```bash
+flyte run --tracked --tracked-strict my_example.py my_task
+```
+
+`--tracked-strict` is only meaningful together with `--tracked`; enabling it on its own raises an error.
+
+### Naming a tracked run
+
+Tracked runs are named `local-<id>` unless you pass `--name`. Tracking adds two rules on top of the usual `--name` behavior: the name must be at most 30 characters, and it must not begin with `u` or `r`, both of which are reserved for runs the platform names itself. A name that breaks either rule fails before the run starts.
+
+### Tracking every local run
+
+To track local runs without passing the flag each time, write the setting into your config file:
+
+```bash
+flyte create config --local-tracked
+```
+
+This sets the `local.tracked` key, after which `flyte run --local` reports to the control plane on its own. The matching key for strict mode is `local.tracked_strict`.
+
+{{< /markdown >}}
+{{< /variant >}}
+
 ## `--copy-style`
 
 **`flyte run --copy-style [loaded_modules|all|none] <PATH> <TASK_NAME>`**