docs: update credential setup to reflect ~/.unraid-mcp/.env flow

CLAUDE.md

@@ -109,10 +109,12 @@ docker compose down
 
 ### Environment Variable Hierarchy
 The server loads environment variables from multiple locations in order:
-1. `/app/.env.local` (container mount)
+1. `~/.unraid-mcp/.env` (primary — canonical credentials dir, all runtimes)
-2. `../.env.local` (project root)
+2. `~/.unraid-mcp/.env.local` (local overrides, only used if primary is absent)
-3. `../.env` (project root)
+3. `/app/.env.local` (Docker container mount)
-4. `.env` (local directory)
+4. `../.env.local` (project root local overrides)
+5. `../.env` (project root fallback)
+6. `unraid_mcp/.env` (last resort)
 
 ### Transport Configuration
 - **streamable-http** (recommended): HTTP-based transport on `/mcp` endpoint
@@ -182,17 +184,14 @@ When bumping the version, **always update both files** — they must stay in syn
 - `pyproject.toml` → `version = "X.Y.Z"` under `[project]`
 - `.claude-plugin/plugin.json` → `"version": "X.Y.Z"`
 
-### Plugin Cache `.env` (automatic via elicitation)
+### Credential Storage (`~/.unraid-mcp/.env`)
-On first tool call without credentials, the server triggers MCP elicitation to
+All runtimes (plugin, direct, Docker) load credentials from `~/.unraid-mcp/.env`.
-collect `UNRAID_API_URL` and `UNRAID_API_KEY` interactively, then writes `.env`
+- **Plugin/direct:** `unraid_health action=setup` writes this file automatically via elicitation,
-to the plugin cache dir automatically. No manual symlinking needed.
+  or manual: `mkdir -p ~/.unraid-mcp && cp .env.example ~/.unraid-mcp/.env` then edit.
-
+- **Docker:** `docker-compose.yml` loads it via `env_file` before container start.
-Manual fallback (if client doesn't support elicitation):
+- **No symlinks needed.** Version bumps do not affect this path.
-```bash
+- **Permissions:** dir=700, file=600 (set automatically by elicitation; set manually if
-VERSION=$(grep '^version' pyproject.toml | grep -oP '[\d.]+') && \
+  using `cp`: `chmod 700 ~/.unraid-mcp && chmod 600 ~/.unraid-mcp/.env`).
-ln -sf /home/jmagar/workspace/unraid-mcp/.env \
-  ~/.claude/plugins/cache/jmagar-unraid-mcp/unraid/${VERSION}/.env
-```
 
 ### Symlinks
 `AGENTS.md` and `GEMINI.md` are symlinks to `CLAUDE.md` for Codex/Gemini compatibility:

README.md

@@ -54,22 +54,31 @@ This provides instant access to Unraid monitoring and management through Claude
 
 **See [.claude-plugin/README.md](.claude-plugin/README.md) for detailed plugin documentation.**
 
-### ⚙️ Credential Setup (Automatic)
+### ⚙️ Credential Setup
 
-On first use, the plugin will **automatically prompt you for credentials** via an
+Credentials are stored in `~/.unraid-mcp/.env` — one location that works for the
-interactive elicitation dialog in Claude Code. Simply call any Unraid tool and
+Claude Code plugin, direct `uv run` invocations, and Docker.
-follow the prompts — no manual `.env` configuration needed.
 
-Alternatively, trigger setup explicitly:
+**Option 1 — Interactive (Claude Code plugin, elicitation-supported clients):**
 ```
 unraid_health action=setup
 ```
+The server prompts for your API URL and key, writes `~/.unraid-mcp/.env` automatically
+(created with mode 700/600), and activates credentials without restart.
 
-Credentials are saved to `.env` in the plugin cache directory and persisted
+**Option 2 — Manual:**
-across restarts.
+```bash
+mkdir -p ~/.unraid-mcp && chmod 700 ~/.unraid-mcp
+cp .env.example ~/.unraid-mcp/.env && chmod 600 ~/.unraid-mcp/.env
+# Edit ~/.unraid-mcp/.env with your values:
+#   UNRAID_API_URL=https://10-1-0-2.xxx.myunraid.net:31337
+#   UNRAID_API_KEY=your-key-from-unraid-settings
+```
 
-> **Manual fallback:** If elicitation is not supported by your client, create
+**Docker:** `~/.unraid-mcp/.env` is loaded via `env_file` in `docker-compose.yml` —
-> `.env` in the plugin cache directory manually (see `.env.example` for the format).
+same file, no duplication needed.
+
+> **Finding your API key:** Unraid → Settings → Management Access → API Keys
 
 ---