From dfc5ab3c9d383ade3db631eac9ee9dcb9dcd4319 Mon Sep 17 00:00:00 2001
From: Claude <claude@littlefake.com>
Date: Tue, 16 Jun 2026 03:25:03 +0000
Subject: [PATCH] Add Windows setup (setup.ps1), expand README with
 cross-platform install, Claude Desktop example, backup/restore, architecture
 diagram, .dockerignore

---
 .dockerignore |   7 ++++
 README.md     | 106 +++++++++++++++++++++++++++++++++++++++++++++++---
 setup.ps1     |  25 ++++++++++++
 3 files changed, 133 insertions(+), 5 deletions(-)
 create mode 100644 .dockerignore
 create mode 100644 setup.ps1

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..7a27d03
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,7 @@
+.git
+.env
+content/
+*.md
+LICENSE
+setup.sh
+setup.ps1
diff --git a/README.md b/README.md
index 63dd685..561e732 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,14 @@ Built by [DiligenceWorks](https://diligenceworks.online).
 
 ## Quick Start
 
+### Prerequisites
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows, macOS, or Linux)
+- That's it. No Python, Node.js, or database install needed.
+
+### Install
+
+**macOS / Linux:**
 ```bash
 git clone https://github.com/diligenceworks/diligence
 cd diligence
@@ -13,7 +21,32 @@ cd diligence
 docker compose up -d
 ```
 
-Open http://localhost and create your account.
+**Windows (PowerShell):**
+```powershell
+git clone https://github.com/diligenceworks/diligence
+cd diligence
+powershell -ExecutionPolicy Bypass -File setup.ps1
+docker compose up -d
+```
+
+**Windows (no script — manual):**
+```powershell
+git clone https://github.com/diligenceworks/diligence
+cd diligence
+copy .env.example .env
+# Edit .env and set SECRET_KEY to any random string (e.g. mash the keyboard)
+docker compose up -d
+```
+
+Open http://localhost and create your account. First user gets admin.
+
+### Verify
+
+```bash
+docker compose ps
+```
+
+You should see 4 containers, all healthy: `frontend`, `backend`, `mcp-connector`, `fitness-db`.
 
 ## Features
 
@@ -28,15 +61,38 @@ Open http://localhost and create your account.
 
 ## Connecting an AI Agent
 
-Point your agent's MCP config to `http://localhost:3001/sse` (development) or `https://your-domain/mcp` (production behind reverse proxy).
+Point your agent's MCP config at:
+
+| Environment | URL |
+|-------------|-----|
+| Local (development) | `http://localhost:3001/sse` |
+| Behind reverse proxy | `https://your-domain/mcp` |
 
 Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible agent.
 
 Copy the contents of [AGENT_GUIDE.md](AGENT_GUIDE.md) into your agent's system instructions for motivation-aware coaching.
 
+### Claude Desktop example
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "diligence": {
+      "url": "http://localhost:3001/sse"
+    }
+  }
+}
+```
+
+Then paste the contents of `AGENT_GUIDE.md` into your Claude Desktop project instructions.
+
 ## Configuring Integrations
 
-All integrations are configured through the app UI (Settings → Integrations) or through your AI agent. No `.env` file editing or container restarts needed.
+All integrations are configured through the app UI (**Settings → Integrations**) or through your AI agent. No `.env` file editing or container restarts needed.
+
+Tell your agent: *"I want to connect my Strava"* — it will walk you through getting API credentials and store them encrypted.
 
 ## Data Sovereignty
 
@@ -44,17 +100,57 @@ Diligence is self-hosted software. Your data never leaves your server. No cloud
 
 Your fitness data — heart rate, body composition, food intake, GPS traces — is biometric data that deserves sovereignty.
 
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                    nginx                         │
+│         (frontend, /api proxy, /mcp proxy)       │
+├──────────┬─────────────────┬────────────────────┤
+│ React    │   FastAPI        │   MCP Connector    │
+│ SPA      │   Backend        │   (14 tools)       │
+│          │                  │   port 3001        │
+│          ├──────────────────┤                    │
+│          │  PostgreSQL 16   │                    │
+│          │  (internal only) │                    │
+└──────────┴──────────────────┴────────────────────┘
+```
+
 ## Stack
 
-- Python 3.12, FastAPI, SQLAlchemy
+- Python 3.12, FastAPI, SQLAlchemy (async)
 - React 18, Vite
 - PostgreSQL 16
 - FastMCP (Streamable HTTP/SSE)
 - Docker Compose
 
+## Updating
+
+```bash
+git pull
+docker compose build
+docker compose up -d
+```
+
+Database migrations run automatically on startup. Your data is preserved.
+
+## Backing Up
+
+Your data lives in the `fitness_db_data` Docker volume:
+
+```bash
+docker compose exec fitness-db pg_dump -U fitness fitness_rewards > backup.sql
+```
+
+To restore:
+
+```bash
+docker compose exec -i fitness-db psql -U fitness fitness_rewards < backup.sql
+```
+
 ## Contributing
 
-Contributions welcome. Open an issue to discuss before submitting a PR.
+Contributions welcome. Please open an issue to discuss before submitting a PR.
 
 ## License
 
diff --git a/setup.ps1 b/setup.ps1
new file mode 100644
index 0000000..98c429d
--- /dev/null
+++ b/setup.ps1
@@ -0,0 +1,25 @@
+# Diligence — Windows Setup
+Write-Host "`n`e[36m💪 Diligence — Setup`e[0m`n"
+
+if (Test-Path .env) {
+    Write-Host "`e[33m.env already exists. Delete it first to regenerate.`e[0m"
+    exit 1
+}
+
+# Generate random SECRET_KEY (64 hex chars)
+$bytes = New-Object byte[] 32
+[System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
+$secret = ($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
+
+# Create .env from template
+Copy-Item .env.example .env
+(Get-Content .env) -replace "^SECRET_KEY=.*", "SECRET_KEY=$secret" | Set-Content .env
+
+Write-Host "`e[32m✅ .env created with random SECRET_KEY`e[0m"
+Write-Host ""
+Write-Host "Next steps:"
+Write-Host "  docker compose up -d"
+Write-Host "  Open http://localhost"
+Write-Host "  Register your account"
+Write-Host "  Configure integrations via Settings or your AI agent"
+Write-Host ""