docs(agent): Refresh run operations guides

agent/docs/source/explanations/agentapp-runtime.md

@@ -46,7 +46,7 @@ Provider credentials and connector implementations remain outside the FAB.
 ### Model responses
 
 `agent.responses.create(request)` accepts an Open Responses-compatible JSON
-object. The Flower 1.34.0 runtime recognizes:
+object. The Flower 1.35.0 runtime recognizes:
 
 - `model` and `input`
 - `stream`

agent/docs/source/how-to-guides/connect-accounts.md

@@ -9,7 +9,7 @@ The current account connectors are Slack, Notion, GitHub, and Attio. Their
 implemented actions are read-only.
 
 ```{important}
-Flower 1.34.0 supports account connectors only for runs in your personal
+Flower 1.35.0 supports account connectors only for runs in your personal
 workspace. A run that selects account connectors is rejected in a collaborative
 federation. Built-in tools such as `web_search` do not require this connection
 flow.

agent/docs/source/how-to-guides/create-automations.md

@@ -99,7 +99,7 @@ requested one and understands how to stop it.
 
 ## Understand automation scope
 
-The 1.34.0 runtime builds scheduled runs from the current run request. It keeps
+The 1.35.0 runtime builds scheduled runs from the current run request. It keeps
 the automation's runs in the current run series and federation and replaces
 `agent.input` with the scheduled `input`.
 
@@ -151,7 +151,7 @@ already started. Stop that run separately from its run details or with
 `flwr stop <run-id> supergrid`.
 
 There is no public CLI command for listing or stopping automations in Flower
-1.34.0. Use the automation list in SuperGrid.
+1.35.0. Use the automation list in SuperGrid.
 
 ## Recover from a failed schedule
 

agent/docs/source/how-to-guides/run-on-supergrid.md

@@ -1,140 +1,149 @@
 # Run an AgentApp on SuperGrid
 
-Use SuperGrid to submit an AgentApp, follow its progress, inspect its logs, and
-stop it when necessary.
+Submit an AgentApp, choose its federation, follow progress, inspect logs, and
+stop the run when necessary.
 
-If you haven't created an AgentApp yet, start with [Write your first
-AgentApp](../tutorials/write-your-first-agentapp.md).
+Start with [Write your first
+AgentApp](../tutorials/write-your-first-agentapp.md) if you do not have a valid
+AgentApp project. This guide targets Flower 1.35.0.
 
 To run the same app without SuperGrid, see [Run an AgentApp with a local
 SuperLink](run-with-local-superlink.md).
 
 ## Prepare the CLI
 
-Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you
-haven't already, then authenticate with SuperGrid:
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and log in:
 
 ```console
-$ uvx flwr login supergrid
+$ uvx --from flwr==1.35.0 flwr login supergrid
 ```
 
-Your SuperGrid account must have access to the Flower Agent runtime. The
-`supergrid` connection is included in Flower's default CLI configuration.
+Use `uvx --from flwr==1.35.0` for standalone commands. Use `uv run flwr` for
+commands that must load the local project environment.
 
-This guide uses `uvx flwr` for standalone CLI commands and `uv run flwr` for
-commands that need a local project's environment.
+## Validate before submission
 
-If this is your first Flower Agent run, follow [Chat in your
-terminal](../tutorials/get-started-with-flower-agent.md) first. That tutorial
-uses the built-in AgentApp to check your account and CLI setup without a local
-project.
+From the project directory:
 
-## Run a local AgentApp
+```console
+$ uv sync
+$ uv run flwr build
+```
 
-To run your own AgentApp, open a terminal in a project whose `pyproject.toml`
-declares an `agentapp` component:
+Fix configuration, dependency, and component-reference errors locally before
+starting a remote run.
+
+## Run a local AgentApp project
 
 ```console
-$ uv run flwr run . supergrid
+$ uv run flwr run . supergrid --stream
 ```
 
-Flower validates the project, builds a Flower App Bundle, and submits it with
-the run request. Override configured values for one run with `--run-config`:
+Flower builds the project, submits the FAB, prints a run ID, and streams process
+logs. Override a declared configuration value for one run:
 
 ```console
 $ uv run flwr run . supergrid \
-    --run-config 'agent.input="Compare federated learning and centralized learning."'
+    --run-config 'agent.input="Compare federated and centralized AI."' \
+    --stream
 ```
 
-An override key must already exist in the app's
-`[tool.flwr.app.config]` configuration.
+An override key must already exist under `[tool.flwr.app.config]`.
 
-For a longer set of overrides, put them in a TOML file:
+For longer overrides, create `run-config.toml`:
 
 ```toml
-# run-config.toml
 [agent]
-input = "Compare federated learning and centralized learning."
+input = "Compare federated and centralized AI."
 ```
 
-Then pass the file to `--run-config`:
+Then run:
 
 ```console
-$ uv run flwr run . supergrid --run-config run-config.toml
+$ uv run flwr run . supergrid --run-config run-config.toml --stream
 ```
 
-Don't combine a TOML file with inline `--run-config` values in the same command.
+Do not combine a TOML run-config file and inline run-config values.
 
-## Run in another federation
+## Run a published agent
 
-Every SuperGrid account has a default federation, and the commands above use it
-automatically. To run in another federation, pass its full ID:
+Use its app spec instead of a local directory:
 
 ```console
-$ uv run flwr run . supergrid \
-    --federation @<account>/<federation-name> \
-    --run-config 'agent.input="Hello from this federation."'
+$ uvx --from flwr==1.35.0 flwr run @publisher/agent supergrid \
+    --run-config 'agent.input="Explain your task."'
 ```
 
-The account must be a member of the target federation and entitled to start an
-AgentApp run there.
+SuperGrid resolves the app spec to an available version of the app. Availability
+can depend on the target federation.
 
-## Observe the run
+## Choose a federation
 
-Once SuperGrid accepts the request, `flwr run` prints a run ID. Keep it handy:
-you can use it to inspect the status and process logs:
+List the federations visible to your account:
 
 ```console
-$ uvx flwr list --run-id <run-id> supergrid
-$ uvx flwr log <run-id> supergrid
+$ uvx --from flwr==1.35.0 flwr federation list supergrid
 ```
 
-Add `--stream` to the original run command to follow logs immediately:
+Without `--federation`, SuperGrid uses the account default. To choose another
+federation, use its full ID:
 
 ```console
-$ uv run flwr run . supergrid --stream
+$ uv run flwr run . supergrid \
+    --federation @account/federation-name \
+    --run-config 'agent.input="Hello from this federation."'
 ```
 
-Process logs show app output and exceptions. Open the run in the SuperGrid
-dashboard to inspect structured model responses, connector activity, and the
-persisted agent context.
+The account must be a member and entitled to execute AgentApps there.
 
-## Stop a run
+```{important}
+Slack, Notion, GitHub, and Attio connector references are currently accepted
+only for personal-workspace runs. Built-in tools selected by the AgentApp do not
+use the account-connector selection flow.
+```
+
+## Observe the run
 
-Stop an active run with:
+Use the printed run ID:
 
 ```console
-$ uvx flwr stop <run-id> supergrid
+$ uvx --from flwr==1.35.0 flwr list --run-id <run-id> supergrid
+$ uvx --from flwr==1.35.0 flwr log <run-id> supergrid --show
 ```
 
-Flower sends a stop request to SuperGrid and records the stopped run status.
+`flwr log` streams by default. Use `--show` to print the available logs once.
+Open the run in SuperGrid to inspect structured model output, connector
+activity, federation, and persisted context.
 
-## Troubleshoot a failed run
+Process logs are useful for app output and exceptions. Connector activity is a
+better signal than a general **Working** label when diagnosing which child task
+is active.
 
-Start with the detailed status and logs:
+## Stop a run
 
 ```console
-$ uvx flwr list --run-id <run-id> supergrid
-$ uvx flwr log <run-id> supergrid --stream
+$ uvx --from flwr==1.35.0 flwr stop <run-id> supergrid
 ```
 
-Common failures include:
+Wait for the run to reach a stopped terminal state before submitting a
+replacement that could duplicate external work.
+
+Stopping a run does not stop future automation executions. Stop the automation
+separately under **Settings** > **Automations**.
 
-- **Invalid component reference:** confirm that
-  `[tool.flwr.app.components].agentapp` uses `<module>:<attribute>` and resolves
-  to an `AgentApp`.
-- **Invalid run configuration:** define the key under
-  `[tool.flwr.app.config]` before overriding it.
-- **Missing dependency:** add every imported third-party package to
-  `[project].dependencies`.
-- **Unsupported model or connector:** use a model and connector available to
-  the account. Account-backed connectors must be connected and included by the
-  person starting the run.
-- **Federation or entitlement error:** verify the federation ID, membership,
-  and Flower Agent access for the account.
+## Recover from failure
 
-To catch configuration and component-reference errors before submission, run:
+Use [Troubleshoot AgentApp runs](troubleshoot-agent-runs.md) for authentication,
+agent catalog, connector, heartbeat, interruption, and stuck-run recovery.
+
+For a custom app, start with:
 
 ```console
 $ uv run flwr build
+$ uvx --from flwr==1.35.0 flwr list --run-id <run-id> supergrid
+$ uvx --from flwr==1.35.0 flwr log <run-id> supergrid --show
 ```
+
+Keep the run ID, series ID when visible, federation ID, app spec, Flower
+version, and exact public error. Never include credentials or private connector
+content in a support report.

agent/docs/source/how-to-guides/run-with-local-superlink.md

@@ -4,6 +4,9 @@ Run an AgentApp locally with Flower's Community Edition runtime. This setup is
 useful while developing an app: it runs SuperLink and the AgentApp processes on
 your machine, without a SuperGrid account or Enterprise services.
 
+This guide targets Flower 1.35.0. Run the CLI and SuperLink from the same
+project environment to avoid protocol mismatches.
+
 If you haven't created an AgentApp yet, start with [Write your first
 AgentApp](../tutorials/write-your-first-agentapp.md).
 
@@ -35,6 +38,10 @@ You can omit `FLWR_MODEL_API_KEY` when the custom endpoint does not require
 authentication. The model and AgentApp subprocesses inherit these variables
 from SuperLink.
 
+Account connectors configured in SuperGrid are not available to this local
+unauthenticated runtime. Built-in connectors depend on the local runtime and
+provider configuration.
+
 ## Start SuperLink
 
 From your AgentApp project directory, start an insecure local SuperLink:
@@ -106,10 +113,10 @@ $ uv run flwr log <run-id> local-agent --show
 Common problems include:
 
 - **Model API key is not set:** export `FLWR_MODEL_API_KEY` in the SuperLink
-  terminal, then restart SuperLink.
+  terminal, then restart SuperLink
 - **Invalid model endpoint:** `FLWR_MODEL_API_ENDPOINT` must include the full
-  `/responses` path.
+  `/responses` path
 - **Connection refused:** confirm that SuperLink is still running and that the
-  configured address is `127.0.0.1:9093`.
+  configured address is `127.0.0.1:9093`
 - **Version mismatch:** start SuperLink and run the CLI from the same project
-  environment so they use compatible Flower versions.
+  environment so they use compatible Flower versions

agent/docs/source/how-to-guides/troubleshoot-agent-runs.md

@@ -9,8 +9,8 @@ one controlled change makes the cause easier to identify.
 For a CLI-started run, record the run ID and inspect its status and logs:
 
 ```console
-$ uvx --from flwr==1.34.0 flwr list --run-id <run-id> supergrid
-$ uvx --from flwr==1.34.0 flwr log <run-id> supergrid --show
+$ uvx --from flwr==1.35.0 flwr list --run-id <run-id> supergrid
+$ uvx --from flwr==1.35.0 flwr log <run-id> supergrid --show
 ```
 
 In the browser, keep the conversation open and note the visible federation,
@@ -36,7 +36,7 @@ Preserve other connections and settings. Add only the missing section, then run
 **Symptom:** the CLI fails before opening Flower Chat, or SuperGrid asks you to
 sign in again.
 
-1. Complete `uvx --from flwr==1.34.0 flwr login supergrid` again.
+1. Complete `uvx --from flwr==1.35.0 flwr login supergrid` again.
 1. Ensure the browser flow uses the same Flower account that has Agent access.
 1. Retry one deterministic prompt in a new chat.
 
@@ -131,7 +131,7 @@ In Flower Chat, {kbd}`Ctrl+C` during a response requests a stop. Wait until the
 prompt is idle before submitting again. If the old run remains active, use:
 
 ```console
-$ uvx --from flwr==1.34.0 flwr stop <run-id> supergrid
+$ uvx --from flwr==1.35.0 flwr stop <run-id> supergrid
 ```
 
 Start a new conversation if the interrupted app left incomplete tool state that