Update quickstarts, install, and CLI reference

assets/ar-docs/setup-docker.md

@@ -0,0 +1,36 @@
+1. Install the agentregistry `arctl` binary on your local machine.
+   ```sh
+   curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash
+
+   export PATH="/usr/local/bin:$PATH"
+   ```
+
+2. Verify that the CLI is installed correctly.
+   ```sh
+   arctl version
+   ```
+
+3. Download the Docker Compose file that matches your installed `arctl` version.
+   ```sh
+   export VERSION="$(arctl version | awk 'NR == 1 { print $3 }')"
+   curl -fsSLo agentregistry-compose.yml \
+     "https://raw.githubusercontent.com/agentregistry-dev/agentregistry/${VERSION}/docker/docker-compose.yml"
+   ```
+
+4. Start the agentregistry server and its bundled PostgreSQL database.
+   ```sh
+   docker compose -f agentregistry-compose.yml up -d --wait
+   ```
+
+   Example output: 
+   ```console
+   [+] Running 4/4
+    ✔ Network agentregistry_agentregistry-network  Created                                                                                                                                                                                 0.0s 
+    ✔ Volume agentregistry_postgres_data           Created                                                                                                                                                                                 0.0s 
+    ✔ Container agent-registry-postgres            Healthy                                                                                                                                                                                 6.3s 
+    ✔ Container agentregistry-server               Healthy    
+    ```
+
+5. [Open the agentregistry UI](http://localhost:12121/) in your browser. The UI is automatically exposed on port 12121 on your local machine.
+
+   {{< reuse-image src="img/ar-local.svg" width="800px" srcDark="img/ar-local-dark.svg" >}}

content/docs/install/docker.md

@@ -6,7 +6,7 @@ description: "Install agentregistry for local development with Docker to build,
 
 Use this guide to install agentregistry for local development with Docker. This approach is useful if you want to run agentregistry from your local machine, an on-prem environment, or a VM. Agentregistry is spun up using Docker containers and you can use this installation to build, publish, and deploy AI artifacts to your local environment and Kubernetes clusters.
 
-To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/install/kubernetes) guide.
+To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/install/kubernetes/) guide.
 
 ## Before you begin
 
@@ -18,41 +18,7 @@ To install agentregistry in a Kubernetes cluster instead, see the [Install in Ku
 
 ## Install
 
-1. Install the `arctl` binary on your local machine. The binary is automatically added to `/usr/local/bin/arctl`.
-   ```sh
-   curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash
-   ```
-
-2. Start the agentregistry daemon. This starts the Docker containers that power agentregistry.
-   ```sh
-   arctl daemon start
-   ```
-
-   Example output:
-   ```console
-   Starting agentregistry daemon...
-   ✓ agentregistry daemon started successfully
-   ```
-
-3. Verify the installation by checking the version.
-   ```sh
-   arctl version
-   ```
-
-   Example output:
-   ```console
-   arctl version v0.3.3
-   Git commit: 89dc215
-   Build date: 2026-04-02
-   Server version: v0.3.3
-   Server git commit: 89dc215
-   Server build date: 2026-04-02
-   ```
-
-4. [Open the agentregistry UI](http://localhost:12121/) in your browser. The UI is automatically exposed on port `12121` when the daemon starts.
-
-   {{< reuse-image src="img/ar-local.png" width="800px" >}}
-   {{< reuse-image-dark srcDark="img/ar-local-dark.png" width="800px" >}}
+{{< reuse "ar-docs/setup-docker.md" >}}
 
 ## Next steps
 
@@ -62,3 +28,4 @@ With agentregistry up and running, you can explore how to build, publish, and de
 * [**MCP servers**](/docs/mcp/): Create and run MCP tool servers, add tools, and publish them as Docker images.
 * [**Skills**](/docs/skills/): Build and publish skills that you can add to your agents.
 * [**Prompts**](/docs/prompts/): Build and publish prompts that you can add to your agents.
+* [**BYO PostgreSQL database**]({{< link path="/operations/database/" >}}): Replace the bundled PostgreSQL instance with an external database for production use.

content/docs/install/kubernetes.md

@@ -1,13 +1,13 @@
 ---
-title: Install in Kubernetes
+title: Install on Kubernetes
 weight: 20
 description: "Install agentregistry in a Kubernetes cluster with Helm for shared team access to a central artifact registry."
 ---
 
 Use this guide to install agentregistry in a Kubernetes cluster by using Helm. This approach is useful for team environments where multiple developers need shared access to a central artifact registry.
 
 > [!NOTE]
-> If you install agentregistry in a Kubernetes cluster, you cannot deploy AI artifacts to a local environment. To deploy them to a local environment, you must [install agentregistry locally with Docker](/docs/install/docker). 
+> If you install agentregistry in a Kubernetes cluster, you cannot deploy AI artifacts to a local environment. To deploy them to a local environment, you must [install agentregistry locally with Docker](/docs/install/docker/).
 
 ## Before you begin
 
@@ -16,67 +16,55 @@ Make sure you have the following tools installed:
 - [kubectl](https://kubernetes.io/docs/tasks/tools/) with access to a Kubernetes cluster
 - [Helm](https://helm.sh/docs/intro/install/) v3 or later
 
-## Set up PostgreSQL
-
-Agentregistry requires an external PostgreSQL instance with the [pgvector](https://github.com/pgvector/pgvector) extension for Kubernetes deployments.
-
-> [!WARNING]
-> The bundled PostgreSQL setup is intended for development and testing only. For production, use a managed PostgreSQL service or a production-grade operator.
-
 ## Install with Helm
 
-Install agentregistry using the Helm chart from the GitHub Container Registry.
-
-```sh
-helm upgrade -i agentregistry oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \
-    --namespace agentregistry \
-    --create-namespace \
-    --set config.jwtPrivateKey=$(openssl rand -hex 32) \
-    --set image.tag=v0.3.3 \
-    --set database.host=postgres-pgvector.agentregistry.svc.cluster.local \
-    --set database.password=agentregistry \
-    --set database.sslMode=disable
-```
+The Helm chart includes a bundled PostgreSQL instance for development and evaluation. For production, [bring your own PostgreSQL instance]({{< link path="/operations/database/" >}}) instead.
 
-If you are using an external PostgreSQL instance, replace `database.host`, `database.password`, and `database.sslMode` with values for your database.
-
-Verify that the pods are running.
-
-```sh
-kubectl get pods -n agentregistry
-```
+1. Install agentregistry with the bundled PostgreSQL instance. 
+   ```sh
+   helm upgrade -i agentregistry oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \
+       --namespace agentregistry \
+       --create-namespace
+   ```
 
-### Helm chart configuration
+   > [!WARNING]
+   > The bundled PostgreSQL instance is for development and evaluation only. Data is lost if the PostgreSQL pod is restarted or rescheduled. For production, use an external PostgreSQL instance instead. See the [BYO PostgreSQL database]({{< link path="/operations/database/" >}}) guide.
 
-| Value | Description | Default |
-|---|---|---|
-| `database.host` | PostgreSQL hostname | — |
-| `database.password` | Database password | — |
-| `database.sslMode` | SSL mode (`disable`, `require`, `verify-full`) | — |
-| `config.jwtPrivateKey` | JWT signing key (use a securely generated random value) | — |
+2. Verify that the agentregistry and PostgreSQL pods are up and running. 
+   ```sh
+   kubectl get pods -n agentregistry
+   ```
 
-## Access the UI
+   Example output: 
+   ```console
+   NAME                                       READY   STATUS    RESTARTS   AGE
+   agentregistry-c46b8bd98-hvnzf              1/1     Running   0          45s
+   gentregistry-postgresql-9858cbcbf-tk7p9   1/1     Running   0          45s
+   ```
 
-1. Port-forward the agentregistry service to access the UI and API from your local machine:
+3. Port-forward the agentregistry service to access the UI and API from your local machine. 
    ```sh
    kubectl port-forward -n agentregistry svc/agentregistry 12121:12121
    ```
 
-2. [Open the agentregistry UI](http://localhost:12121/) in your browser.
+4. [Open the agentregistry UI](http://localhost:12121/) in your browser.
 
-## Install arctl
+### Install the `arctl` CLI
 
-Install the `arctl` CLI to interact with agentregistry from your local machine:
+1. Install the agentregistry `arctl` binary on your local machine.
+   ```sh
+   curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash
 
-```sh
-curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash
-```
+   export PATH="/usr/local/bin:$PATH"
+   ```
 
-By default, `arctl` connects to `http://localhost:12121`. If your agentregistry instance is exposed at a different address, configure the connection:
+2. Verify that the CLI is installed correctly.
+   ```sh
+   arctl version
+   ```
 
-```sh
-arctl configure --url http://<your-agentregistry-host>:12121
-```
+> [!TIP]
+> By default, `arctl` connects to `http://localhost:12121`. If your agentregistry instance is exposed at a different address, set the `ARCTL_API_BASE_URL` environment variable or pass `--registry-url` on each command. For example, to set the environment variable, use `export ARCTL_API_BASE_URL=http://<your-agentregistry-host>:12121`. 
 
 ## Next steps
 

content/docs/operations/_index.md

@@ -0,0 +1,5 @@
+---
+title: Operations
+weight: 90
+description: "Operational guides for running agentregistry in production."
+---