loki-mode 6.59.0 → 6.60.0

package/autonomy/mirofish-adapter.py

@@ -0,0 +1,1530 @@
+#!/usr/bin/env python3
+"""MiroFish Market Validation Adapter for Loki Mode
+
+Orchestrates the MiroFish swarm intelligence API to provide pre-build
+market validation. Runs MiroFish's 4-stage async pipeline and normalizes
+results into Loki Mode's .loki/ directory format.
+
+Stdlib only - no pip dependencies required. Python 3.9+.
+
+Usage:
+    python3 mirofish-adapter.py <prd-path> --output-dir .loki/ [--validate] [--json] [--url URL] [--background] [--max-rounds N]
+    python3 mirofish-adapter.py --status [--output-dir .loki/]
+    python3 mirofish-adapter.py --resume --output-dir .loki/ --url URL
+    python3 mirofish-adapter.py --docker-start --docker-image IMAGE [--port N]
+    python3 mirofish-adapter.py --docker-stop
+    python3 mirofish-adapter.py --health --url URL
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+import tempfile
+import hashlib
+import signal
+import subprocess
+import urllib.request
+import urllib.parse
+import urllib.error
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from datetime import datetime, timezone
+
+# Maximum artifact file size (10 MB)
+MAX_ARTIFACT_SIZE = 10 * 1024 * 1024
+
+# Container and connection defaults
+CONTAINER_NAME = "loki-mirofish"
+DEFAULT_URL = "http://localhost:5001"
+DEFAULT_PORT = 5001
+DEFAULT_MAX_ROUNDS = 100
+DEFAULT_TIMEOUT = 3600  # 1 hour total pipeline timeout
+
+
+# ---------------------------------------------------------------------------
+# Utility Functions
+# ---------------------------------------------------------------------------
+
+def _safe_read(path: Path) -> str:
+    """Read a file with size limit and encoding safety."""
+    size = path.stat().st_size
+    if size > MAX_ARTIFACT_SIZE:
+        raise ValueError(
+            f"Artifact too large ({size} bytes, max {MAX_ARTIFACT_SIZE}): {path.name}"
+        )
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _write_atomic(path: Path, content: str) -> None:
+    """Write content to file atomically using temp file + rename."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        os.replace(tmp_path, str(path))
+    except Exception:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def _write_json(path: Path, data: Any) -> None:
+    """Write JSON data atomically to a file."""
+    _write_atomic(path, json.dumps(data, indent=2) + "\n")
+
+
+def _now_iso() -> str:
+    """Return current UTC timestamp in ISO-8601 format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+# ---------------------------------------------------------------------------
+# MiroFish HTTP Client
+# ---------------------------------------------------------------------------
+
+class MiroFishClient:
+    """HTTP client for the MiroFish swarm intelligence API.
+
+    Uses stdlib urllib only -- no third-party dependencies.
+    All methods return parsed JSON dicts. Raises RuntimeError on errors.
+    """
+
+    def __init__(self, base_url: str = DEFAULT_URL, timeout: int = 30):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json_data: Optional[dict] = None,
+        form_data: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+    ) -> dict:
+        """Make HTTP request. Returns parsed JSON response.
+
+        Raises RuntimeError on non-2xx status or connection error.
+        """
+        url = f"{self.base_url}{path}"
+        headers: Dict[str, str] = {"Accept": "application/json"}
+        body: Optional[bytes] = None
+
+        if json_data is not None:
+            body = json.dumps(json_data).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        elif form_data is not None:
+            body = form_data
+            if content_type:
+                headers["Content-Type"] = content_type
+
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                resp_body = resp.read().decode("utf-8")
+                if not resp_body.strip():
+                    return {}
+                return json.loads(resp_body)
+        except urllib.error.HTTPError as exc:
+            resp_text = ""
+            try:
+                resp_text = exc.read().decode("utf-8", errors="replace")
+            except Exception:
+                pass
+            raise RuntimeError(
+                f"MiroFish API error: {exc.code} {exc.reason} "
+                f"on {method} {path}: {resp_text}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise RuntimeError(
+                f"MiroFish connection error on {method} {path}: {exc.reason}"
+            ) from exc
+        except Exception as exc:
+            raise RuntimeError(
+                f"MiroFish request failed on {method} {path}: {exc}"
+            ) from exc
+
+    def health_check(self) -> bool:
+        """GET /health - returns True if MiroFish is healthy."""
+        try:
+            resp = self._request("GET", "/health")
+            return resp.get("status") == "ok" or bool(resp)
+        except RuntimeError:
+            return False
+
+    # -- Stage 1: Graph Construction ------------------------------------------
+
+    def generate_ontology(
+        self,
+        prd_path: str,
+        simulation_requirement: str,
+        project_name: str = "",
+    ) -> dict:
+        """POST /api/graph/ontology/generate - multipart/form-data upload.
+
+        Uploads the PRD file and simulation_requirement text.
+        Returns: {project_id, ontology: {entity_types, edge_types, analysis_summary}}
+        """
+        boundary = hashlib.md5(
+            f"{time.time()}-{prd_path}".encode()
+        ).hexdigest()
+
+        parts: List[bytes] = []
+
+        # File field
+        filename = Path(prd_path).name
+        file_content = Path(prd_path).read_bytes()
+        parts.append(
+            f"--{boundary}\r\n"
+            f'Content-Disposition: form-data; name="prd_file"; filename="{filename}"\r\n'
+            f"Content-Type: application/octet-stream\r\n\r\n".encode("utf-8")
+            + file_content
+            + b"\r\n"
+        )
+
+        # Text fields
+        for field_name, field_value in [
+            ("simulation_requirement", simulation_requirement),
+            ("project_name", project_name),
+        ]:
+            parts.append(
+                f"--{boundary}\r\n"
+                f'Content-Disposition: form-data; name="{field_name}"\r\n\r\n'
+                f"{field_value}\r\n".encode("utf-8")
+            )
+
+        parts.append(f"--{boundary}--\r\n".encode("utf-8"))
+        form_body = b"".join(parts)
+        ct = f"multipart/form-data; boundary={boundary}"
+
+        return self._request(
+            "POST",
+            "/api/graph/ontology/generate",
+            form_data=form_body,
+            content_type=ct,
+        )
+
+    def build_graph(self, project_id: str) -> dict:
+        """POST /api/graph/build - start async graph building.
+
+        Returns: {project_id, graph_id, task_id, status}
+        """
+        return self._request(
+            "POST", "/api/graph/build", json_data={"project_id": project_id}
+        )
+
+    def poll_graph_build(
+        self, task_id: str, max_wait: int = 600, interval: int = 5
+    ) -> dict:
+        """POST /api/graph/build/status - poll until completed or timeout.
+
+        Returns final status dict with graph_id.
+        """
+        deadline = time.time() + max_wait
+        while time.time() < deadline:
+            resp = self._request(
+                "POST",
+                "/api/graph/build/status",
+                json_data={"task_id": task_id},
+            )
+            data = resp.get("data", resp)
+            status = data.get("status", "")
+            if status == "completed":
+                return data
+            if status in ("failed", "error"):
+                raise RuntimeError(
+                    f"Graph build failed: {data.get('error', 'unknown')}"
+                )
+            time.sleep(interval)
+        raise RuntimeError(
+            f"Graph build timed out after {max_wait}s (task_id={task_id})"
+        )
+
+    # -- Stage 2: Simulation Setup --------------------------------------------
+
+    def create_simulation(
+        self,
+        project_id: str,
+        graph_id: str,
+        enable_twitter: bool = True,
+        enable_reddit: bool = True,
+    ) -> dict:
+        """POST /api/simulation/create
+
+        Returns: {simulation_id, status}
+        """
+        return self._request(
+            "POST",
+            "/api/simulation/create",
+            json_data={
+                "project_id": project_id,
+                "graph_id": graph_id,
+                "enable_twitter": enable_twitter,
+                "enable_reddit": enable_reddit,
+            },
+        )
+
+    def prepare_simulation(self, simulation_id: str) -> dict:
+        """POST /api/simulation/prepare - async profile generation.
+
+        Returns: {simulation_id, task_id, status, expected_entities_count}
+        """
+        return self._request(
+            "POST",
+            "/api/simulation/prepare",
+            json_data={"simulation_id": simulation_id},
+        )
+
+    def poll_prepare(
+        self, task_id: str, max_wait: int = 900, interval: int = 10
+    ) -> dict:
+        """POST /api/simulation/prepare/status - poll until ready."""
+        deadline = time.time() + max_wait
+        while time.time() < deadline:
+            resp = self._request(
+                "POST",
+                "/api/simulation/prepare/status",
+                json_data={"task_id": task_id},
+            )
+            data = resp.get("data", resp)
+            status = data.get("status", "")
+            if status == "completed":
+                return data
+            if status in ("failed", "error"):
+                raise RuntimeError(
+                    f"Simulation prepare failed: {data.get('error', 'unknown')}"
+                )
+            time.sleep(interval)
+        raise RuntimeError(
+            f"Simulation prepare timed out after {max_wait}s (task_id={task_id})"
+        )
+
+    # -- Stage 3: Simulation Execution ----------------------------------------
+
+    def start_simulation(
+        self,
+        simulation_id: str,
+        platform: str = "parallel",
+        max_rounds: int = 100,
+    ) -> dict:
+        """POST /api/simulation/start
+
+        Returns: {simulation_id, runner_status, process_pid}
+        """
+        return self._request(
+            "POST",
+            "/api/simulation/start",
+            json_data={
+                "simulation_id": simulation_id,
+                "platform": platform,
+                "max_rounds": max_rounds,
+            },
+        )
+
+    def poll_run_status(
+        self, simulation_id: str, max_wait: int = 1800, interval: int = 15
+    ) -> dict:
+        """GET /api/simulation/{simulation_id}/run-status - poll until completed.
+
+        Returns: {runner_status, current_round, total_rounds, progress}
+        """
+        deadline = time.time() + max_wait
+        while time.time() < deadline:
+            resp = self._request(
+                "GET", f"/api/simulation/{simulation_id}/run-status"
+            )
+            data = resp.get("data", resp)
+            status = data.get("runner_status", "")
+            if status == "completed":
+                return data
+            if status in ("failed", "error", "stopped"):
+                raise RuntimeError(
+                    f"Simulation run failed: status={status}, "
+                    f"detail={data.get('error', 'unknown')}"
+                )
+            time.sleep(interval)
+        raise RuntimeError(
+            f"Simulation run timed out after {max_wait}s "
+            f"(simulation_id={simulation_id})"
+        )
+
+    def stop_simulation(self, simulation_id: str) -> dict:
+        """POST /api/simulation/stop"""
+        return self._request(
+            "POST",
+            "/api/simulation/stop",
+            json_data={"simulation_id": simulation_id},
+        )
+
+    # -- Stage 4: Report ------------------------------------------------------
+
+    def generate_report(self, simulation_id: str) -> dict:
+        """POST /api/report/generate - async report generation.
+
+        Returns: {report_id, task_id, status}
+        """
+        return self._request(
+            "POST",
+            "/api/report/generate",
+            json_data={"simulation_id": simulation_id},
+        )
+
+    def poll_report(
+        self, task_id: str, max_wait: int = 600, interval: int = 5
+    ) -> dict:
+        """POST /api/report/generate/status - poll until completed."""
+        deadline = time.time() + max_wait
+        while time.time() < deadline:
+            resp = self._request(
+                "POST",
+                "/api/report/generate/status",
+                json_data={"task_id": task_id},
+            )
+            data = resp.get("data", resp)
+            status = data.get("status", "")
+            if status == "completed":
+                return data
+            if status in ("failed", "error"):
+                raise RuntimeError(
+                    f"Report generation failed: {data.get('error', 'unknown')}"
+                )
+            time.sleep(interval)
+        raise RuntimeError(
+            f"Report generation timed out after {max_wait}s (task_id={task_id})"
+        )
+
+    def get_report(self, report_id: str) -> dict:
+        """GET /api/report/{report_id}
+
+        Returns: {report_id, simulation_id, status, sections: [{index, title, content}]}
+        """
+        return self._request("GET", f"/api/report/{report_id}")
+
+
+# ---------------------------------------------------------------------------
+# PRD Translation
+# ---------------------------------------------------------------------------
+
+def extract_simulation_context(prd_path: Path) -> dict:
+    """Parse PRD markdown to extract simulation seed material.
+
+    Looks for (case-insensitive):
+    - Project name: from first H1 heading, or filename
+    - Simulation requirement: from ## Problem Statement, ## Value Proposition,
+      ## Overview, ## Summary sections
+    - Target audience: from ## Target Audience, ## Users, ## User Personas sections
+
+    Fallback: first 2000 chars of PRD as simulation_requirement.
+
+    Returns: {
+        "project_name": str,
+        "simulation_requirement": str,
+        "target_audience": str,
+        "prd_summary": str
+    }
+    """
+    text = _safe_read(prd_path)
+
+    result: Dict[str, str] = {
+        "project_name": "",
+        "simulation_requirement": "",
+        "target_audience": "",
+        "prd_summary": "",
+    }
+
+    # Extract project name from first H1 heading
+    h1_match = re.search(r"^#\s+(.+)$", text, re.MULTILINE)
+    if h1_match:
+        result["project_name"] = h1_match.group(1).strip()
+    else:
+        # Fallback to filename without extension
+        result["project_name"] = prd_path.stem.replace("-", " ").replace("_", " ").title()
+
+    # Split into sections by ## headings
+    sections = _split_sections(text)
+
+    # Keywords for simulation requirement (priority order)
+    req_keywords = [
+        "problem statement",
+        "value proposition",
+        "overview",
+        "summary",
+    ]
+
+    # Keywords for target audience
+    audience_keywords = [
+        "target audience",
+        "users",
+        "user personas",
+    ]
+
+    for heading, body in sections.items():
+        heading_lower = heading.lower().strip()
+        # Check for simulation requirement sections
+        if not result["simulation_requirement"]:
+            for kw in req_keywords:
+                if kw in heading_lower:
+                    result["simulation_requirement"] = body.strip()
+                    break
+        # Check for target audience sections
+        if not result["target_audience"]:
+            for kw in audience_keywords:
+                if kw in heading_lower:
+                    result["target_audience"] = body.strip()
+                    break
+
+    # Fallback: use first 2000 chars of PRD as simulation_requirement
+    if not result["simulation_requirement"]:
+        result["simulation_requirement"] = text[:2000].strip()
+
+    # PRD summary: first 200 chars for logging
+    result["prd_summary"] = text[:200].strip()
+
+    return result
+
+
+def _split_sections(text: str, level: int = 2) -> Dict[str, str]:
+    """Split markdown text into sections by heading level.
+
+    Returns {heading_text: body_text} preserving order.
+    """
+    prefix = "#" * level
+    pattern = re.compile(rf"^{prefix}\s+(.+)$", re.MULTILINE)
+    matches = list(pattern.finditer(text))
+    sections: Dict[str, str] = {}
+    for i, m in enumerate(matches):
+        heading = m.group(1).strip()
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+        sections[heading] = text[start:end].strip()
+    return sections
+
+
+# ---------------------------------------------------------------------------
+# Pipeline State Management
+# ---------------------------------------------------------------------------
+
+def _update_pipeline_state(output_dir: Path, state: dict) -> None:
+    """Write pipeline-state.json atomically."""
+    state["updated_at"] = _now_iso()
+    state_path = output_dir / "mirofish" / "pipeline-state.json"
+    _write_json(state_path, state)
+
+
+def _load_pipeline_state(output_dir: Path) -> Optional[dict]:
+    """Load existing pipeline state, or None."""
+    state_path = output_dir / "mirofish" / "pipeline-state.json"
+    if not state_path.exists():
+        return None
+    try:
+        text = _safe_read(state_path)
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError, OSError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Report Normalization
+# ---------------------------------------------------------------------------
+
+# Sentiment keyword sets for simple heuristic analysis
+_POSITIVE_KEYWORDS = [
+    "positive", "strong", "adoption", "interest", "favorable",
+    "loved", "benefit", "opportunity", "success", "growth",
+    "promising", "enthusiastic", "excited", "valuable",
+]
+_NEGATIVE_KEYWORDS = [
+    "concern", "risk", "negative", "reluctance", "resistance",
+    "problem", "issue", "challenge", "difficult", "unfavorable",
+    "reject", "opposed", "cautious", "wary", "worried",
+]
+
+
+def normalize_report(
+    report_data: dict, simulation_data: Optional[dict] = None
+) -> dict:
+    """Convert MiroFish report into Loki Mode advisory format.
+
+    Analyzes report sections to extract:
+    - overall_sentiment: positive/negative/mixed
+    - confidence: low/medium/high
+    - sentiment_score: 0.0-1.0 (keyword-based heuristic)
+    - key_concerns: list of risk/concern strings
+    - feature_rankings: list of {feature, reception_score}
+    - notable_quotes: interesting agent reactions (max 5)
+    - recommendation: proceed/review_concerns/reconsider
+
+    The sentiment analysis uses simple keyword matching since we cannot
+    import NLP libraries.
+
+    Returns the full mirofish-context.json structure.
+    """
+    data = report_data.get("data", report_data)
+    sections = data.get("sections", [])
+
+    # Combine all section content for keyword analysis
+    all_content = " ".join(s.get("content", "") for s in sections).lower()
+
+    # --- Sentiment score (keyword heuristic) ---
+    pos_count = sum(1 for kw in _POSITIVE_KEYWORDS if kw in all_content)
+    neg_count = sum(1 for kw in _NEGATIVE_KEYWORDS if kw in all_content)
+    total_kw = pos_count + neg_count
+    if total_kw > 0:
+        sentiment_score = round(pos_count / total_kw, 2)
+    else:
+        sentiment_score = 0.5  # neutral default
+
+    # Overall sentiment classification
+    if sentiment_score >= 0.65:
+        overall_sentiment = "positive"
+    elif sentiment_score <= 0.35:
+        overall_sentiment = "negative"
+    else:
+        overall_sentiment = "mixed"
+
+    # --- Confidence level ---
+    # Based on available data richness
+    section_count = len(sections)
+    entity_count = 0
+    round_count = 0
+    if simulation_data:
+        sim_inner = simulation_data.get("data", simulation_data)
+        entity_count = sim_inner.get("expected_entities_count", 0)
+        round_count = sim_inner.get("total_rounds", 0)
+
+    if section_count >= 5 and (entity_count >= 50 or round_count >= 80):
+        confidence = "high"
+    elif section_count >= 3:
+        confidence = "medium"
+    else:
+        confidence = "low"
+
+    # --- Key concerns ---
+    key_concerns: List[str] = []
+    for section in sections:
+        title = section.get("title", "").lower()
+        content = section.get("content", "")
+        if "concern" in title or "risk" in title:
+            # Extract numbered items
+            for m in re.finditer(
+                r"\d+\.\s+([^.]+?)(?::\s*(.+?))?(?=\d+\.\s|\Z)",
+                content,
+                re.DOTALL,
+            ):
+                concern = m.group(1).strip()
+                if concern:
+                    key_concerns.append(concern)
+
+    # --- Feature rankings ---
+    feature_rankings: List[Dict[str, Any]] = []
+    for section in sections:
+        title = section.get("title", "").lower()
+        content = section.get("content", "")
+        if "feature" in title or "ranking" in title or "reception" in title:
+            # Extract lines like: N. Feature name (reception: 0.XX)
+            for m in re.finditer(
+                r"\d+\.\s+(.+?)\s*\(reception:\s*([\d.]+)\)",
+                content,
+            ):
+                feature_rankings.append({
+                    "feature": m.group(1).strip(),
+                    "reception_score": float(m.group(2)),
+                })
+
+    # --- Notable quotes ---
+    notable_quotes: List[str] = []
+    for section in sections:
+        title = section.get("title", "").lower()
+        content = section.get("content", "")
+        if "notable" in title or "reaction" in title or "quote" in title:
+            for m in re.finditer(r"'([^']{10,})'", content):
+                notable_quotes.append(m.group(1).strip())
+                if len(notable_quotes) >= 5:
+                    break
+        if len(notable_quotes) >= 5:
+            break
+
+    # --- Recommendation ---
+    if sentiment_score >= 0.65 and len(key_concerns) <= 2:
+        recommendation = "proceed"
+    elif sentiment_score <= 0.35:
+        recommendation = "reconsider"
+    else:
+        recommendation = "review_concerns"
+
+    return {
+        "source": "mirofish",
+        "version": "1.0",
+        "generated_at": _now_iso(),
+        "report_id": data.get("report_id", ""),
+        "simulation_id": data.get("simulation_id", ""),
+        "analysis": {
+            "overall_sentiment": overall_sentiment,
+            "sentiment_score": sentiment_score,
+            "confidence": confidence,
+            "recommendation": recommendation,
+            "key_concerns": key_concerns,
+            "feature_rankings": feature_rankings,
+            "notable_quotes": notable_quotes,
+        },
+        "section_count": section_count,
+        "raw_sections": [
+            {"title": s.get("title", ""), "index": s.get("index", i)}
+            for i, s in enumerate(sections)
+        ],
+    }
+
+
+def build_mirofish_tasks(report_data: dict) -> list:
+    """Extract actionable items from report sections.
+
+    Looks for:
+    - Sections with "risk" or "concern" in title -> high priority tasks
+    - Sections with "recommendation" in title -> medium priority tasks
+    - Bullet points starting with "Should", "Must", "Consider" -> tasks
+
+    Returns list of {id, title, description, priority, source, category}.
+    """
+    data = report_data.get("data", report_data)
+    sections = data.get("sections", [])
+    tasks: List[Dict[str, Any]] = []
+    task_counter = 0
+
+    for section in sections:
+        title = section.get("title", "").lower()
+        content = section.get("content", "")
+
+        # Determine priority and category based on section title
+        if "risk" in title or "concern" in title:
+            priority = "high"
+            category = "risk_mitigation"
+        elif "recommendation" in title:
+            priority = "medium"
+            category = "recommendation"
+        else:
+            # Scan content for actionable keywords even in other sections
+            priority = "low"
+            category = "insight"
+
+        # Extract sentences starting with action keywords
+        for m in re.finditer(
+            r"(?:^|(?<=\.\s)|(?<=\d\.\s))"
+            r"((?:Should|Must|Consider|Recommendation:)\s+[^.]+\.?)",
+            content,
+            re.MULTILINE,
+        ):
+            task_counter += 1
+            task_text = m.group(1).strip().rstrip(".")
+            tasks.append({
+                "id": f"mirofish-{task_counter:03d}",
+                "title": task_text[:120],
+                "description": task_text,
+                "priority": priority,
+                "source": "mirofish",
+                "category": category,
+            })
+
+    return tasks
+
+
+# ---------------------------------------------------------------------------
+# Pipeline Summary Generation
+# ---------------------------------------------------------------------------
+
+def _build_summary_markdown(context: dict, tasks: list) -> str:
+    """Build a human-readable summary markdown from normalized data."""
+    lines: List[str] = []
+    analysis = context.get("analysis", {})
+
+    lines.append("# MiroFish Market Validation Summary")
+    lines.append("")
+    lines.append(f"Generated: {context.get('generated_at', 'unknown')}")
+    lines.append(f"Report ID: {context.get('report_id', 'unknown')}")
+    lines.append(f"Simulation ID: {context.get('simulation_id', 'unknown')}")
+    lines.append("")
+
+    lines.append("## Overall Assessment")
+    lines.append("")
+    lines.append(f"- Sentiment: {analysis.get('overall_sentiment', 'unknown')}")
+    lines.append(f"- Sentiment Score: {analysis.get('sentiment_score', 'N/A')}")
+    lines.append(f"- Confidence: {analysis.get('confidence', 'unknown')}")
+    lines.append(f"- Recommendation: {analysis.get('recommendation', 'unknown')}")
+    lines.append("")
+
+    concerns = analysis.get("key_concerns", [])
+    if concerns:
+        lines.append("## Key Concerns")
+        lines.append("")
+        for concern in concerns:
+            lines.append(f"- {concern}")
+        lines.append("")
+
+    rankings = analysis.get("feature_rankings", [])
+    if rankings:
+        lines.append("## Feature Rankings")
+        lines.append("")
+        for rank in rankings:
+            lines.append(
+                f"- {rank.get('feature', 'unknown')}: "
+                f"{rank.get('reception_score', 'N/A')}"
+            )
+        lines.append("")
+
+    quotes = analysis.get("notable_quotes", [])
+    if quotes:
+        lines.append("## Notable Agent Reactions")
+        lines.append("")
+        for quote in quotes:
+            lines.append(f"> {quote}")
+            lines.append("")
+
+    if tasks:
+        lines.append("## Action Items")
+        lines.append("")
+        for task in tasks:
+            prio = task.get("priority", "medium")
+            lines.append(f"- [{prio.upper()}] {task.get('title', '')}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Pipeline Orchestration
+# ---------------------------------------------------------------------------
+
+def run_pipeline(
+    client: MiroFishClient,
+    prd_path: Path,
+    output_dir: Path,
+    max_rounds: int = DEFAULT_MAX_ROUNDS,
+) -> int:
+    """Execute the 4-stage MiroFish pipeline.
+
+    Stage 1: Generate ontology from PRD (upload file + requirement)
+    Stage 2: Build knowledge graph (async, poll)
+    Stage 3: Create + prepare + run simulation (async, poll)
+    Stage 4: Generate + retrieve report (async, poll)
+
+    After each stage:
+    - Write stage output to output_dir/mirofish/
+    - Update pipeline-state.json
+
+    On completion:
+    - Write mirofish-context.json (normalized advisory)
+    - Write mirofish-tasks.json (queue-ready tasks)
+    - Write mirofish-summary.md (human-readable)
+
+    Returns 0 on success, 1 on failure.
+    """
+    mf_dir = output_dir / "mirofish"
+    mf_dir.mkdir(parents=True, exist_ok=True)
+
+    # Compute PRD hash for caching / dedup
+    prd_content = _safe_read(prd_path)
+    prd_hash = hashlib.sha256(prd_content.encode("utf-8")).hexdigest()[:16]
+
+    # Initialize pipeline state
+    state: Dict[str, Any] = {
+        "version": "1.0",
+        "prd_path": str(prd_path.resolve()),
+        "prd_hash": prd_hash,
+        "base_url": client.base_url,
+        "started_at": _now_iso(),
+        "updated_at": _now_iso(),
+        "status": "running",
+        "current_stage": 1,
+        "pid": os.getpid(),
+        "stages": {
+            "1_ontology": {"status": "pending"},
+            "2_graph": {"status": "pending"},
+            "3_simulation": {"status": "pending"},
+            "4_report": {"status": "pending"},
+        },
+        "error": None,
+    }
+    _update_pipeline_state(output_dir, state)
+
+    try:
+        # Extract simulation context from PRD
+        context = extract_simulation_context(prd_path)
+        print(
+            f"MiroFish: project={context['project_name']!r} "
+            f"prd_hash={prd_hash}"
+        )
+
+        # -- Stage 1: Ontology ------------------------------------------------
+        print("MiroFish Stage 1/4: Generating ontology...")
+        onto_resp = client.generate_ontology(
+            prd_path=str(prd_path),
+            simulation_requirement=context["simulation_requirement"],
+            project_name=context["project_name"],
+        )
+        onto_data = onto_resp.get("data", onto_resp)
+        project_id = onto_data["project_id"]
+
+        state["stages"]["1_ontology"] = {
+            "status": "completed",
+            "project_id": project_id,
+            "completed_at": _now_iso(),
+        }
+        state["current_stage"] = 2
+        _update_pipeline_state(output_dir, state)
+        _write_json(mf_dir / "ontology.json", onto_resp)
+        print(f"MiroFish Stage 1/4: Ontology complete (project={project_id})")
+
+        # -- Stage 2: Graph Build ---------------------------------------------
+        print("MiroFish Stage 2/4: Building knowledge graph...")
+        build_resp = client.build_graph(project_id)
+        build_data = build_resp.get("data", build_resp)
+        task_id = build_data["task_id"]
+
+        state["stages"]["2_graph"]["status"] = "running"
+        state["stages"]["2_graph"]["task_id"] = task_id
+        _update_pipeline_state(output_dir, state)
+
+        graph_result = client.poll_graph_build(task_id)
+        graph_id = graph_result.get("graph_id", "")
+
+        state["stages"]["2_graph"] = {
+            "status": "completed",
+            "graph_id": graph_id,
+            "completed_at": _now_iso(),
+        }
+        state["current_stage"] = 3
+        _update_pipeline_state(output_dir, state)
+        _write_json(mf_dir / "graph.json", graph_result)
+        print(f"MiroFish Stage 2/4: Graph complete (graph_id={graph_id})")
+
+        # -- Stage 3: Simulation ----------------------------------------------
+        print("MiroFish Stage 3/4: Running simulation...")
+
+        # Create simulation
+        sim_resp = client.create_simulation(project_id, graph_id)
+        sim_data = sim_resp.get("data", sim_resp)
+        simulation_id = sim_data["simulation_id"]
+
+        state["stages"]["3_simulation"]["status"] = "running"
+        state["stages"]["3_simulation"]["simulation_id"] = simulation_id
+        _update_pipeline_state(output_dir, state)
+
+        # Prepare simulation (async profile generation)
+        prep_resp = client.prepare_simulation(simulation_id)
+        prep_data = prep_resp.get("data", prep_resp)
+        prep_task_id = prep_data["task_id"]
+
+        prep_result = client.poll_prepare(prep_task_id)
+
+        # Start simulation run
+        start_resp = client.start_simulation(
+            simulation_id, max_rounds=max_rounds
+        )
+        _write_json(mf_dir / "simulation-start.json", start_resp)
+
+        # Poll until simulation completes
+        sim_result = client.poll_run_status(simulation_id)
+
+        state["stages"]["3_simulation"] = {
+            "status": "completed",
+            "simulation_id": simulation_id,
+            "completed_at": _now_iso(),
+        }
+        state["current_stage"] = 4
+        _update_pipeline_state(output_dir, state)
+        _write_json(mf_dir / "simulation-result.json", sim_result)
+        print(
+            f"MiroFish Stage 3/4: Simulation complete "
+            f"(simulation_id={simulation_id})"
+        )
+
+        # -- Stage 4: Report --------------------------------------------------
+        print("MiroFish Stage 4/4: Generating report...")
+        report_resp = client.generate_report(simulation_id)
+        report_data = report_resp.get("data", report_resp)
+        report_task_id = report_data["task_id"]
+
+        state["stages"]["4_report"]["status"] = "running"
+        state["stages"]["4_report"]["task_id"] = report_task_id
+        _update_pipeline_state(output_dir, state)
+
+        report_result = client.poll_report(report_task_id)
+        report_id = report_result.get("report_id", "")
+
+        # Fetch full report
+        full_report = client.get_report(report_id)
+        _write_json(mf_dir / "report.json", full_report)
+
+        state["stages"]["4_report"] = {
+            "status": "completed",
+            "report_id": report_id,
+            "completed_at": _now_iso(),
+        }
+        _update_pipeline_state(output_dir, state)
+        print(f"MiroFish Stage 4/4: Report complete (report_id={report_id})")
+
+        # -- Normalize and write final outputs --------------------------------
+        normalized = normalize_report(full_report, simulation_data=prep_result)
+        tasks = build_mirofish_tasks(full_report)
+        summary_md = _build_summary_markdown(normalized, tasks)
+
+        _write_json(output_dir / "mirofish-context.json", normalized)
+        _write_json(output_dir / "mirofish-tasks.json", tasks)
+        _write_atomic(output_dir / "mirofish-summary.md", summary_md)
+
+        # Mark pipeline complete
+        state["status"] = "completed"
+        state["completed_at"] = _now_iso()
+        _update_pipeline_state(output_dir, state)
+
+        print(
+            f"MiroFish: Pipeline complete. "
+            f"Sentiment={normalized['analysis']['overall_sentiment']} "
+            f"Recommendation={normalized['analysis']['recommendation']} "
+            f"Tasks={len(tasks)}"
+        )
+        return 0
+
+    except RuntimeError as exc:
+        state["status"] = "failed"
+        state["error"] = str(exc)
+        _update_pipeline_state(output_dir, state)
+        print(f"ERROR: MiroFish pipeline failed: {exc}", file=sys.stderr)
+        return 1
+    except KeyError as exc:
+        state["status"] = "failed"
+        state["error"] = f"Missing key in API response: {exc}"
+        _update_pipeline_state(output_dir, state)
+        print(
+            f"ERROR: MiroFish pipeline failed (missing key): {exc}",
+            file=sys.stderr,
+        )
+        return 1
+    except Exception as exc:
+        state["status"] = "failed"
+        state["error"] = str(exc)
+        _update_pipeline_state(output_dir, state)
+        print(
+            f"ERROR: MiroFish pipeline failed unexpectedly: {exc}",
+            file=sys.stderr,
+        )
+        return 1
+
+
+def run_background(
+    prd_path: str,
+    output_dir: str,
+    base_url: str,
+    max_rounds: int = DEFAULT_MAX_ROUNDS,
+) -> int:
+    """Fork child process to run pipeline. Parent returns 0 immediately.
+
+    Uses os.fork(). Child process:
+    1. Detaches from terminal (setsid)
+    2. Redirects stdout/stderr to output_dir/mirofish/pipeline.log
+    3. Writes PID to pipeline-state.json
+    4. Runs run_pipeline()
+    5. Updates state to completed/failed
+
+    Parent returns 0 immediately.
+    """
+    # Ensure output directory exists before fork
+    mf_dir = Path(output_dir) / "mirofish"
+    mf_dir.mkdir(parents=True, exist_ok=True)
+
+    pid = os.fork()
+    if pid > 0:
+        # Parent process
+        print(f"MiroFish: Background pipeline started (pid={pid})")
+        return 0
+
+    # Child process
+    try:
+        os.setsid()
+
+        # Redirect stdout/stderr to log file
+        log_path = mf_dir / "pipeline.log"
+        log_fd = os.open(
+            str(log_path),
+            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+            0o644,
+        )
+        os.dup2(log_fd, 1)  # stdout
+        os.dup2(log_fd, 2)  # stderr
+        os.close(log_fd)
+
+        # Close stdin
+        devnull = os.open(os.devnull, os.O_RDONLY)
+        os.dup2(devnull, 0)
+        os.close(devnull)
+
+        # Set up signal handler so graceful termination updates state
+        def _handle_term(signum: int, frame: Any) -> None:
+            state = _load_pipeline_state(Path(output_dir))
+            if state:
+                state["status"] = "cancelled"
+                state["updated_at"] = _now_iso()
+                state["error"] = f"Cancelled by signal {signum}"
+                _update_pipeline_state(Path(output_dir), state)
+            os._exit(130)
+
+        signal.signal(signal.SIGTERM, _handle_term)
+        signal.signal(signal.SIGINT, _handle_term)
+
+        client = MiroFishClient(base_url=base_url)
+        exit_code = run_pipeline(
+            client=client,
+            prd_path=Path(prd_path),
+            output_dir=Path(output_dir),
+            max_rounds=max_rounds,
+        )
+        os._exit(exit_code)  # noqa: use _exit in forked child
+    except Exception:
+        os._exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Docker Management
+# ---------------------------------------------------------------------------
+
+def _run_docker(
+    args: List[str], check: bool = False, capture: bool = True
+) -> subprocess.CompletedProcess:
+    """Run docker command, return CompletedProcess."""
+    cmd = ["docker"] + args
+    return subprocess.run(
+        cmd,
+        capture_output=capture,
+        text=True,
+        timeout=120,
+        check=check,
+    )
+
+
+def check_container() -> str:
+    """Check MiroFish container status.
+
+    Returns: 'running', 'stopped', or 'not_found'.
+    """
+    result = _run_docker(
+        ["inspect", "--format", "{{.State.Status}}", CONTAINER_NAME]
+    )
+    if result.returncode != 0:
+        return "not_found"
+    status = result.stdout.strip().lower()
+    if status == "running":
+        return "running"
+    return "stopped"
+
+
+def start_container(
+    image: str,
+    port: int = DEFAULT_PORT,
+    env_vars: Optional[Dict[str, str]] = None,
+) -> bool:
+    """Start MiroFish Docker container. Check-before-create pattern.
+
+    1. If running: return True (already running)
+    2. If stopped: docker start loki-mirofish
+    3. If not_found: docker run -d --name loki-mirofish
+           -p {port}:5001 -e LLM_API_KEY -e ZEP_API_KEY {image}
+    4. Wait for healthy (poll /health, max 60s)
+
+    Passes LLM_API_KEY and ZEP_API_KEY from os.environ if present.
+    """
+    status = check_container()
+
+    if status == "running":
+        print(f"MiroFish: Container {CONTAINER_NAME} already running")
+        return True
+
+    if status == "stopped":
+        print(f"MiroFish: Starting stopped container {CONTAINER_NAME}")
+        result = _run_docker(["start", CONTAINER_NAME])
+        if result.returncode != 0:
+            print(
+                f"ERROR: Failed to start container: {result.stderr}",
+                file=sys.stderr,
+            )
+            return False
+    else:
+        # not_found -- create new container
+        print(f"MiroFish: Creating container {CONTAINER_NAME} from {image}")
+        cmd = [
+            "run", "-d",
+            "--name", CONTAINER_NAME,
+            "-p", f"{port}:5001",
+        ]
+
+        # Pass through environment variables
+        all_env = dict(env_vars or {})
+        for key in ("LLM_API_KEY", "ZEP_API_KEY"):
+            val = os.environ.get(key)
+            if val:
+                all_env[key] = val
+        for key, val in all_env.items():
+            cmd.extend(["-e", f"{key}={val}"])
+
+        cmd.append(image)
+        result = _run_docker(cmd)
+        if result.returncode != 0:
+            print(
+                f"ERROR: Failed to create container: {result.stderr}",
+                file=sys.stderr,
+            )
+            return False
+
+    # Wait for healthy
+    base_url = f"http://localhost:{port}"
+    if wait_for_healthy(base_url):
+        print(f"MiroFish: Container healthy at {base_url}")
+        return True
+    else:
+        print(
+            f"ERROR: Container started but health check failed at {base_url}",
+            file=sys.stderr,
+        )
+        return False
+
+
+def stop_container() -> bool:
+    """Stop MiroFish container gracefully.
+
+    docker stop loki-mirofish --time 10, then docker rm if needed.
+    """
+    status = check_container()
+    if status == "not_found":
+        print(f"MiroFish: Container {CONTAINER_NAME} not found")
+        return True
+
+    if status == "running":
+        print(f"MiroFish: Stopping container {CONTAINER_NAME}")
+        result = _run_docker(["stop", "--time", "10", CONTAINER_NAME])
+        if result.returncode != 0:
+            print(
+                f"ERROR: Failed to stop container: {result.stderr}",
+                file=sys.stderr,
+            )
+            return False
+
+    # Remove stopped container
+    result = _run_docker(["rm", CONTAINER_NAME])
+    if result.returncode != 0:
+        print(
+            f"WARNING: Failed to remove container: {result.stderr}",
+            file=sys.stderr,
+        )
+        # Not a fatal error -- container is stopped
+    else:
+        print(f"MiroFish: Container {CONTAINER_NAME} removed")
+
+    return True
+
+
+def wait_for_healthy(base_url: str, max_wait: int = 60) -> bool:
+    """Poll GET {base_url}/health every 2s until ok or timeout."""
+    client = MiroFishClient(base_url=base_url, timeout=5)
+    deadline = time.time() + max_wait
+    while time.time() < deadline:
+        if client.health_check():
+            return True
+        time.sleep(2)
+    return False
+
+
+# ---------------------------------------------------------------------------
+# CLI Entry Points
+# ---------------------------------------------------------------------------
+
+def validate_prd(prd_path: Path, base_url: str = DEFAULT_URL) -> int:
+    """Validate PRD can be parsed for MiroFish. Returns 0 if valid."""
+    if not prd_path.exists():
+        print(f"ERROR: PRD file not found: {prd_path}", file=sys.stderr)
+        return 1
+
+    if prd_path.stat().st_size == 0:
+        print(f"ERROR: PRD file is empty: {prd_path}", file=sys.stderr)
+        return 1
+
+    try:
+        context = extract_simulation_context(prd_path)
+    except Exception as exc:
+        print(f"ERROR: Failed to parse PRD: {exc}", file=sys.stderr)
+        return 1
+
+    if not context.get("simulation_requirement"):
+        print(
+            "ERROR: Could not extract simulation requirement from PRD",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"MiroFish PRD validation: OK\n"
+        f"  Project: {context['project_name']}\n"
+        f"  Requirement length: {len(context['simulation_requirement'])} chars\n"
+        f"  Target audience: {'found' if context.get('target_audience') else 'not found'}"
+    )
+    return 0
+
+
+def show_status(output_dir: Path) -> int:
+    """Show pipeline status from pipeline-state.json."""
+    state = _load_pipeline_state(output_dir)
+    if state is None:
+        print("MiroFish: No pipeline state found. No pipeline has been run.")
+        return 0
+
+    print(f"MiroFish Pipeline Status")
+    print(f"  Status: {state.get('status', 'unknown')}")
+    print(f"  Started: {state.get('started_at', 'unknown')}")
+    print(f"  Updated: {state.get('updated_at', 'unknown')}")
+    print(f"  Current stage: {state.get('current_stage', 'unknown')}")
+    print(f"  PRD: {state.get('prd_path', 'unknown')}")
+
+    if state.get("completed_at"):
+        print(f"  Completed: {state['completed_at']}")
+
+    if state.get("error"):
+        print(f"  Error: {state['error']}")
+
+    stages = state.get("stages", {})
+    for stage_name, stage_data in sorted(stages.items()):
+        stage_status = stage_data.get("status", "unknown")
+        extra = ""
+        if stage_data.get("project_id"):
+            extra = f" (project={stage_data['project_id']})"
+        elif stage_data.get("graph_id"):
+            extra = f" (graph={stage_data['graph_id']})"
+        elif stage_data.get("simulation_id"):
+            extra = f" (simulation={stage_data['simulation_id']})"
+        elif stage_data.get("report_id"):
+            extra = f" (report={stage_data['report_id']})"
+        print(f"  Stage {stage_name}: {stage_status}{extra}")
+
+    # Check if background process is still running
+    pid = state.get("pid")
+    if pid and state.get("status") == "running":
+        try:
+            os.kill(pid, 0)  # Check if process exists
+            print(f"  Process: running (pid={pid})")
+        except OSError:
+            print(f"  Process: not running (pid={pid} -- may have crashed)")
+
+    return 0
+
+
+def resume_pipeline(output_dir: Path, base_url: str, max_rounds: int) -> int:
+    """Resume an interrupted pipeline from last completed stage."""
+    state = _load_pipeline_state(output_dir)
+    if state is None:
+        print(
+            "ERROR: No pipeline state found. Cannot resume.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if state.get("status") == "completed":
+        print("MiroFish: Pipeline already completed. Nothing to resume.")
+        return 0
+
+    prd_path = Path(state.get("prd_path", ""))
+    if not prd_path.exists():
+        print(
+            f"ERROR: Original PRD not found at {prd_path}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # For resume, we re-run the full pipeline.
+    # A more sophisticated implementation would skip completed stages,
+    # but that requires persisting all intermediate IDs.
+    print("MiroFish: Resuming pipeline (re-running from start)...")
+    client = MiroFishClient(base_url=base_url)
+    return run_pipeline(
+        client=client,
+        prd_path=prd_path,
+        output_dir=output_dir,
+        max_rounds=max_rounds,
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="MiroFish Market Validation Adapter for Loki Mode",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  python3 mirofish-adapter.py ./prd.md --output-dir .loki/\n"
+            "  python3 mirofish-adapter.py ./prd.md --validate\n"
+            "  python3 mirofish-adapter.py ./prd.md --json --url http://mf:5001\n"
+            "  python3 mirofish-adapter.py --status --output-dir .loki/\n"
+            "  python3 mirofish-adapter.py --health --url http://localhost:5001\n"
+            "  python3 mirofish-adapter.py --docker-start --docker-image mirofish/app\n"
+            "  python3 mirofish-adapter.py --docker-stop\n"
+        ),
+    )
+
+    # Positional
+    parser.add_argument("prd_path", nargs="?", help="Path to PRD file")
+
+    # Modes
+    parser.add_argument(
+        "--validate", action="store_true", help="Validate PRD only"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="as_json",
+        help="Output as JSON to stdout",
+    )
+    parser.add_argument(
+        "--status", action="store_true", help="Show pipeline status"
+    )
+    parser.add_argument(
+        "--resume",
+        action="store_true",
+        help="Resume interrupted pipeline",
+    )
+    parser.add_argument(
+        "--health", action="store_true", help="Health check only"
+    )
+    parser.add_argument(
+        "--docker-start",
+        action="store_true",
+        help="Start MiroFish container",
+    )
+    parser.add_argument(
+        "--docker-stop",
+        action="store_true",
+        help="Stop MiroFish container",
+    )
+
+    # Options
+    parser.add_argument(
+        "--output-dir", default=".loki", help="Output directory"
+    )
+    parser.add_argument(
+        "--url", default=DEFAULT_URL, help="MiroFish API URL"
+    )
+    parser.add_argument(
+        "--background",
+        action="store_true",
+        help="Run in background",
+    )
+    parser.add_argument(
+        "--max-rounds",
+        type=int,
+        default=DEFAULT_MAX_ROUNDS,
+        help="Maximum simulation rounds",
+    )
+    parser.add_argument(
+        "--docker-image", help="Docker image for --docker-start"
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_PORT,
+        help="Port for Docker container",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=int(os.environ.get("LOKI_MIROFISH_TIMEOUT", str(DEFAULT_TIMEOUT))),
+        help="Total pipeline timeout in seconds (default: 3600)",
+    )
+
+    args = parser.parse_args()
+
+    # -- Route to appropriate handler --
+
+    if args.docker_stop:
+        ok = stop_container()
+        sys.exit(0 if ok else 1)
+
+    if args.docker_start:
+        if not args.docker_image:
+            print(
+                "ERROR: --docker-image is required with --docker-start",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        ok = start_container(args.docker_image, port=args.port)
+        sys.exit(0 if ok else 1)
+
+    if args.health:
+        client = MiroFishClient(base_url=args.url)
+        ok = client.health_check()
+        if ok:
+            print(f"MiroFish: Healthy at {args.url}")
+        else:
+            print(f"MiroFish: NOT healthy at {args.url}", file=sys.stderr)
+        sys.exit(0 if ok else 1)
+
+    if args.status:
+        output_dir = Path(args.output_dir)
+        sys.exit(show_status(output_dir))
+
+    if args.resume:
+        output_dir = Path(args.output_dir)
+        sys.exit(resume_pipeline(output_dir, args.url, args.max_rounds))
+
+    # Remaining modes require prd_path
+    if not args.prd_path:
+        parser.error("prd_path is required for this mode")
+
+    prd_path = Path(args.prd_path)
+
+    if args.validate:
+        sys.exit(validate_prd(prd_path, base_url=args.url))
+
+    # Main pipeline run
+    if not prd_path.exists():
+        print(f"ERROR: PRD file not found: {prd_path}", file=sys.stderr)
+        sys.exit(1)
+
+    output_dir = Path(args.output_dir)
+
+    if args.as_json:
+        # JSON mode: extract context and output to stdout (no pipeline)
+        context = extract_simulation_context(prd_path)
+        output = {
+            "source": "mirofish",
+            "prd_path": str(prd_path),
+            "project_name": context["project_name"],
+            "simulation_requirement": context["simulation_requirement"],
+            "target_audience": context["target_audience"],
+            "prd_summary": context["prd_summary"],
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+
+    if args.background:
+        sys.exit(
+            run_background(
+                prd_path=str(prd_path),
+                output_dir=str(output_dir),
+                base_url=args.url,
+                max_rounds=args.max_rounds,
+            )
+        )
+
+    # Foreground pipeline run
+    client = MiroFishClient(base_url=args.url)
+    sys.exit(
+        run_pipeline(
+            client=client,
+            prd_path=prd_path,
+            output_dir=output_dir,
+            max_rounds=args.max_rounds,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()