diff --git a/README.md b/README.md
index 646f2ac..16acc03 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ The connector is a daemon the studio runs on its own hardware (or in a container
 go build -o butterstack-connector ./cmd/butterstack-connector
 ```
 
-**Docker image (from the in-tree Dockerfile):**
+**Docker image (from the in-tree Dockerfile, local build):**
 
 ```bash
 docker build -t butterstack-connector .
@@ -30,8 +30,48 @@ docker build -t butterstack-connector .
 
 The Dockerfile produces a minimal image with a static Go binary and a Ruby runtime for the UAT entrypoint. In production, the entrypoint runs the connector directly from `/usr/local/bin/butterstack-connector`.
 
+**Docker image (published, recommended):**
+
+Pull the published image instead of building it yourself, and pin an exact version tag:
+
+```bash
+docker run -d \
+  --name butterstack-connector \
+  -v $(pwd)/connector.yml:/etc/butterstack/connector.yml:ro \
+  ghcr.io/butterstack/butterstack-connector:v0.2.0
+```
+
+The image's entrypoint always reads its config from `/etc/butterstack/connector.yml` (the same path the `-config` flag defaults to), so mounting your `connector.yml` there read-only is all a container needs. See [Image and versions](#image-and-versions) below for the tagging policy.
+
+## Image and versions
+
+The image is published at `ghcr.io/butterstack/butterstack-connector`. Releases are pinned by semver tag (e.g. `v0.2.0`); do not run `:latest` for anything you want to stay stable, since a new tag may ship a breaking change to the config schema or the compiled vocabulary. Each tag also carries `provenance` and `sbom` metadata from the build, and the same version is published as OS/arch archives on the GitHub Releases page.
+
 ## Configure
 
+### Get a connector.yml from ButterStack
+
+You do not hand-write the `endpoint` and `token` fields yourself. From your ButterStack project's **Integrations > Connectors** tab in the web app, create a new connector: this generates a `connector.yml` already scoped with your project's real `endpoint` and a freshly issued `token`, ready to download.
+
+Once you have that file:
+
+1. Save it as `connector.yml` (or download it directly to your install location).
+2. Fill in the `perforce:` and/or `teamcity:` sections yourself with your own LAN details (server address, service-account user, ticket/token file paths, depot scope). These sections describe your own network and are never generated by ButterStack, since your credentials never leave it.
+3. Install it per the permissions steps below and point the daemon at it.
+
+For example, a filled-in Perforce section might look like:
+
+```yaml
+perforce:
+  enabled: true
+  port: ssl:<your-perforce-host>:1666
+  user: butterstack-ro
+  ticket_file: /etc/butterstack/p4.ticket
+scopes:
+  depot_scope:
+    - //depot/your-studio/
+```
+
 Copy `connector.example.yml` to your install location (e.g. `/etc/butterstack/connector.yml`) and set its permissions to 0600. The daemon refuses to start if the config file or any `*_file` path is readable by group or other users.
 
 ```bash