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>

Author: ppiegaze

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

@@ -48,7 +48,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

@@ -115,6 +115,26 @@ 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 next to your remote runs:
+
+```bash
+flyte run --tracked hello.py main
+```
+
+The command prints a console link when the run 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.
+
+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
@@ -130,6 +150,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

@@ -27,6 +27,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>`**
@@ -78,6 +91,48 @@ 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 it appears in the {{< key product_name >}} console alongside your remote runs. It implies `--local`, so you do not need to pass both:
+
+```bash
+flyte run --tracked my_example.py my_task --input "test_data"
+```
+
+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`. A name you supply must be at most 30 characters and 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>`**