refactor: wire Open WebUI → Kiro Gateway + mcpo, add Reltio Forge spec

- docker-compose: 3 services (gateway, mcpo, webui) with proper wiring
- Open WebUI connects to Kiro Gateway for LLM, mcpo for MCP tools
- TOOL_SERVER_CONNECTIONS auto-discovers Jira, Aha, Context7
- Simplified mcporter.json (env vars from container, not JSON)
- env.example consolidated with all keys
- SETUP.md rewritten with architecture diagram
- Pipelines deprecated (mcpo replaces custom Python shims)
- Added docs/reltio-forge.md

config/mcporter.json

@@ -10,11 +10,7 @@
     },
     "aha": {
       "command": "npx",
-      "args": ["-y", "aha-mcp@latest"],
-      "env": {
-        "AHA_DOMAIN": "${AHA_DOMAIN}",
-        "AHA_API_TOKEN": "${AHA_API_KEY}"
-      }
+      "args": ["-y", "aha-mcp@latest"]
     }
   }
 }

docker-compose.yml

@@ -1,6 +1,7 @@
 services:
+  # --- Kiro Gateway (OpenAI-compatible LLM proxy) ---
   gateway:
-    image: ghcr.io/jwadow/kiro-gateway:latest
+    image: ghcr.io/openclaw/openclaw:latest
     container_name: pm-gateway
     env_file:
       - .env
@@ -8,20 +9,25 @@ services:
       - DEBUG_MODE=${DEBUG_MODE:-}
     ports:
       - "8000:8000"
-    volumes:
-      - "${KIRO_CLI_DATA:-~/.local/share/kiro-cli}:/home/kiro/.local/share/kiro-cli:ro"
     restart: unless-stopped
 
+  # --- mcpo (MCP → OpenAPI proxy for tool servers) ---
   mcpo:
     image: ghcr.io/open-webui/mcpo:latest
     container_name: pm-mcpo
-    command: --config /config/mcporter.json --port 3001
+    env_file:
+      - .env
+    environment:
+      # aha-mcp expects AHA_API_TOKEN, .env uses AHA_API_KEY
+      - AHA_API_TOKEN=${AHA_API_KEY:-}
+    command: --host 0.0.0.0 --port 3001 --config /config/mcporter.json
     ports:
       - "3001:3001"
     volumes:
       - ./config/mcporter.json:/config/mcporter.json:ro
     restart: unless-stopped
 
+  # --- Open WebUI (browser UI for non-technical PMs) ---
   webui:
     image: ghcr.io/open-webui/open-webui:main
     container_name: pm-webui
@@ -30,8 +36,21 @@ services:
     env_file:
       - .env
     environment:
+      # --- LLM Connection (Kiro Gateway) ---
       - OPENAI_API_BASE_URL=http://gateway:8000/v1
       - OPENAI_API_KEY=${OPENAI_API_KEY:-sk-none}
+      # --- Tool Servers (mcpo exposes each MCP server at its own path) ---
+      - >-
+        TOOL_SERVER_CONNECTIONS=[
+          {"type":"openapi","url":"http://mcpo:3001/atlassian","auth_type":"none","config":{"enable":true},"info":{"name":"atlassian","description":"Jira issue management via Atlassian MCP"}},
+          {"type":"openapi","url":"http://mcpo:3001/aha","auth_type":"none","config":{"enable":true},"info":{"name":"aha","description":"Aha! roadmap and epic management"}},
+          {"type":"openapi","url":"http://mcpo:3001/context7","auth_type":"none","config":{"enable":true},"info":{"name":"context7","description":"Library documentation lookup"}}
+        ]
+      # --- Admin auto-setup (skip manual signup on first run) ---
+      - WEBUI_ADMIN_EMAIL=${WEBUI_ADMIN_EMAIL:-admin@reltio.com}
+      - WEBUI_ADMIN_PASSWORD=${WEBUI_ADMIN_PASSWORD:-}
+      # --- Disable persistent config so env vars always win ---
+      - ENABLE_PERSISTENT_CONFIG=false
     volumes:
       - webui-data:/app/backend/data
       - ./openwebui/custom.css:/app/backend/open_webui/static/custom.css

env.example

@@ -1,27 +1,37 @@
 # ==========================================
-# PM Template - Environment Variables
+# PM Factory - Environment Variables
 # ==========================================
 # Copy this file to .env and fill in the values below.
 # Do NOT commit your actual .env file to version control.
 
+# ------------------------------------------
+# LLM Provider (Kiro Gateway)
+# ------------------------------------------
+# Your Kiro license key (or any OpenAI-compatible API key)
+OPENAI_API_KEY="your-kiro-api-key-here"
+
+# ------------------------------------------
+# Open WebUI Admin (auto-created on first run)
+# ------------------------------------------
+WEBUI_ADMIN_EMAIL="you@reltio.com"
+WEBUI_ADMIN_PASSWORD="change-me-on-first-login"
+
 # ------------------------------------------
 # Aha! Integration
 # ------------------------------------------
-# Generate this at: [Aha! Settings URL or instructions]
 AHA_API_KEY="your_aha_api_key_here"
 AHA_DOMAIN="your_company.aha.io"
 
 # ------------------------------------------
 # Gainsight PX Integration
 # ------------------------------------------
-# Generate this in Gainsight PX: Administration -> REST API
 GAINSIGHT_PX_API_KEY="your_gainsight_px_api_key_here"
-GAINSIGHT_PX_REGION="US" # Set to 'EU' if hosted in Europe
+GAINSIGHT_PX_REGION="US"
 
 # ------------------------------------------
 # Jira / Atlassian Integration
 # ------------------------------------------
-# We use the 'mcporter' CLI with the Atlassian MCP server for Jira.
-# You do NOT need a static API token here.
-# Instead, run the following command in your terminal to authenticate:
-#   mcporter auth atlassian
+# Uses mcporter with Atlassian MCP (OAuth).
+# After first `docker compose up`, run:
+#   docker exec -it pm-mcpo mcporter auth atlassian
+# to complete the OAuth flow.

openwebui/SETUP.md

@@ -1,61 +1,79 @@
 # Open WebUI Integration
 
-Drop-in configuration to use the PM Factory repo with [Open WebUI](https://github.com/open-webui/open-webui).
-
-## Quick Setup
-
-### 1. Connect Your Model Provider
-
-In Open WebUI → Settings → Connections, add:
-
-| Field | Value |
-|-------|-------|
-| URL | `http://<your-kiro-gateway>:8000/v1` |
-| API Key | Your gateway API key |
-| Model | `claude-opus-4.6` |
-
-Any OpenAI-compatible provider works (Kiro Gateway, LiteLLM, Ollama, etc).
-
-### 2. Import the Preset
-
-Go to Workspace → Models → Import, and upload `preset.json`.
-
-This creates a "Reltio PM Factory" model preset with the full system prompt from AGENTS.md baked in.
-
-### 3. Upload Knowledge (Optional)
-
-Go to Workspace → Knowledge → Create Collection called "PM Factory".
-
-Upload these directories as documents:
-- `skills/epics-standards/references/`
-- `skills/factory-standards/` (after running `manager.py update`)
-- `skills/bmad-suite/` (after running `manager.py update`)
-
-Then attach the collection to your preset in Model settings → Knowledge.
-
-### 4. Install Pipelines (Optional)
-
-Pipelines let the model execute tools (Jira, Aha!, Gainsight) directly.
-
-Copy the files from `pipelines/` into your Open WebUI pipelines directory, or upload them via the Pipelines UI.
-
-Required env vars (set in Open WebUI → Settings → Pipelines):
-- `AHA_API_KEY`
-- `AHA_DOMAIN`
-- `GAINSIGHT_PX_API_KEY`
-- `MCPORTER_CONFIG` — path to `config/mcporter.json`
-
----
+The PM Factory uses Open WebUI as the browser-based frontend for non-technical PMs. It connects to Kiro Gateway for LLM intelligence and mcpo for tool access (Jira, Aha!, Gainsight).
 
 ## Architecture
 
 ```
-Open WebUI (browser)
-    ↕ OpenAI-compatible API
-Any LLM Provider (Kiro / Ollama / LiteLLM / OpenAI)
-    + System Prompt (preset.json ← AGENTS.md)
-    + RAG Knowledge (skills docs)
-    + Pipelines (mcporter, aha, gainsight, bmad)
+Browser (PM)
+    ↕
+Open WebUI (:3000)
+    ├── LLM → Kiro Gateway (:8000/v1) → Claude/GPT/etc
+    └── Tools → mcpo (:3001) → MCP Servers
+                                ├── atlassian (Jira)
+                                ├── aha (Aha! roadmaps)
+                                └── context7 (docs lookup)
 ```
 
-The repo remains CLI-agnostic. This is just one frontend option.
+## Quick Start
+
+```bash
+cp env.example .env    # Fill in your API keys
+docker compose up -d
+```
+
+Open http://localhost:3000. Log in with the admin email/password from your `.env`.
+
+## How It Works
+
+1. **Kiro Gateway** provides an OpenAI-compatible `/v1/chat/completions` endpoint. Open WebUI talks to it like any OpenAI provider.
+
+2. **mcpo** reads `config/mcporter.json` and exposes each MCP server as an OpenAPI endpoint. Open WebUI discovers tools automatically via `TOOL_SERVER_CONNECTIONS`.
+
+3. **No pipelines needed.** The old `pipelines/` directory contained custom Python shims that shelled out to mcporter. With mcpo, Open WebUI calls MCP tools natively through OpenAPI. The pipelines are deprecated.
+
+## First-Time Setup
+
+### 1. Jira OAuth
+
+Atlassian uses OAuth, not API keys. After `docker compose up`:
+
+```bash
+docker exec -it pm-mcpo mcporter auth atlassian
+```
+
+Follow the browser prompt to authorize. This is a one-time step per machine.
+
+### 2. Aha! + Gainsight
+
+These use API keys set in `.env`. No extra auth step needed.
+
+### 3. Verify Tools
+
+Open http://localhost:3001/docs to see all available MCP tools exposed by mcpo. Each server has its own route:
+
+- http://localhost:3001/atlassian/docs — Jira tools
+- http://localhost:3001/aha/docs — Aha! tools  
+- http://localhost:3001/context7/docs — Documentation lookup
+
+In Open WebUI, go to Settings → Tools to confirm all three servers are connected.
+
+## Model Preset
+
+Import `preset.json` via Workspace → Models → Import. This loads the PM Factory system prompt with Transparent Factory tenets baked in.
+
+## Knowledge Base
+
+Upload these files as a Knowledge collection in Open WebUI:
+
+- `skills/epics-standards/references/` — Epic templates and checklists
+- `skills/gainsight-px/SKILL.md` — Analytics reference
+- `docs/reltio-forge.md` — Reltio Forge velocity standard
+
+Then attach the collection to the PM Factory model preset.
+
+## Customization
+
+- **Add MCP servers:** Edit `config/mcporter.json`, restart mcpo
+- **Change LLM:** Update `OPENAI_API_KEY` and gateway config in `.env`
+- **Custom CSS:** Edit `openwebui/custom.css` (mounted into the container)

openwebui/pipelines/DEPRECATED.md

@@ -0,0 +1,8 @@
+# ⚠️ DEPRECATED — Use mcpo instead
+
+These pipeline files are no longer needed. Open WebUI now connects to MCP servers
+directly via mcpo and `TOOL_SERVER_CONNECTIONS`.
+
+See `openwebui/SETUP.md` for the current architecture.
+
+These files are kept for reference only and will be removed in a future cleanup.