misc: UI improvements and docs updates

docs/content/docs/(configuration)/config.mdx

@@ -15,6 +15,20 @@ $SPACEBOT_DIR/config.toml        # env override
 spacebot --config /path/to.toml  # CLI override
 ```
 
+## Environment Variables
+
+These environment variables control instance-level behavior and are not set in `config.toml`.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPACEBOT_DIR` | `~/.spacebot` | Instance root directory. All data, config, databases, and sockets live under this path. Set this to run multiple isolated instances (e.g. dev and prod) side by side. |
+| `SPACEBOT_DEPLOYMENT` | auto-detected | Deployment mode: `docker`, `hosted`, or native (auto-detected). Affects API bind address, agent limits, and update behavior. |
+| `SPACEBOT_MAX_AGENTS` | unlimited | Maximum number of agents (enforced in hosted mode only). |
+| `SPACEBOT_CRON_TIMEZONE` | server local | Default timezone for cron active-hours evaluation (IANA name). Overridden by `defaults.cron_timezone` or `agents.cron_timezone` in config. |
+| `SPACEBOT_USER_TIMEZONE` | inherits cron | Default timezone for channel/worker temporal context. Overridden by config equivalents. |
+| `SPACEBOT_CHANNEL_MODEL` | `anthropic/claude-sonnet-4-20250514` | Default channel model (env-only mode). |
+| `SPACEBOT_WORKER_MODEL` | `anthropic/claude-haiku-4.5-20250514` | Default worker model (env-only mode). |
+
 ## Full Reference
 
 ```toml

docs/content/docs/(getting-started)/quickstart.mdx

@@ -157,6 +157,60 @@ Each agent has three optional markdown files in its workspace (`~/.spacebot/agen
 
 Template files are created on first run. Edit them to shape the agent's personality. Changes are hot-reloaded (no restart needed).
 
+## Development setup
+
+To run a dev instance from source alongside an installed production instance, use `SPACEBOT_DIR` to give each its own data directory. Each instance gets separate databases, PID file, Unix socket, and logs — fully isolated.
+
+### 1. Create a dev instance directory
+
+```bash
+mkdir -p ~/.spacebot/dev
+```
+
+### 2. Add a dev config with different ports
+
+Create `~/.spacebot/dev/config.toml`:
+
+```toml
+[llm]
+anthropic_key = "env:ANTHROPIC_API_KEY"
+
+[[agents]]
+id = "main"
+
+# Use different ports so dev and prod don't conflict
+[api]
+port = 19899
+
+[messaging.webhook]
+port = 18790
+```
+
+### 3. Run both instances
+
+```bash
+# Production (installed binary, default ~/.spacebot)
+spacebot start
+
+# Dev (from source, separate data directory)
+SPACEBOT_DIR=~/.spacebot/dev cargo run -- start -f -d
+```
+
+The dev instance uses `~/.spacebot/dev/` for all data, and the production instance uses `~/.spacebot/` — they won't interfere with each other.
+
+You can also set `SPACEBOT_DIR` in a direnv `.envrc` so it applies automatically when you're in the project directory:
+
+```bash
+# .envrc in your spacebot source checkout
+export SPACEBOT_DIR="$HOME/.spacebot/dev"
+```
+
+Alternatively, use the `-c` flag to point at a specific config file (the instance directory is inferred as its parent):
+
+```bash
+cargo run -- -c ~/.spacebot/dev/config.toml start -f -d
+```
+
 ## Web UI
 
 When the API is enabled (default), the web dashboard is served at: