docs(agent): Add Flower Hub page

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

@@ -67,7 +67,8 @@ Do not combine a TOML run-config file and inline run-config values.
 
 ## Run a published agent
 
-Use its app spec instead of a local directory:
+After you [find or publish an AgentApp on Flower Hub](use-flower-hub.md), use
+its app spec instead of a local directory:
 
 ```console
 $ uvx --from flwr==1.35.0 flwr run @publisher/agent supergrid \

agent/docs/source/how-to-guides/use-flower-hub.md

@@ -0,0 +1,161 @@
+# Explore and publish AgentApps on Flower Hub
+
+Flower Hub lets you discover AgentApps that you can run on SuperGrid and share
+your own AgentApps with other Flower users. Published apps use an app spec such
+as `@publisher/agent-name`.
+
+## Explore AgentApps
+
+Open the [Flower Hub app catalog](https://flower.ai/apps) and select type
+**Agent** to browse agents. Open an AgentApp to review its description,
+source code, available versions, and app spec before running it.
+
+### Add an AgentApp to a federation
+
+Sign in and open the AgentApp to review its description and source. If you want
+to make it available in a federation, select the **Add app to federation** plus
+button, choose one of your active federations, and select **Confirm**.
+
+Open that federation from the Flower Agent sidebar and select **New chat**.
+The AgentApp is now available in the agent selector above the prompt.
+
+### Run an AgentApp from the terminal
+
+Use the publisher and project name from the app spec:
+
+```console
+$ uvx --from flwr==1.35.0 flwr run @publisher/agent-name supergrid \
+    --run-config 'agent.input="What can you help me with?"' \
+    --stream
+```
+
+See [Run an AgentApp on SuperGrid](run-on-supergrid.md) to choose a federation,
+inspect logs, and stop a run.
+
+## Publish your AgentApp
+
+Start with a working project from [Write your first
+AgentApp](../tutorials/write-your-first-agentapp.md). This guide targets Flower
+1.35.0.
+
+### Prepare the project
+
+Check the public metadata in `pyproject.toml`:
+
+```toml
+[project]
+name = "hello-agent"
+version = "0.1.0"
+description = "Answer questions with a Flower AgentApp"
+license = { file = "LICENSE" }
+dependencies = ["flwr>=1.35.0,<2.0"]
+
+[tool.flwr.app]
+publisher = "your-username"
+display-name = "Hello Agent"
+flwr-version-target = "1.35.0"
+
+[tool.flwr.app.components]
+agentapp = "hello_agent.agent_app:app"
+```
+
+Add a top-level `LICENSE` file containing the license text. FAB format v1
+requires this declared license file and a `flwr` dependency with an inclusive
+lower bound. The target version must satisfy that dependency constraint.
+
+The `publisher` must match your Flower account username. Flower identifies the
+project as an AgentApp from the `agentapp` component, so you do not need to add
+a tag or another app-type setting.
+
+Before publishing:
+
+- choose a final project name because it becomes part of the app spec
+- write a short description that explains what the AgentApp does
+- include a `README.md` with setup, configuration, and usage instructions
+- remove credentials, local data, and private connector content
+- update `.gitignore` so local-only files are excluded
+
+### Validate the AgentApp
+
+Create the environment and build the app locally:
+
+```console
+$ uv sync
+$ uv run flwr build
+```
+
+Fix configuration, dependency, and component-reference errors before
+publishing. A successful build reports the path of the generated `.fab` file.
+The publish command uploads the project sources rather than this local bundle,
+and Flower Hub builds the FAB again on the server.
+
+### Log in to SuperGrid
+
+```console
+$ uv run flwr login supergrid
+```
+
+Complete authentication in the browser window. The signed-in account must
+match the `publisher` value in `pyproject.toml`.
+
+### Review the files, then publish
+
+Before running the publish command, inspect the project for source,
+configuration, documentation, and data files that must not become public. The
+publish filter considers supported files throughout the project, even when
+they are not tracked by Git. Remove any sensitive file or add it to the
+project's `.gitignore`, then review the project again.
+
+Do not use the `Attach:` output from the publish command as a review step. The
+command uploads the attached files immediately after printing their names and
+does not ask for confirmation.
+
+After you have reviewed the eligible files, publish from the project
+directory:
+
+```console
+$ uv run flwr app publish .
+```
+
+Flower applies its publish filters and the project's `.gitignore`, validates
+the files, and sends them to Flower Hub. The uploaded sources are public.
+
+After a successful upload, open:
+
+```text
+https://flower.ai/apps/<publisher>/<project-name>/
+```
+
+For the complete file-type, size, license, and FAB-format rules, see [Publish an
+App on Flower
+Hub](https://flower.ai/docs/hub/how-to-publish-app-on-hub.html).
+
+### Publish a new version
+
+Keep the same project name and publisher, update `[project].version`, and
+publish again:
+
+```toml
+[project]
+version = "0.1.1"
+```
+
+```console
+$ uv run flwr build
+$ uv run flwr app publish .
+```
+
+An app ID cannot change between an Agent and a Federated app. Use a new
+project name if you need to publish a different app type.
+
+### Troubleshoot publishing
+
+- **Please log in before publishing app**: run `uv run flwr login supergrid`
+- **Publisher mismatch**: set `publisher` to the username of the signed-in
+  Flower account
+- **Missing or invalid app description**: add a non-empty `description` under
+  `[project]`
+- **Required file was skipped**: review `.gitignore` and the publish include and
+  exclude rules
+- **Component cannot be loaded**: check the module and object named by
+  `[tool.flwr.app.components].agentapp`

agent/docs/source/index.md

@@ -59,6 +59,7 @@ tutorials/build-a-collaborative-agent
 how-to-guides/use-agents-and-federations
 how-to-guides/connect-accounts
 how-to-guides/create-automations
+how-to-guides/use-flower-hub
 how-to-guides/run-on-supergrid
 how-to-guides/troubleshoot-agent-runs
 how-to-guides/run-with-local-superlink

agent/docs/source/tutorials/write-your-first-agentapp.md

@@ -184,4 +184,6 @@ The app makes one model request and exits. It does not:
 
 Those behaviors belong in AgentApp code rather than appearing automatically.
 Continue with [Build a collaborative research
-agent](build-a-collaborative-agent.md) for a complete, bounded connector loop.
+agent](build-a-collaborative-agent.md) for a complete, bounded connector loop,
+or [publish the AgentApp to Flower
+Hub](../how-to-guides/use-flower-hub.md) so others can run it.