Merge pull request #96 from DGouron/feat/29-interactive-setup-wizard

docs: update documentation for reviewflow init wizard

Author: DGouron

docs/guide/index.md

@@ -4,7 +4,7 @@ title: Guide
 
 # Guide
 
-Everything you need to get started with Claude Review Automation and configure it for your projects.
+Everything you need to get started with Reviewflow and configure it for your projects.
 
 ## Suggested Reading Order
 

docs/guide/quick-start.md

@@ -12,7 +12,7 @@ Get Reviewflow running in 5 minutes.
 - A GitLab or GitHub account with webhook access
 - [Claude Code CLI](https://claude.ai/claude-code) installed and authenticated
 
-## 1. Installation
+## 1. Install
 
 ### As a user (recommended)
 
@@ -37,120 +37,93 @@ yarn install
 yarn build
 ```
 
-## 2. Configuration
+## 2. Initialize
 
-### Environment variables
+Run the interactive setup wizard:
 
 ```bash
-# Create your .env from the bundled template
-cp node_modules/reviewflow/templates/.env.example .env 2>/dev/null \
-  || cp .env.example .env
-
-# Edit with your webhook secrets
-# Generate tokens with: openssl rand -hex 32
-nano .env
+reviewflow init
 ```
 
-```bash
-# .env
-GITLAB_WEBHOOK_TOKEN=your_generated_token_here
-GITHUB_WEBHOOK_SECRET=your_generated_token_here
-```
+The wizard walks you through:
+1. Choosing your platform (GitLab, GitHub, or both)
+2. Entering your username(s) for @mention filtering
+3. Scanning for local repositories to register
+4. Generating webhook secrets automatically
 
-### Application config
+Your configuration is saved to `~/.claude-review/config.json` and `~/.claude-review/.env`.
 
-```bash
-# Create your config from the bundled template
-cp node_modules/reviewflow/templates/config.json.template config.json 2>/dev/null \
-  || cp config.example.json config.json
+::: tip Non-interactive mode
+Use `reviewflow init --yes` to accept all defaults. You can also pass `--scan-path /path/to/projects` to target specific directories.
+:::
 
-# Edit with your settings
-nano config.json
-```
+::: tip Add repositories later
+Use `reviewflow discover` to scan for and add new repositories to your existing configuration.
+:::
 
-```json
-{
-  "server": { "port": 3000 },
-  "user": {
-    "gitlabUsername": "YOUR_GITLAB_USERNAME",
-    "githubUsername": "YOUR_GITHUB_USERNAME"
-  },
-  "repositories": [
-    {
-      "platform": "gitlab",
-      "remoteUrl": "https://gitlab.com/your-org/your-project",
-      "localPath": "/path/to/your/local/clone",
-      "skill": "review-code",
-      "enabled": true
-    }
-  ]
-}
-```
+## 3. Configure webhook
 
-## 3. Start the server
+### GitLab
 
-### Global install
+1. Go to your project → **Settings** → **Webhooks**
+2. Add webhook:
+   - **URL**: `https://YOUR_TUNNEL_URL/webhooks/gitlab`
+   - **Secret token**: (shown during `reviewflow init`, or run `reviewflow init --show-secrets` to view)
+   - **Trigger**: ☑ Merge request events
+3. Click **Add webhook**
 
-```bash
-reviewflow start
-```
+### GitHub
+
+1. Go to your repo → **Settings** → **Webhooks**
+2. Add webhook:
+   - **Payload URL**: `https://YOUR_TUNNEL_URL/webhooks/github`
+   - **Content type**: `application/json`
+   - **Secret**: (shown during `reviewflow init`, or run `reviewflow init --show-secrets` to view)
+   - **Events**: ☑ Pull requests
+3. Click **Add webhook**
 
-### Contributor mode
+::: info Expose for webhooks
+GitLab/GitHub need to reach your server. Use a tunnel:
 
 ```bash
-# Development mode (with hot reload)
-yarn dev
+# Cloudflare Tunnel (recommended)
+cloudflared tunnel --url http://localhost:3847
 
-# Or production mode
-yarn start
+# Or ngrok
+ngrok http 3847
 ```
+:::
 
-The server runs at `http://localhost:3000` (or your configured port).
-
-## 4. Expose for webhooks
-
-GitLab/GitHub need to reach your server. Options:
-
-### Option A: Cloudflare Tunnel (recommended)
+## 4. Start & verify
 
 ```bash
-cloudflared tunnel --url http://localhost:3000
-```
-
-Copy the generated URL (e.g., `https://xxx-xxx.trycloudflare.com`).
+# Start the server
+reviewflow start
 
-### Option B: ngrok
+# Or as a background daemon
+reviewflow start --daemon
 
-```bash
-ngrok http 3000
+# Open the dashboard automatically
+reviewflow start --open
 ```
 
-## 5. Configure webhook
+The server runs at `http://localhost:3847` (or your configured port).
 
-### GitLab
+### Verify your setup
 
-1. Go to your project → **Settings** → **Webhooks**
-2. Add webhook:
-   - **URL**: `https://YOUR_TUNNEL_URL/webhooks/gitlab`
-   - **Secret token**: (same as `GITLAB_WEBHOOK_TOKEN` in your `.env`)
-   - **Trigger**: ☑ Merge request events
-3. Click **Add webhook**
-
-### GitHub
+```bash
+# Check configuration is valid
+reviewflow validate
 
-1. Go to your repo → **Settings** → **Webhooks**
-2. Add webhook:
-   - **Payload URL**: `https://YOUR_TUNNEL_URL/webhooks/github`
-   - **Content type**: `application/json`
-   - **Secret**: (same as `GITHUB_WEBHOOK_SECRET` in your `.env`)
-   - **Events**: ☑ Pull requests
-3. Click **Add webhook**
+# Check server status
+reviewflow status
+```
 
-## 6. Test it!
+## 5. Test it!
 
 1. Create or open a Merge Request / Pull Request
 2. Assign yourself as **Reviewer**
-3. Open `http://localhost:3000/dashboard/`
+3. Open `http://localhost:3847/dashboard/`
 4. Watch the review appear!
 
 ## Next steps
@@ -161,4 +134,4 @@ ngrok http 3000
 
 ## Troubleshooting
 
-See [Troubleshooting](./troubleshooting.md) for common issues (webhooks, reviews, Claude Code).
+See [Troubleshooting](./troubleshooting.md) for common issues and CLI diagnostics.

docs/guide/troubleshooting.md

@@ -6,6 +6,22 @@ title: Troubleshooting
 
 Common issues and solutions for Reviewflow.
 
+## CLI Diagnostics
+
+Before diving into specific issues, use these built-in commands:
+
+| Command | What it checks |
+|---------|---------------|
+| `reviewflow validate` | Config and `.env` correctness |
+| `reviewflow status` | Server running state, PID, port |
+| `reviewflow logs -f` | Live server logs (follow mode) |
+| `reviewflow logs -n 50` | Last 50 log lines |
+
+```bash
+# Quick health check
+reviewflow validate && reviewflow status
+```
+
 ## Webhooks
 
 ### Webhook returns 401

docs/reference/config.md

@@ -12,7 +12,7 @@ The system uses two configuration files:
 
 | File | Location | Purpose |
 |------|----------|---------|
-| `config.json` | Server root | Server configuration, repositories |
+| `config.json` | `~/.claude-review/` (created by `reviewflow init`) | Server configuration, repositories |
 | `.claude/reviews/config.json` | Each project | Project-specific review settings |
 
 ---
@@ -21,14 +21,14 @@ The system uses two configuration files:
 
 ### Location
 
-`config.json` in the server's root directory (or `config.example.json` as template).
+`~/.claude-review/config.json`, created automatically by `reviewflow init`.
 
 ### Schema
 
 ```json
 {
   "server": {
-    "port": 3000
+    "port": 3847
   },
   "user": {
     "gitlabUsername": "your-gitlab-username",
@@ -57,7 +57,7 @@ The system uses two configuration files:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `port` | number | `3000` | HTTP server port |
+| `port` | number | `3847` | HTTP server port |
 
 #### `user`
 
@@ -169,7 +169,7 @@ The automation server creates these files in `.claude/reviews/`:
 
 ## Validation
 
-Configuration files are validated at startup. Common errors: missing required fields, invalid model name (use `"sonnet"` or `"opus"`), nonexistent `localPath`, or missing skill file in `.claude/skills/`.
+Configuration files are validated at startup. Run `reviewflow validate` to check your configuration without starting the server. Common errors: missing required fields, invalid model name (use `"sonnet"` or `"opus"`), nonexistent `localPath`, or missing skill file in `.claude/skills/`.
 
 ---