docs(framework): Document local SuperLink usage

framework/docs/source/docker/run-quickstart-examples-docker-compose.rst

@@ -1,6 +1,6 @@
-:og:description: Beginner’s guide to running Flower quickstart examples with the Deployment Engine using Docker Compose, showcasing its powerful federated learning capabilities.
+:og:description: Beginner’s guide to running Flower quickstart examples with the Deployment Runtime using Docker Compose, showcasing its powerful federated learning capabilities.
 .. meta::
-    :description: Beginner’s guide to running Flower quickstart examples with the Deployment Engine using Docker Compose, showcasing its powerful federated learning capabilities.
+    :description: Beginner’s guide to running Flower quickstart examples with the Deployment Runtime using Docker Compose, showcasing its powerful federated learning capabilities.
 
 ####################################################
  Run Flower Quickstart Examples with Docker Compose
@@ -9,8 +9,8 @@
 Flower provides a set of `quickstart examples
 <https://github.com/adap/flower/tree/main/examples>`_ to help you get started with the
 framework. These examples are designed to demonstrate the capabilities of Flower and by
-default run using the Simulation Engine. This guide demonstrates how to run them using
-Flower's Deployment Engine via Docker Compose.
+default run using the Simulation Runtime. This guide demonstrates how to run them using
+Flower's Deployment Runtime via Docker Compose.
 
 .. important::
 

framework/docs/source/how-to-configure-audit-logging.rst

@@ -102,12 +102,12 @@ Here is an example output when a user runs ``flwr run`` (note the ``"action":
     INFO :      ControlServicer.StartRun
     INFO :      [AUDIT] {"timestamp": "2025-07-12T10:24:21Z", "actor": {"actor_id": "...", "description": "...", "ip_address": "..."}, "event": {"action": "ControlServicer.StartRun", "run_id": "...", "fab_hash": "..."}, "status": "completed"}
 
-Here is another example output when a user runs ``flwr ls``:
+Here is another example output when a user runs ``flwr list``:
 
 .. code-block:: shell
 
     INFO :      [AUDIT] {"timestamp": "2025-07-12T10:26:35Z", "actor": {"actor_id": "...", "description": "...", "ip_address": "..."}, "event": {"action": "ControlServicer.ListRuns", "run_id": null, "fab_hash": null}, "status": "started"}
-    INFO :      ControlServicer.List
+    INFO :      ControlServicer.ListRuns
     INFO :      [AUDIT] {"timestamp": "2025-07-12T10:26:35Z", "actor": {"actor_id": "...", "description": "...", "ip_address": "..."}, "event": {"action": "ControlServicer.ListRuns", "run_id": null, "fab_hash": null}, "status": "completed"}
 
 And here is an example when a SuperNode pulls a message from the SuperLink:

framework/docs/source/how-to-design-stateful-clients.rst

@@ -24,7 +24,7 @@
 
 By design, ClientApp_ objects are stateless. This means that the ``ClientApp`` object is
 recreated each time a new ``Message`` is to be processed. This behavior is identical
-with Flower's Simulation Engine and Deployment Engine. For the former, it allows us to
+with Flower's Simulation Runtime and Deployment Runtime. For the former, it allows us to
 simulate the running of a large number of nodes on a single machine or across multiple
 machines. For the latter, it enables each ``SuperNode`` to be part of multiple runs,
 each running a different ``ClientApp``.

framework/docs/source/how-to-install-flower.rst

@@ -25,8 +25,8 @@ Stable releases are available on `PyPI <https://pypi.org/project/flwr/>`_:
 
     python -m pip install flwr
 
-For simulations that use the Virtual Client Engine, ``flwr`` should be installed with
-the ``simulation`` extra:
+For simulations that use the Simulation Runtime, ``flwr`` should be installed with the
+``simulation`` extra:
 
 ::
 
@@ -95,7 +95,7 @@ versions (alpha, beta, release candidate) before the stable release happens:
 
     python -m pip install -U --pre flwr
 
-For simulations that use the Virtual Client Engine, ``flwr`` pre-releases should be
+For simulations that use the Simulation Runtime, ``flwr`` pre-releases should be
 installed with the ``simulation`` extra:
 
 ::
@@ -111,7 +111,7 @@ The latest (potentially unstable) changes in Flower are available as nightly rel
 
     python -m pip install -U flwr-nightly
 
-For simulations that use the Virtual Client Engine, ``flwr-nightly`` should be installed
+For simulations that use the Simulation Runtime, ``flwr-nightly`` should be installed
 with the ``simulation`` extra:
 
 ::

framework/docs/source/how-to-manage-flower-federations.rst

@@ -1,6 +1,6 @@
-:og:description: Guide to manage Flower federations using the Deployment Engine.
+:og:description: Guide to manage Flower federations using the Deployment Runtime.
 .. meta::
-    :description: Guide to manage Flower federations using the Deployment Engine.
+    :description: Guide to manage Flower federations using the Deployment Runtime.
 
 .. |flower_cli_federation_link| replace:: ``Flower CLI``
 

framework/docs/source/how-to-run-flower-locally.rst

@@ -0,0 +1,195 @@
+:og:description: Learn how local `flwr run` uses a managed local SuperLink, how to inspect runs, stream logs, stop runs, and stop the background local SuperLink process.
+.. meta::
+    :description: Learn how local `flwr run` uses a managed local SuperLink, how to inspect runs, stream logs, stop runs, and stop the background local SuperLink process.
+
+#############################################
+ Run Flower Locally with a Managed SuperLink
+#############################################
+
+When you use a local Flower configuration profile with ``options.*`` and no explicit
+``address``, ``flwr`` does not call the simulation runtime directly. Instead, Flower
+starts a managed local ``flower-superlink`` on demand, submits the run through the
+Control API, and the local SuperLink executes the run with the simulation runtime.
+
+This is the default experience for a profile like the one created automatically in your
+Flower configuration:
+
+.. code-block:: toml
+
+    [superlink.local]
+    options.num-supernodes = 10
+    options.backend.client-resources.num-cpus = 1
+    options.backend.client-resources.num-gpus = 0
+
+If ``FLWR_HOME`` is unset, Flower stores this managed local runtime under
+``$HOME/.flwr/local-superlink``.
+
+****************************
+ What Flower starts for you
+****************************
+
+On the first command that needs the local Control API, Flower starts a local
+``flower-superlink`` process automatically. That process:
+
+- listens on ``127.0.0.1:39093`` for the Control API
+- listens on ``127.0.0.1:39094`` for SimulationIO
+- keeps running in the background after your command finishes
+- is reused by later ``flwr run``, ``flwr list``, ``flwr log``, and ``flwr stop``
+  commands
+
+You can override those default ports with the environment variables
+``FLWR_LOCAL_CONTROL_API_PORT`` and ``FLWR_LOCAL_SIMULATIONIO_API_PORT``.
+
+**************
+ Submit a run
+**************
+
+From your Flower App directory, submit a run as usual:
+
+.. code-block:: shell
+
+    $ flwr run .
+
+Representative output:
+
+.. code-block:: text
+
+    Successfully built flwrlabs.myapp.1-0-0.014c8eb3.fab
+    Starting local SuperLink on 127.0.0.1:39093...
+    Successfully started run 1859953118041441032
+
+Plain ``flwr run .`` submits the run, prints the run ID, and returns. If you want to
+submit the run and immediately follow the logs in the same terminal, use:
+
+.. code-block:: shell
+
+    $ flwr run . --stream
+
+***********
+ List runs
+***********
+
+To see all runs known to the local SuperLink:
+
+.. code-block:: shell
+
+    $ flwr list
+
+To inspect one run in detail:
+
+.. code-block:: shell
+
+    $ flwr list --run-id 1859953118041441032
+
+***********
+ View logs
+***********
+
+To stream logs continuously:
+
+.. code-block:: shell
+
+    $ flwr log 1859953118041441032 --stream
+
+To fetch the currently available logs once and return:
+
+.. code-block:: shell
+
+    $ flwr log 1859953118041441032 --show
+
+Representative streamed output:
+
+.. code-block:: text
+
+    INFO :      Starting FedAvg strategy:
+    INFO :          Number of rounds: 3
+    INFO :      [ROUND 1/3]
+    INFO :      configure_train: Sampled 5 nodes (out of 10)
+    INFO :      aggregate_train: Received 5 results and 0 failures
+    ...
+
+************
+ Stop a run
+************
+
+To stop a submitted or running run:
+
+.. code-block:: shell
+
+    $ flwr stop 1859953118041441032
+
+This stops the run only. It does **not** stop the background local SuperLink process.
+
+*******************************
+ Local runtime files and state
+*******************************
+
+The managed local SuperLink keeps its files in ``$FLWR_HOME/local-superlink/``:
+
+- ``state.db`` stores the local SuperLink state
+- ``ffs/`` stores SuperLink file artifacts
+- ``superlink.log`` stores the local SuperLink process output
+
+These files persist across local runs until you remove them yourself.
+
+*************************************
+ Stop the background local SuperLink
+*************************************
+
+There is currently no dedicated ``flwr`` command to stop the managed local SuperLink
+process. To stop it, first inspect the matching process and then terminate it.
+
+macOS/Linux
+===========
+
+Inspect the process:
+
+.. code-block:: shell
+
+    $ ps aux | grep '[f]lower-superlink.*--control-api-address 127.0.0.1:39093'
+
+Stop the process:
+
+.. code-block:: shell
+
+    $ pkill -f 'flower-superlink.*--control-api-address 127.0.0.1:39093'
+
+Windows PowerShell
+==================
+
+Inspect the process:
+
+.. code-block:: powershell
+
+    PS> Get-CimInstance Win32_Process |
+    >>   Where-Object {
+    >>     $_.CommandLine -like '*flower-superlink*--control-api-address 127.0.0.1:39093*'
+    >>   } |
+    >>   Select-Object ProcessId, CommandLine
+
+Stop the process:
+
+.. code-block:: powershell
+
+    PS> Get-CimInstance Win32_Process |
+    >>   Where-Object {
+    >>     $_.CommandLine -like '*flower-superlink*--control-api-address 127.0.0.1:39093*'
+    >>   } |
+    >>   ForEach-Object { Stop-Process -Id $_.ProcessId }
+
+If you changed the local Control API port with ``FLWR_LOCAL_CONTROL_API_PORT``, replace
+``39093`` in the commands above.
+
+*****************
+ Troubleshooting
+*****************
+
+If a local run fails before it starts, or if the managed local SuperLink does not come
+up correctly, inspect:
+
+.. code-block:: text
+
+    $FLWR_HOME/local-superlink/superlink.log
+
+That log contains the output of the background ``flower-superlink`` process and is the
+first place to check for startup errors, port conflicts, or runtime failures.

framework/docs/source/how-to-run-flower-with-deployment-engine.rst

@@ -1,12 +1,12 @@
-:og:description: Guide to use Flower's Deployment Engine and run a Flower App trough a federation consisting of a SuperLink and two SuperNodes.
+:og:description: Guide to use Flower's Deployment Runtime and run a Flower App through a federation consisting of a SuperLink and two SuperNodes.
 .. meta::
-    :description: Guide to use Flower's Deployment Engine and run a Flower App trough a federation consisting of a SuperLink and two SuperNodes.
+    :description: Guide to use Flower's Deployment Runtime and run a Flower App through a federation consisting of a SuperLink and two SuperNodes.
 
-#######################################
- Run Flower with the Deployment Engine
-#######################################
+########################################
+ Run Flower with the Deployment Runtime
+########################################
 
-This how-to guide demonstrates how to set up and run Flower with the Deployment Engine
+This how-to guide demonstrates how to set up and run Flower with the Deployment Runtime
 using minimal configurations to illustrate the workflow. This is a complementary guide
 to the :doc:`docker/index` guides.
 
@@ -76,8 +76,10 @@ executing ``flwr new``:
 
 .. note::
 
-    If you decide to run the project with ``flwr run .``, the Simulation Engine will be
-    used. Continue to Step 2 to know how to instead use the Deployment Engine.
+    If you decide to run the project with ``flwr run .`` against the default local
+    profile, Flower submits the run to a managed local SuperLink, which then executes it
+    with the Simulation Runtime. Continue to Step 2 to instead point ``flwr run`` at a
+    named SuperLink connection for the Deployment Runtime.
 
 .. tip::
 
@@ -176,10 +178,10 @@ At this point, you have launched two SuperNodes that are connected to the same
 SuperLink. The system is idling waiting for a ``Run`` to be submitted. Before you can
 run your Flower App through the federation we need a way to tell ``flwr run`` that the
 App is to be executed via the SuperLink we just started, instead of using the local
-Simulation Engine (the default). Doing this is easy: define a new SuperLink connection
-in the **Flower Configuration** file, indicate the address of the SuperLink and pass a
-certificate (if any) or set the insecure flag (only when testing locally, real
-deployments require TLS).
+managed local SuperLink workflow used by the default local profile. Doing this is easy:
+define a new SuperLink connection in the **Flower Configuration** file, indicate the
+address of the SuperLink and pass a certificate (if any) or set the insecure flag (only
+when testing locally, real deployments require TLS).
 
 1. Find the Flower Configuration TOML file in your machine. This file is automatically
    create for your when you first use a Flower CLI command. Use ``flwr config list`` to