docs: add Docker Compose troubleshooting FAQ

QUICKSTART.md

@@ -45,6 +45,8 @@ docker compose version  # V2 syntax (not docker-compose)
 
 **Missing something?** → [docs/INSTALL-FRAMEWORKS.md](docs/INSTALL-FRAMEWORKS.md) — installs Node, npm, and Docker in minutes on Mac, Linux, or Windows.
 
+**Docker still giving you trouble?** → [docs/DOCKER-COMPOSE-TROUBLESHOOTING.md](docs/DOCKER-COMPOSE-TROUBLESHOOTING.md) — bind, health, auth, and restart fixes for local self-hosting.
+
 > **Why these?** Node + npm power the `annie` CLI you'll install on employee machines. Docker runs the server without you needing to install Rust, Postgres, or nginx yourself.
 
 ---
@@ -244,6 +246,8 @@ You now have:
 | Session not appearing in dashboard | Confirm `NEST_API_URL` in CLI points to the correct server address |
 | Something else is wrong | Run `annie diagnose` — it prints a full diagnostic report |
 
+Need deeper Compose-specific debugging? See [docs/DOCKER-COMPOSE-TROUBLESHOOTING.md](docs/DOCKER-COMPOSE-TROUBLESHOOTING.md).
+
 ---
 
 > **You're running an enterprise-grade AI workforce hub. For free. On your own infrastructure.**
@@ -259,4 +263,4 @@ You now have:
 
 *Public distribution: [contextzero/nest_hub](https://github.com/contextzero/nest_hub) · CLI: [@contextzero/nest](https://www.npmjs.com/package/@contextzero/nest).*
 
-</div>
+</div>

README.md

@@ -78,6 +78,16 @@ flowchart LR
 
 Architecture: hexagonal (`domain` → `ports` → `application` → `adapters`). See the [security model](docs/SECURITY-MODEL.md) for the data-residency and audit posture.
 
+### Runtime layers
+
+- `annie` CLI lives on employee machines and authenticates with `CLI_API_TOKEN`
+- `nginx` is public entrypoint for web, REST, Socket.IO, and SSE
+- `nest-server` handles auth, policy, sessions, audit trail, and orchestration
+- `postgres` stores users, sessions, prompts, approvals, and logs
+- model providers stay external and are reached only through your configured keys
+
+This separation keeps browser and CLI traffic outbound-only from user devices while the server and database stay inside your boundary.
+
 ## Quick Start
 
 Deploy the self-hosted hub with [Docker](https://docs.docker.com/get-docker/). Clone the repo and run the setup script — it generates secrets, pulls the published images, starts the stack, and waits for health:

docs/DOCKER-COMPOSE-TROUBLESHOOTING.md

@@ -0,0 +1,96 @@
+# Docker Compose Troubleshooting
+
+This FAQ covers common local self-hosting problems when bringing up NEST with
+Docker Compose.
+
+## `docker compose` command not found
+
+NEST expects Compose V2. Verify:
+
+```bash
+docker compose version
+```
+
+If this fails, update Docker Desktop or Docker Engine until the integrated
+`docker compose` command is available.
+
+## Port `80` already in use
+
+Symptoms:
+
+- `nginx` fails to start
+- Compose reports a bind error
+
+Fix options:
+
+1. Stop the process already using port `80`.
+2. Change the published web port in your local `.env` or Compose override.
+3. Restart the stack:
+
+```bash
+docker compose up -d
+```
+
+If you remap the port, use the same host and port in `NEST_API_URL`.
+
+## Stack never turns healthy
+
+Check current state:
+
+```bash
+docker compose ps
+docker compose logs nest-server --tail=100
+docker compose logs postgres --tail=100
+docker compose logs nginx --tail=100
+```
+
+Typical causes:
+
+- stale or partially edited `.env`
+- failed image pull
+- local filesystem permission problem on mounted files
+- PostgreSQL still warming up on the first start
+
+## Browser works but CLI auth fails
+
+Check:
+
+```bash
+grep CLI_API_TOKEN .env
+annie auth status
+```
+
+Verify that:
+
+- the stack is healthy
+- the CLI token matches `.env`
+- the CLI points at the same host and port exposed by nginx
+
+## Need a clean restart
+
+For a normal restart:
+
+```bash
+docker compose down
+docker compose up -d
+docker compose logs -f
+```
+
+After `.env` changes:
+
+```bash
+docker compose down
+docker compose up -d --force-recreate
+```
+
+## What to include in a bug report
+
+Open an issue with:
+
+- host OS
+- Docker version
+- exact failing command
+- redacted `docker compose ps`
+- redacted logs from affected containers
+
+Never post secrets, tokens, or full `.env` contents.