docs: cleanup

README.md

@@ -85,7 +85,7 @@ agentstack run example_agent "Alice"  # Test your agent
 You should see: "Ciao Alice!" 🎉
 
 > [!TIP]
-> Check out [Start Building Agents](https://agentstack.beeai.dev/introduction/start-building-agents) for a complete step-by-step guide to creating your first agent.
+> Check out [Building Agents](https://agentstack.beeai.dev/guides/building-agents) for a complete step-by-step guide to creating your first agent.
 
 ---
 

docs/docs.json

@@ -12,14 +12,17 @@
     "groups": [
       {
         "group": "Introduction",
-        "pages": ["introduction/welcome", "introduction/quickstart"]
+        "pages": [
+          "introduction/welcome", 
+          "introduction/quickstart"
+        ]
       },
       {
         "group": "Deploy to Agent Stack",
         "pages": [
-          "deploy/wrap-existing-agents",
-          "introduction/start-building-agents",
-          "deploy/deploy-your-agents"
+          "guides/wrap-existing-agents",
+          "guides/building-agents",
+          "guides/deploy-your-agents"
         ]
       },
 
@@ -30,32 +33,35 @@
           "guides/messages",
           "guides/multi-turn",
           "guides/files",
-          "extensions/agent-details",
-          "extensions/llm-proxy-service",
-          "extensions/trajectory",
-          "extensions/citations",
-          "extensions/forms",
-          "extensions/agent-settings",
-          "extensions/secrets",
-          "extensions/rag",
-          "extensions/mcp-oauth",
-          "extensions/mcp"
+          "sdk/agent-details",
+          "sdk/llm-proxy-service",
+          "sdk/trajectory",
+          "sdk/citations",
+          "sdk/forms",
+          "sdk/agent-settings",
+          "sdk/secrets",
+          "sdk/rag",
+          "sdk/mcp-oauth",
+          "sdk/mcp"
         ]
       },
       {
         "group": "Guides",
         "pages": [
           "guides/cli-reference",
           "guides/observability",
-          "introduction/connect-a2a-agents"
+          "guides/connect-a2a-agents"
         ]
       },
       {
         "group": "Deploy Agent Stack for Your Team",
-        "pages": ["how-to/deployment-guide", "how-to/remote-cli-guide"]
+        "pages": [
+          "guides/deployment-guide", 
+          "guides/authenticate-cli-to-server"
+        ]
       },
       {
-        "group": "Integrating with Agent Stack",
+        "group": "Advanced Integration",
         "pages": ["guides/connectors"]
       },
 

docs/guides/authenticate-cli-to-server.mdx

@@ -0,0 +1,56 @@
+---
+title: "Connect CLI to Remote Server"
+description: "Connect the Agent Stack CLI to your deployed server"
+---
+
+Use the Agent Stack CLI to configure and manage remote Agent Stack deployments. Agent Stack follows a client-server architecture, where the CLI acts as a client connecting to a deployed Agent Stack server. This allows you to manage agents remotely from your local machine.
+
+## Prerequisites
+
+- Agent Stack CLI installed locally ([Quickstart](/introduction/quickstart))
+- URL of your deployed Agent Stack server
+- Authentication credentials for the server
+
+## Connect to a server
+
+Run this command to connect to a remote server:
+
+```bash
+agentstack server login
+```
+
+The CLI will prompt you for:
+- Server URL
+- Authentication credentials
+
+Once authenticated, the CLI connects to your specified server and saves the connection for future commands.
+
+## View connected servers
+
+List all servers you've connected to:
+
+```bash
+agentstack server list
+```
+
+This shows all saved server connections. The active server is marked in the output.
+
+## Switch between servers
+
+To switch to a different connected server:
+
+```bash
+agentstack server select
+```
+
+Select from your saved connections.
+
+## Disconnect from a server
+
+Remove the currently active server connection:
+
+```bash
+agentstack server logout
+```
+
+This removes the server from your saved connections. To disconnect from a different server, switch to it first, then logout.

docs/guides/cli-reference.mdx

@@ -155,13 +155,22 @@ agentstack build . --dockerfile ./custom.Dockerfile
 
 ### server-side-build
 
-**EXPERIMENTAL:** Build agent from GitHub repository in the platform:
+**EXPERIMENTAL:** Build an agent from a GitHub repository on the platform, instead of locally.
+
+This is useful if you don’t want to set up a local build environment or if you want to ensure the build happens in a consistent, controlled server environment.
 
 ```bash
-agentstack server-side-build <github-url>
+agentstack server-side-build [OPTIONS] <github-url>
 ```
 
-This builds the agent on the server side rather than locally.
+This command clones the GitHub repository, builds the agent image on the platform, and optionally adds the built agent to your workspace.
+
+**Options:**
+| Option                | Description                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `--dockerfile <path>` | Use a custom Dockerfile path. Path should be relative to the repo root or a subdirectory.                  |
+| `--replace <id/name>` | Replace an existing agent. Accepts short agent ID, agent name, or part of the provider location.           |
+| `--add / --no-add`    | After the build completes, automatically add the agent to your Agent Stack instance. Default: `--no-add`. |
 
 ## Model Commands
 

docs/introduction/welcome.mdx

@@ -41,13 +41,13 @@ Your agents request infrastructure services at runtime through A2A protocol exte
   <Card title="Quickstart" icon="rocket" href="/introduction/quickstart">
     Get up and running in one command
   </Card>
-  <Card title="Connect A2A Agents" icon="plug" href="/introduction/connect-a2a-agents">
-    Run existing A2A-compatible agents for instance GUI
+  <Card title="Wrap Existing Agents" icon="box" href="/guides/wrap-existing-agents">
+    Deploy your existing agents to Agent Stack
   </Card>
-  <Card title="Start Building Agents" icon="code" href="/introduction/start-building-agents">
+  <Card title="Build New Agents" icon="code" href="/guides/building-agents">
     Build your first agent with the SDK
   </Card>
-  <Card title="Deploy to Production" icon="server" href="/how-to/deployment-guide">
+  <Card title="Deploy to Production" icon="server" href="/guides/deployment-guide">
     Deploy Agent Stack to Kubernetes for your team
   </Card>
 </CardGroup>