From cdbaa6aca49f65108ccb4e8fbb5e0ecb1940a4a9 Mon Sep 17 00:00:00 2001
From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com>
Date: Sun, 25 Oct 2026 01:47:35 -0700
Subject: [PATCH] docs(self-host): state local install Postgres limitations

Co-authored-by: kite <WyJraXRlIiwiZGVmYXVsdCJd@agents.commonly.invalid>
Agent-Model: codex/gpt-6.1-sol/medium
---
 README.md                           |  8 +++++++-
 docs/deployment/SELF_HOSTED.md      | 13 ++++++++++---
 docs/self-hosting/helm-reference.md | 10 ++++++++++
 install.sh                          |  5 +++++
 4 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 8557ff1101..0a821fbe84 100644
--- a/README.md
+++ b/README.md
@@ -92,7 +92,13 @@ cd commonly
 ./install.sh
 ```
 
-Then open http://localhost:3000. More in the [self-hosting guide](docs/deployment/SELF_HOSTED.md).
+Then open http://localhost:3000.
+
+The one-command local install (`docker-compose.local.yml`) currently runs without
+Postgres. Chat uses the MongoDB fallback; the tool broker, Postgres-backed
+decisions and reactions are unavailable. The full `docker-compose.yml` includes
+Postgres. Adding it to the local profile is tracked in TASK-503.
+More in the [self-hosting guide](docs/deployment/SELF_HOSTED.md).
 
 ## Docs
 
diff --git a/docs/deployment/SELF_HOSTED.md b/docs/deployment/SELF_HOSTED.md
index 2de9ba7ad1..4e69fe2424 100644
--- a/docs/deployment/SELF_HOSTED.md
+++ b/docs/deployment/SELF_HOSTED.md
@@ -12,9 +12,16 @@ matches where it will run:
 The Docker Compose profile is intentionally **local-only**. It builds the
 frontend, backend, and MongoDB on one machine and publishes ports `3000` and
 `5000`. It has no TLS, reverse proxy, public-domain configuration, or
-PostgreSQL service. PostgreSQL-backed capabilities, including threaded agent
-messages, are therefore not enabled in this profile. Do not expose this Compose
-file directly to the internet.
+PostgreSQL service. Chat uses the MongoDB fallback. The tool broker,
+Postgres-backed decisions and reactions are unavailable in this profile;
+threaded agent messages are not enabled either. The tool broker explicitly
+requires PostgreSQL (`backend/models/ToolCall.ts`).
+
+The full [`docker-compose.yml`](../../docker-compose.yml) includes PostgreSQL;
+it requires its own environment configuration and is a separate profile.
+TASK-503 tracks adding PostgreSQL to the one-command local profile. Until that
+change lands, `./install.sh` continues to start the MongoDB-only profile.
+Do not expose this Compose file directly to the internet.
 
 ## Prerequisites
 
diff --git a/docs/self-hosting/helm-reference.md b/docs/self-hosting/helm-reference.md
index 171b6dc1c3..cc979c9792 100644
--- a/docs/self-hosting/helm-reference.md
+++ b/docs/self-hosting/helm-reference.md
@@ -8,6 +8,16 @@ The base chart's `values.yaml` ships `agents.clawdbot.enabled: true`. The
 legacy gateway is optional, so self-hosters who do not deliberately run it
 must override that value to `false`; the current hosted dev values do so.
 
+## One-command local install
+
+`./install.sh` uses `docker-compose.local.yml`, which currently runs without
+Postgres. Chat uses the MongoDB fallback. The tool broker, Postgres-backed
+decisions and reactions are unavailable. The full `docker-compose.yml` includes
+Postgres; adding it to the local profile is tracked in TASK-503.
+See the [local installation guide](../deployment/SELF_HOSTED.md) for profile
+selection. The Helm configuration below supports a PostgreSQL service or an
+external PostgreSQL database.
+
 ## Quick Start
 
 ```bash
diff --git a/install.sh b/install.sh
index a70a32c0bd..bea45e8c36 100755
--- a/install.sh
+++ b/install.sh
@@ -37,6 +37,11 @@ else
   echo "  ✓ Created $ENV_FILE with a generated JWT secret"
 fi
 
+echo ""
+echo "  Local profile: docker-compose.local.yml (without Postgres)."
+echo "  Chat uses the MongoDB fallback. The tool broker, Postgres-backed"
+echo "  decisions and reactions are unavailable."
+echo "  docker-compose.yml includes Postgres; TASK-503 tracks adding it locally."
 echo ""
 echo "  Starting Commonly..."
 echo ""