docs(self-host): state local install Postgres limitations (TASK-505)

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
 

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
 

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

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 ""