[AISOS-2125] Add quick start instructions to forge readme.md

README.md

@@ -168,28 +168,67 @@ Jira and GitHub send webhooks to Forge. Forge queues events, resumes the right w
 
 ## Quick Start
 
-To run Forge locally you need:
+### 1. Prerequisites
 
-- Python 3.11+
-- Redis Stack
-- Podman
-- Jira Cloud API access
-- GitHub access
-- LLM backend access through a direct model provider API or Google Vertex AI
+Before running Forge locally, ensure you have the following installed and configured:
 
-Then:
+- **Python 3.11+**
+- **Podman** (or Docker)
+- **API Access Tokens**:
+  - Jira Cloud API credentials (base URL, API token, user email)
+  - GitHub personal access token (with repository scope)
+  - LLM Backend Access (Anthropic Claude API credentials or Google Vertex AI authentication)
+
+### 2. Core Services
+
+To start the local development environment, clone the repository, synchronize the environment, and spin up the required core services:
 
 ```bash
 git clone https://github.com/Forge-sdlc/forge.git
 cd forge
 uv sync
 cp .env.example .env
+# Edit .env with your Jira, GitHub, and LLM credentials
+
+# 1. Start Redis Stack (using developer compose configuration)
+docker compose -f devtools/docker-compose.dev.yml up -d redis
+
+# 2. Build the container image for isolated code execution
 podman build -t forge-dev:latest -f containers/Containerfile containers/
-docker compose up redis -d
+
+# 3. Start the FastAPI Gateway
 uv run uvicorn forge.main:app --reload --port 8000 --host 0.0.0.0
+
+# 4. Start the background worker process
 uv run forge worker
 ```
 
+### 3. Optional Observability Services
+
+Forge supports extensive real-time telemetry, including Prometheus metrics, Langfuse traces, and local Grafana dashboards.
+
+#### Monitoring (Prometheus & Grafana)
+
+Run Prometheus and Grafana for metrics and dashboard visualization:
+
+```bash
+docker compose -f devtools/docker-compose.dev.yml up -d prometheus grafana
+```
+
+Access the service consoles via these local endpoints:
+- **Prometheus Dashboard:** [http://localhost:9092](http://localhost:9092)
+- **Grafana Dashboards:** [http://localhost:3010](http://localhost:3010) (default credentials: `admin` / `grafana`)
+
+#### Tracing (Langfuse)
+
+To capture workflow execution steps, inputs, and outputs with Langfuse, configure your `.env` file with your credentials:
+
+```env
+LANGFUSE_PUBLIC_KEY="pk-lf-..."
+LANGFUSE_SECRET_KEY="sk-lf-..."
+LANGFUSE_HOST="https://cloud.langfuse.com" # Or your custom/local endpoint
+```
+
 See [Getting Started](https://Forge-sdlc.github.io/forge/getting-started/) for the full setup path, including environment variables, webhooks, and local development options.
 
 ## Documentation

tests/unit/test_readme_integrity.py

@@ -0,0 +1,31 @@
+"""Test suite verifying README.md structure and content integrity."""
+
+import os
+from pathlib import Path
+
+
+def test_readme_exists_and_contains_quickstart():
+    # Find the repository root README.md
+    readme_path = Path("/workspace/README.md")
+    assert readme_path.exists(), "README.md does not exist at root"
+
+    content = readme_path.read_text()
+
+    # Assert presence of key quick start headings and instructions
+    assert "## Quick Start" in content, "README is missing '## Quick Start' section"
+    assert "### 1. Prerequisites" in content, "README is missing Prerequisites subsection"
+    assert "### 2. Core Services" in content, "README is missing Core Services subsection"
+    assert "### 3. Optional Observability Services" in content, "README is missing Optional Observability Services subsection"
+
+def test_readme_contains_commands_and_paths():
+    readme_path = Path("/workspace/README.md")
+    content = readme_path.read_text()
+
+    # Verify the specific files/paths mentioned in the implementation plan
+    assert "devtools/docker-compose.dev.yml" in content, "README should mention the developer docker-compose file path"
+    assert "redis" in content, "README should contain redis instructions"
+    assert "prometheus" in content, "README should mention prometheus"
+    assert "grafana" in content, "README should mention grafana"
+    assert "LANGFUSE_PUBLIC_KEY" in content, "README should mention Langfuse configuration keys"
+    assert "uv run uvicorn forge.main:app" in content, "README should specify the FastAPI startup command"
+    assert "uv run forge worker" in content, "README should specify the worker startup command"