@moxxy/cli 0.0.3 → 0.0.5

package/README.md

@@ -76,6 +76,70 @@ Start the orchestration server. Connects to the configured SDK, initializes the
 
 Display current configuration: SDK provider, GitHub token status, webhook settings, watched repositories, and agent configuration.
 
+## Connecting to GitHub
+
+Moxxy uses standard GitHub repository webhooks (no GitHub App required). You need a **GitHub Personal Access Token** and a publicly reachable URL for your webhook server.
+
+### 1. Generate a webhook secret
+
+```bash
+openssl rand -hex 32
+```
+
+Save this value — you'll use it in both Moxxy config and GitHub.
+
+### 2. Initialize Moxxy
+
+```bash
+moxxy config init
+```
+
+The interactive wizard will ask for your SDK provider, GitHub PAT, webhook secret, and port. Or pass flags directly:
+
+```bash
+moxxy config init \
+  --sdk claude \
+  --github-token ghp_xxx \
+  --webhook-secret your-secret \
+  --webhook-port 3456
+```
+
+### 3. Expose the webhook server
+
+Moxxy listens on `localhost:3456` by default. For GitHub to reach it, expose it with a tunnel:
+
+```bash
+ngrok http 3456
+```
+
+This gives you a public URL like `https://abc123.ngrok-free.app`.
+
+### 4. Add a webhook on GitHub
+
+Go to your repository **Settings > Webhooks > Add webhook**:
+
+| Field | Value |
+|-------|-------|
+| Payload URL | `https://<your-ngrok-url>/webhook/github` |
+| Content type | `application/json` |
+| Secret | the same secret from step 1 |
+| Events | select "Let me select individual events" > check **Issues** |
+
+### 5. Add the repo and start
+
+```bash
+moxxy repo add owner/repo
+moxxy start
+```
+
+Open an issue on the repo to verify Moxxy picks it up.
+
+### Webhook details
+
+- **Path**: `/webhook/github` (fixed)
+- **Signature verification**: HMAC-SHA256 via `X-Hub-Signature-256` header. Optional but recommended — if no secret is configured, all requests are accepted.
+- **Supported events**: `issues` (actions: `opened`, `labeled`)
+
 ## Programmatic Usage
 
 ```typescript