From d014f2e0b6475b2eed837d6ddd8da9aaa3a0779b Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Sun, 5 Apr 2026 18:26:12 +0800
Subject: [PATCH 01/17] feat(idea): add exportable assessment reports in
 markdown and json

---
 README.md              | 11 ++++++
 README.zh-CN.md        | 11 ++++++
 src/api/routes/idea.py | 82 +++++++++++++++++++++++++++++++++++++++---
 src/models/schemas.py  |  6 ++++
 tests/test_api.py      | 36 +++++++++++++++++++
 5 files changed, 142 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 1332f34..c13a1e8 100644
--- a/README.md
+++ b/README.md
@@ -193,11 +193,22 @@ curl -X POST http://localhost:8000/api/v1/idea/assess \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}'
 
+# Export assessment report as Markdown
+curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=markdown" \
+  -H "Content-Type: application/json" \
+  -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}'
+
+# Export assessment report as JSON envelope
+curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
+  -H "Content-Type: application/json" \
+  -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}'
+
 # Response includes:
 # - verdict + existing_project_probability
 # - action_recommendation (build|fork|integrate) + action_rationale
 # - decision_signals for explainability
 # - similar_projects with evidence_snippets
+# - export endpoint supports markdown/json report output
 ```
 
 Full API documentation available at `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc` (ReDoc).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index e53bb62..d7a8054 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -146,6 +146,16 @@ curl -X POST http://localhost:8000/api/v1/search \
 curl -X POST http://localhost:8000/api/v1/idea/assess \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}'
+
+# 导出 Markdown 报告
+curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=markdown" \
+  -H "Content-Type: application/json" \
+  -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}'
+
+# 导出 JSON 报告
+curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
+  -H "Content-Type: application/json" \
+  -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}'
 ```
 
 响应包含：
@@ -153,6 +163,7 @@ curl -X POST http://localhost:8000/api/v1/idea/assess \
 - action_recommendation（build/fork/integrate）
 - decision_signals（判定依据）
 - similar_projects 与 evidence_snippets
+- 导出接口支持 markdown/json 两种报告格式
 
 ## 自托管
 
diff --git a/src/api/routes/idea.py b/src/api/routes/idea.py
index e98a333..17ecc4b 100644
--- a/src/api/routes/idea.py
+++ b/src/api/routes/idea.py
@@ -8,7 +8,8 @@
 
 import re
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Query
+from fastapi.responses import PlainTextResponse
 
 from src.core.llm.adapter import llm
 from src.core.llm.router import CallLevel
@@ -17,6 +18,7 @@
     DecisionSignals,
     DifferentiationOpportunity,
     IdeaAssessCandidate,
+    IdeaAssessExportResponse,
     IdeaAssessRequest,
     IdeaAssessResponse,
 )
@@ -175,9 +177,60 @@ def _action_recommendation(verdict: str, probability: float) -> tuple[str, str]:
     )
 
 
-@router.post("/idea/assess", response_model=IdeaAssessResponse)
-async def assess_idea(request: IdeaAssessRequest) -> IdeaAssessResponse:
-    """Assess if an idea is already implemented and suggest similar projects."""
+def _render_markdown_report(assessment: IdeaAssessResponse) -> str:
+    lines: list[str] = [
+        "# Idea Assessment Report",
+        "",
+        "## Input",
+        f"- Idea: {assessment.idea}",
+        "",
+        "## Verdict",
+        f"- Verdict: {assessment.verdict}",
+        f"- Confidence: {assessment.confidence}",
+        f"- Existing project probability: {assessment.existing_project_probability}",
+        f"- Recommended action: {assessment.action_recommendation}",
+        f"- Action rationale: {assessment.action_rationale}",
+        "",
+        "## Summary",
+        assessment.summary,
+        "",
+        "## Decision Signals",
+        f"- Candidate count: {assessment.decision_signals.candidate_count}",
+        f"- Top score: {assessment.decision_signals.top_score}",
+        f"- Base probability: {assessment.decision_signals.base_probability}",
+        f"- Calibrated probability: {assessment.decision_signals.calibrated_probability}",
+        f"- Avg keyword hits: {assessment.decision_signals.avg_keyword_hits}",
+        f"- Non-empty reason ratio: {assessment.decision_signals.nonempty_reason_ratio}",
+        "",
+        "## Similar Projects",
+    ]
+
+    if assessment.similar_projects:
+        for item in assessment.similar_projects:
+            lines.append(
+                f"- {item.rank}. {item.project} ({item.source or 'unknown'}, score={item.score})"
+            )
+            lines.append(f"  - Match reason: {item.match_reason}")
+            if item.evidence_snippets:
+                lines.append(f"  - Evidence: {' | '.join(item.evidence_snippets)}")
+    else:
+        lines.append("- No close matches found")
+
+    lines.extend(["", "## Differentiation Opportunities"])
+    for opp in assessment.differentiation_opportunities:
+        lines.append(f"- [{opp.category}] {opp.opportunity}")
+        lines.append(f"  - Rationale: {opp.rationale}")
+        lines.append(f"  - Effort: {opp.implementation_effort}")
+
+    lines.extend(["", "## Next Actions"])
+    for action in assessment.next_actions:
+        lines.append(f"- {action}")
+
+    return "\n".join(lines)
+
+
+async def _assess_core(request: IdeaAssessRequest) -> IdeaAssessResponse:
+    """Core idea assessment logic shared by standard and export endpoints."""
     combined_query = request.idea.strip()
     if request.product_doc:
         combined_query += "\n\n" + request.product_doc.strip()
@@ -309,3 +362,24 @@ async def assess_idea(request: IdeaAssessRequest) -> IdeaAssessResponse:
         differentiation_opportunities=opportunities,
         next_actions=next_actions,
     )
+
+
+@router.post("/idea/assess", response_model=IdeaAssessResponse)
+async def assess_idea(request: IdeaAssessRequest) -> IdeaAssessResponse:
+    """Assess if an idea is already implemented and suggest similar projects."""
+    return await _assess_core(request)
+
+
+@router.post("/idea/assess/export", response_model=IdeaAssessExportResponse)
+async def export_assessment_report(
+    request: IdeaAssessRequest,
+    format: str = Query("markdown", pattern="^(markdown|json)$"),
+) -> IdeaAssessExportResponse | PlainTextResponse:
+    """Export idea assessment as Markdown or JSON report."""
+    assessment = await _assess_core(request)
+
+    if format == "markdown":
+        markdown = _render_markdown_report(assessment)
+        return PlainTextResponse(content=markdown, media_type="text/markdown")
+
+    return IdeaAssessExportResponse(report_type="json", assessment=assessment)
diff --git a/src/models/schemas.py b/src/models/schemas.py
index b149cc4..b430ac6 100644
--- a/src/models/schemas.py
+++ b/src/models/schemas.py
@@ -123,6 +123,12 @@ class IdeaAssessResponse(BaseModel):
     generated_at: datetime = Field(default_factory=datetime.utcnow)
 
 
+class IdeaAssessExportResponse(BaseModel):
+    report_type: str  # markdown|json
+    assessment: IdeaAssessResponse
+    generated_at: datetime = Field(default_factory=datetime.utcnow)
+
+
 # ── Evaluation ───────────────────────────────────────────────────────────────
 
 
diff --git a/tests/test_api.py b/tests/test_api.py
index 916b983..a77d537 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -103,3 +103,39 @@ async def test_assess_idea_endpoint(client: AsyncClient):
     assert "calibrated_probability" in data["decision_signals"]
     if data["similar_projects"]:
         assert "evidence_snippets" in data["similar_projects"][0]
+
+
+@pytest.mark.asyncio
+async def test_assess_idea_export_markdown(client: AsyncClient):
+    resp = await client.post(
+        "/api/v1/idea/assess/export?format=markdown",
+        json={
+            "idea": "Build an open-source tool to compare similar Python web frameworks",
+            "product_doc": "Need semantic search and recommendation quality scoring.",
+        },
+    )
+    assert resp.status_code == 200
+    assert resp.headers.get("content-type", "").startswith("text/markdown")
+    body = resp.text
+    assert "# Idea Assessment Report" in body
+    assert "## Verdict" in body
+
+
+@pytest.mark.asyncio
+async def test_assess_idea_export_json(client: AsyncClient):
+    resp = await client.post(
+        "/api/v1/idea/assess/export?format=json",
+        json={
+            "idea": "Build an open-source tool to compare similar Python web frameworks",
+            "product_doc": "Need semantic search and recommendation quality scoring.",
+        },
+    )
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["report_type"] == "json"
+    assert "assessment" in data
+    assert data["assessment"]["verdict"] in {
+        "already_exists",
+        "similar_projects_exist",
+        "likely_novel",
+    }

From 48ed87c89fb94cf6a99734fd013354cd1ecbc73e Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Sun, 5 Apr 2026 22:04:39 +0800
Subject: [PATCH 02/17] feat(idea): add batch assessment api with verdict
 aggregation

---
 README.md              |  6 ++++++
 README.zh-CN.md        |  6 ++++++
 src/api/routes/idea.py | 32 ++++++++++++++++++++++++++++++++
 src/models/schemas.py  | 22 ++++++++++++++++++++++
 tests/test_api.py      | 30 ++++++++++++++++++++++++++++++
 5 files changed, 96 insertions(+)

diff --git a/README.md b/README.md
index c13a1e8..13405d1 100644
--- a/README.md
+++ b/README.md
@@ -203,12 +203,18 @@ curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}'
 
+# Batch assess multiple ideas
+curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6}'
+
 # Response includes:
 # - verdict + existing_project_probability
 # - action_recommendation (build|fork|integrate) + action_rationale
 # - decision_signals for explainability
 # - similar_projects with evidence_snippets
 # - export endpoint supports markdown/json report output
+# - batch endpoint returns per-idea results + verdict counts
 ```
 
 Full API documentation available at `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc` (ReDoc).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index d7a8054..7eeb3dc 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -156,6 +156,11 @@ curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=markdown" \
 curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}'
+
+# 批量评估多个想法
+curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6}'
 ```
 
 响应包含：
@@ -164,6 +169,7 @@ curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
 - decision_signals（判定依据）
 - similar_projects 与 evidence_snippets
 - 导出接口支持 markdown/json 两种报告格式
+- 批量接口返回逐条结果和 verdict 统计
 
 ## 自托管
 
diff --git a/src/api/routes/idea.py b/src/api/routes/idea.py
index 17ecc4b..acf60af 100644
--- a/src/api/routes/idea.py
+++ b/src/api/routes/idea.py
@@ -17,6 +17,8 @@
 from src.models.schemas import (
     DecisionSignals,
     DifferentiationOpportunity,
+    IdeaAssessBatchRequest,
+    IdeaAssessBatchResponse,
     IdeaAssessCandidate,
     IdeaAssessExportResponse,
     IdeaAssessRequest,
@@ -383,3 +385,33 @@ async def export_assessment_report(
         return PlainTextResponse(content=markdown, media_type="text/markdown")
 
     return IdeaAssessExportResponse(report_type="json", assessment=assessment)
+
+
+@router.post("/idea/assess/batch", response_model=IdeaAssessBatchResponse)
+async def assess_idea_batch(request: IdeaAssessBatchRequest) -> IdeaAssessBatchResponse:
+    """Assess multiple ideas/PRDs in one request."""
+    results: list[IdeaAssessResponse] = []
+    counters = {
+        "already_exists": 0,
+        "similar_projects_exist": 0,
+        "likely_novel": 0,
+    }
+
+    for item in request.items:
+        single_request = IdeaAssessRequest(
+            idea=item.idea,
+            product_doc=item.product_doc,
+            limit=request.limit,
+        )
+        assessment = await _assess_core(single_request)
+        results.append(assessment)
+        if assessment.verdict in counters:
+            counters[assessment.verdict] += 1
+
+    return IdeaAssessBatchResponse(
+        total=len(results),
+        already_exists=counters["already_exists"],
+        similar_projects_exist=counters["similar_projects_exist"],
+        likely_novel=counters["likely_novel"],
+        results=results,
+    )
diff --git a/src/models/schemas.py b/src/models/schemas.py
index b430ac6..990d07a 100644
--- a/src/models/schemas.py
+++ b/src/models/schemas.py
@@ -129,6 +129,28 @@ class IdeaAssessExportResponse(BaseModel):
     generated_at: datetime = Field(default_factory=datetime.utcnow)
 
 
+class IdeaAssessBatchItem(BaseModel):
+    idea: str = Field(..., description="Core product idea or one-line concept")
+    product_doc: str | None = Field(
+        None,
+        description="Optional detailed PRD/brief for deeper similarity analysis",
+    )
+
+
+class IdeaAssessBatchRequest(BaseModel):
+    items: list[IdeaAssessBatchItem] = Field(..., min_length=1, max_length=20)
+    limit: int = Field(8, ge=3, le=20, description="How many similar projects to inspect for each idea")
+
+
+class IdeaAssessBatchResponse(BaseModel):
+    total: int
+    already_exists: int
+    similar_projects_exist: int
+    likely_novel: int
+    results: list[IdeaAssessResponse] = Field(default_factory=list)
+    generated_at: datetime = Field(default_factory=datetime.utcnow)
+
+
 # ── Evaluation ───────────────────────────────────────────────────────────────
 
 
diff --git a/tests/test_api.py b/tests/test_api.py
index a77d537..be68ce7 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -139,3 +139,33 @@ async def test_assess_idea_export_json(client: AsyncClient):
         "similar_projects_exist",
         "likely_novel",
     }
+
+
+@pytest.mark.asyncio
+async def test_assess_idea_batch(client: AsyncClient):
+    resp = await client.post(
+        "/api/v1/idea/assess/batch",
+        json={
+            "items": [
+                {
+                    "idea": "Open-source API mocking tool for integration tests",
+                    "product_doc": "Need route templates and scenario replay.",
+                },
+                {
+                    "idea": "Collaborative PR review assistant for OSS maintainers",
+                    "product_doc": "Need triage automation and contributor onboarding hints.",
+                },
+            ],
+            "limit": 6,
+        },
+    )
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["total"] == 2
+    assert len(data["results"]) == 2
+    verdict_sum = (
+        data["already_exists"]
+        + data["similar_projects_exist"]
+        + data["likely_novel"]
+    )
+    assert verdict_sum == 2

From 3007dd662480db887d2cd66d981f1f500bd068ed Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Sun, 5 Apr 2026 22:20:12 +0800
Subject: [PATCH 03/17] feat(idea): add concurrent batch assessment with
 timeout controls

---
 README.md              |  3 +-
 README.zh-CN.md        |  3 +-
 src/api/routes/idea.py | 85 +++++++++++++++++++++++++++++++++++++-----
 src/models/schemas.py  |  7 ++++
 tests/test_api.py      |  2 +
 5 files changed, 89 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 13405d1..a5550fe 100644
--- a/README.md
+++ b/README.md
@@ -206,7 +206,7 @@ curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
 # Batch assess multiple ideas
 curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
   -H "Content-Type: application/json" \
-  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6}'
+  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
 
 # Response includes:
 # - verdict + existing_project_probability
@@ -215,6 +215,7 @@ curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
 # - similar_projects with evidence_snippets
 # - export endpoint supports markdown/json report output
 # - batch endpoint returns per-idea results + verdict counts
+# - batch supports max_concurrency and per_item_timeout_seconds
 ```
 
 Full API documentation available at `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc` (ReDoc).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 7eeb3dc..aa5a4e9 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -160,7 +160,7 @@ curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
 # 批量评估多个想法
 curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
   -H "Content-Type: application/json" \
-  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6}'
+  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
 ```
 
 响应包含：
@@ -170,6 +170,7 @@ curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
 - similar_projects 与 evidence_snippets
 - 导出接口支持 markdown/json 两种报告格式
 - 批量接口返回逐条结果和 verdict 统计
+- 批量接口支持 max_concurrency 与 per_item_timeout_seconds
 
 ## 自托管
 
diff --git a/src/api/routes/idea.py b/src/api/routes/idea.py
index acf60af..b063ab3 100644
--- a/src/api/routes/idea.py
+++ b/src/api/routes/idea.py
@@ -6,7 +6,9 @@
 
 from __future__ import annotations
 
+import asyncio
 import re
+from contextlib import suppress
 
 from fastapi import APIRouter, Query
 from fastapi.responses import PlainTextResponse
@@ -390,21 +392,86 @@ async def export_assessment_report(
 @router.post("/idea/assess/batch", response_model=IdeaAssessBatchResponse)
 async def assess_idea_batch(request: IdeaAssessBatchRequest) -> IdeaAssessBatchResponse:
     """Assess multiple ideas/PRDs in one request."""
-    results: list[IdeaAssessResponse] = []
-    counters = {
-        "already_exists": 0,
-        "similar_projects_exist": 0,
-        "likely_novel": 0,
-    }
+    semaphore = asyncio.Semaphore(request.max_concurrency)
 
-    for item in request.items:
+    async def _assess_one(item) -> IdeaAssessResponse:
         single_request = IdeaAssessRequest(
             idea=item.idea,
             product_doc=item.product_doc,
             limit=request.limit,
         )
-        assessment = await _assess_core(single_request)
-        results.append(assessment)
+
+        task: asyncio.Task[IdeaAssessResponse] | None = None
+        try:
+            async with semaphore:
+                task = asyncio.create_task(_assess_core(single_request))
+                return await asyncio.wait_for(
+                    task,
+                    timeout=request.per_item_timeout_seconds,
+                )
+        except asyncio.TimeoutError:
+            if task is not None:
+                task.cancel()
+                with suppress(asyncio.CancelledError, Exception):
+                    await task
+            return IdeaAssessResponse(
+                idea=item.idea,
+                verdict="likely_novel",
+                confidence="low",
+                existing_project_probability=0.0,
+                action_recommendation="build",
+                action_rationale="Assessment timed out; retry with fewer items or higher timeout.",
+                decision_signals=DecisionSignals(
+                    candidate_count=0,
+                    top_score=0.0,
+                    base_probability=0.0,
+                    calibrated_probability=0.0,
+                    avg_keyword_hits=0.0,
+                    nonempty_reason_ratio=0.0,
+                ),
+                summary="Assessment timed out before retrieval and scoring completed.",
+                similar_projects=[],
+                differentiation_opportunities=_build_opportunities("likely_novel"),
+                next_actions=[
+                    "Retry batch assessment with a larger per_item_timeout_seconds.",
+                    "Reduce batch size to improve per-item completion speed.",
+                ],
+            )
+        except Exception:
+            return IdeaAssessResponse(
+                idea=item.idea,
+                verdict="likely_novel",
+                confidence="low",
+                existing_project_probability=0.0,
+                action_recommendation="build",
+                action_rationale="Assessment encountered an internal error; please retry.",
+                decision_signals=DecisionSignals(
+                    candidate_count=0,
+                    top_score=0.0,
+                    base_probability=0.0,
+                    calibrated_probability=0.0,
+                    avg_keyword_hits=0.0,
+                    nonempty_reason_ratio=0.0,
+                ),
+                summary="Assessment failed due to an internal processing error.",
+                similar_projects=[],
+                differentiation_opportunities=_build_opportunities("likely_novel"),
+                next_actions=[
+                    "Retry the request.",
+                    "If failures persist, inspect service logs and provider connectivity.",
+                ],
+            )
+
+    tasks = [_assess_one(item) for item in request.items]
+    results = await asyncio.gather(*tasks)
+
+    counters = {
+        "already_exists": 0,
+        "similar_projects_exist": 0,
+        "likely_novel": 0,
+    }
+
+    for assessment in results:
         if assessment.verdict in counters:
             counters[assessment.verdict] += 1
 
diff --git a/src/models/schemas.py b/src/models/schemas.py
index 990d07a..ad24967 100644
--- a/src/models/schemas.py
+++ b/src/models/schemas.py
@@ -140,6 +140,13 @@ class IdeaAssessBatchItem(BaseModel):
 class IdeaAssessBatchRequest(BaseModel):
     items: list[IdeaAssessBatchItem] = Field(..., min_length=1, max_length=20)
     limit: int = Field(8, ge=3, le=20, description="How many similar projects to inspect for each idea")
+    max_concurrency: int = Field(4, ge=1, le=10, description="Max concurrent assessments in a batch")
+    per_item_timeout_seconds: float = Field(
+        25.0,
+        ge=5.0,
+        le=120.0,
+        description="Timeout for each single idea assessment",
+    )
 
 
 class IdeaAssessBatchResponse(BaseModel):
diff --git a/tests/test_api.py b/tests/test_api.py
index be68ce7..0e0cec6 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -157,6 +157,8 @@ async def test_assess_idea_batch(client: AsyncClient):
                 },
             ],
             "limit": 6,
+            "max_concurrency": 2,
+            "per_item_timeout_seconds": 30,
         },
     )
     assert resp.status_code == 200

From fdea2799c465754888b1240d48074383a0ad2e63 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Sun, 5 Apr 2026 22:42:13 +0800
Subject: [PATCH 04/17] feat(local-dev): move test ports and add batch idea
 assessment UI

---
 README.md                 |  20 +++---
 README.zh-CN.md           |  16 ++---
 docker-compose.yml        |   7 +-
 docs/self-hosting.md      |  12 ++--
 scripts/release_check.sh  |  20 +++---
 web/next.config.js        |   4 +-
 web/package.json          |   4 +-
 web/src/app/idea/page.tsx | 143 +++++++++++++++++++++++++++++++++++++-
 web/src/lib/api.ts        |  14 ++++
 9 files changed, 201 insertions(+), 39 deletions(-)

diff --git a/README.md b/README.md
index a5550fe..aab8b80 100644
--- a/README.md
+++ b/README.md
@@ -99,7 +99,7 @@ docker compose up -d
 
 Important: Owlscope does not provide shared AI provider keys. You must supply your own API keys for LLM-powered features.
 
-The Web App will be available at `http://localhost:3000` and the API at `http://localhost:8000`.
+The Web App will be available at `http://127.0.0.1:3100` and the API at `http://127.0.0.1:8010`.
 
 ### Local Development
 
@@ -121,7 +121,7 @@ DEEPSEEK_API_KEY=your_deepseek_key
 EOF
 
 # Start the API server
-uvicorn src.api.main:app --reload --port 8000
+uvicorn src.api.main:app --reload --host 127.0.0.1 --port 8010
 ```
 
 #### Web App (Next.js)
@@ -176,35 +176,35 @@ Notes:
 
 ```bash
 # Search
-curl -X POST http://localhost:8000/api/v1/search \
+curl -X POST http://127.0.0.1:8010/api/v1/search \
   -H "Content-Type: application/json" \
   -d '{"query": "lightweight Python web framework"}'
 
 # Evaluate a project
-curl http://localhost:8000/api/v1/evaluate/github:library:encode/httpx
+curl http://127.0.0.1:8010/api/v1/evaluate/github:library:encode/httpx
 
 # Compare projects
-curl -X POST http://localhost:8000/api/v1/compare \
+curl -X POST http://127.0.0.1:8010/api/v1/compare \
   -H "Content-Type: application/json" \
   -d '{"projects": ["github:library:fastapi/fastapi", "github:library:pallets/flask", "github:library:django/django"]}'
 
 # Assess whether an idea is already implemented
-curl -X POST http://localhost:8000/api/v1/idea/assess \
+curl -X POST http://127.0.0.1:8010/api/v1/idea/assess \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}'
 
 # Export assessment report as Markdown
-curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=markdown" \
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=markdown" \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}'
 
 # Export assessment report as JSON envelope
-curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=json" \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant for startup teams", "product_doc": "Need repo indexing, recommendation, and integration guidance"}'
 
 # Batch assess multiple ideas
-curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch" \
   -H "Content-Type: application/json" \
   -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
 
@@ -218,7 +218,7 @@ curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
 # - batch supports max_concurrency and per_item_timeout_seconds
 ```
 
-Full API documentation available at `http://localhost:8000/docs` (Swagger UI) or `http://localhost:8000/redoc` (ReDoc).
+Full API documentation available at `http://127.0.0.1:8010/docs` (Swagger UI) or `http://127.0.0.1:8010/redoc` (ReDoc).
 
 ### MCP Protocol
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index aa5a4e9..e965b0c 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -74,8 +74,8 @@ docker compose up -d
 ```
 
 启动后：
-- Web: http://localhost:3000
-- API: http://localhost:8000
+- Web: http://127.0.0.1:3100
+- API: http://127.0.0.1:8010
 
 重要说明：Owlscope 不提供共享 AI Key。所有 LLM 功能都需要用户自行配置 API Key。
 
@@ -96,7 +96,7 @@ DEEPSEEK_API_KEY=your_deepseek_key
 # ANTHROPIC_API_KEY=your_anthropic_key
 EOF
 
-uvicorn src.api.main:app --reload --port 8000
+uvicorn src.api.main:app --reload --host 127.0.0.1 --port 8010
 ```
 
 前端：
@@ -138,27 +138,27 @@ pytest -q -m integration tests/integration/test_compare_blackbox.py
 
 ```bash
 # 语义搜索
-curl -X POST http://localhost:8000/api/v1/search \
+curl -X POST http://127.0.0.1:8010/api/v1/search \
   -H "Content-Type: application/json" \
   -d '{"query": "lightweight Python web framework"}'
 
 # 想法评估（是否已有开源实现）
-curl -X POST http://localhost:8000/api/v1/idea/assess \
+curl -X POST http://127.0.0.1:8010/api/v1/idea/assess \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}'
 
 # 导出 Markdown 报告
-curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=markdown" \
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=markdown" \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}'
 
 # 导出 JSON 报告
-curl -X POST "http://localhost:8000/api/v1/idea/assess/export?format=json" \
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=json" \
   -H "Content-Type: application/json" \
   -d '{"idea": "AI coding workflow assistant", "product_doc": "Need repo indexing and recommendation"}'
 
 # 批量评估多个想法
-curl -X POST "http://localhost:8000/api/v1/idea/assess/batch" \
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch" \
   -H "Content-Type: application/json" \
   -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
 ```
diff --git a/docker-compose.yml b/docker-compose.yml
index 5566116..bdc35fe 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -5,7 +5,7 @@ services:
       context: .
       dockerfile: docker/Dockerfile.api
     ports:
-      - "8000:8000"
+      - "8010:8000"
     env_file:
       - .env
     depends_on:
@@ -26,11 +26,12 @@ services:
       context: ./web
       dockerfile: ../docker/Dockerfile.web
     ports:
-      - "3000:3000"
+      - "3100:3000"
     depends_on:
       - api
     environment:
-      - NEXT_PUBLIC_API_URL=http://api:8000
+      - NEXT_PUBLIC_API_URL=http://127.0.0.1:8010
+      - OWLSCOPE_API_ORIGIN=http://api:8000
     volumes:
       - ./web/src:/app/src
 
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index 4530536..c3e70a5 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -19,9 +19,9 @@ docker compose up -d
 ```
 
 Services:
-- Web: http://localhost:3000
-- API: http://localhost:8000
-- Swagger: http://localhost:8000/docs
+- Web: http://127.0.0.1:3100
+- API: http://127.0.0.1:8010
+- Swagger: http://127.0.0.1:8010/docs
 
 ## Environment Variables
 
@@ -42,7 +42,7 @@ Owlscope has deterministic fallbacks for some retrieval flows when model service
 python -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
-uvicorn src.api.main:app --reload --port 8000
+uvicorn src.api.main:app --reload --host 127.0.0.1 --port 8010
 ```
 
 ### Frontend
@@ -56,8 +56,8 @@ npm run dev
 ## Health Checks
 
 ```bash
-curl http://localhost:8000/health
-curl http://localhost:8000/api/v1/admin/monitor
+curl http://127.0.0.1:8010/health
+curl http://127.0.0.1:8010/api/v1/admin/monitor
 ```
 
 ## Data Notes
diff --git a/scripts/release_check.sh b/scripts/release_check.sh
index 9310179..01bc41c 100755
--- a/scripts/release_check.sh
+++ b/scripts/release_check.sh
@@ -4,6 +4,10 @@ set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$ROOT_DIR"
 
+API_HOST="${OWLSCOPE_API_HOST:-127.0.0.1}"
+API_PORT="${OWLSCOPE_API_PORT:-8010}"
+API_BASE="http://${API_HOST}:${API_PORT}"
+
 echo "[1/4] Running backend tests..."
 source .venv/bin/activate
 pytest -q -m "not integration"
@@ -14,19 +18,19 @@ npm run build
 popd >/dev/null
 
 echo "[3/4] Starting API for smoke checks..."
-lsof -ti:8000 | xargs kill -9 2>/dev/null || true
-python -m uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --log-level warning >/tmp/owlscope-release-check.log 2>&1 &
+lsof -ti:"$API_PORT" | xargs kill -9 2>/dev/null || true
+python -m uvicorn src.api.main:app --host "$API_HOST" --port "$API_PORT" --log-level warning >/tmp/owlscope-release-check.log 2>&1 &
 API_PID=$!
 trap 'kill "$API_PID" 2>/dev/null || true' EXIT
 
 for _ in {1..90}; do
-  if curl -fsS "http://localhost:8000/health" >/dev/null 2>&1; then
+  if curl -fsS "$API_BASE/health" >/dev/null 2>&1; then
     break
   fi
   sleep 1
 done
 
-if ! curl -fsS "http://localhost:8000/health" >/dev/null 2>&1; then
+if ! curl -fsS "$API_BASE/health" >/dev/null 2>&1; then
   echo "API health check failed"
   echo "--- recent API logs ---"
   tail -n 80 /tmp/owlscope-release-check.log || true
@@ -34,22 +38,22 @@ if ! curl -fsS "http://localhost:8000/health" >/dev/null 2>&1; then
 fi
 
 echo "[4/4] Smoke testing key endpoints..."
-curl -fsS -X POST "http://localhost:8000/api/v1/search" \
+curl -fsS -X POST "$API_BASE/api/v1/search" \
   -H "Content-Type: application/json" \
   -d '{"query":"python web framework"}' >/dev/null
 
-curl -fsS -X POST "http://localhost:8000/api/v1/idea/assess" \
+curl -fsS -X POST "$API_BASE/api/v1/idea/assess" \
   -H "Content-Type: application/json" \
   -d '{"idea":"Open-source assistant for startup idea validation"}' >/dev/null
 
 # Some environments may not have seeded comparison resources yet.
-EVALUATE_CODE=$(curl -s -o /tmp/owlscope-evaluate.out -w "%{http_code}" "http://localhost:8000/api/v1/evaluate/github:library:encode/httpx")
+EVALUATE_CODE=$(curl -s -o /tmp/owlscope-evaluate.out -w "%{http_code}" "$API_BASE/api/v1/evaluate/github:library:encode/httpx")
 if [[ "$EVALUATE_CODE" != "200" && "$EVALUATE_CODE" != "404" ]]; then
   echo "Unexpected /evaluate status: $EVALUATE_CODE"
   exit 1
 fi
 
-COMPARE_CODE=$(curl -s -o /tmp/owlscope-compare.out -w "%{http_code}" -X POST "http://localhost:8000/api/v1/compare" \
+COMPARE_CODE=$(curl -s -o /tmp/owlscope-compare.out -w "%{http_code}" -X POST "$API_BASE/api/v1/compare" \
   -H "Content-Type: application/json" \
   -d '{"projects":["github:library:fastapi/fastapi","github:library:pallets/flask"]}')
 if [[ "$COMPARE_CODE" != "200" && "$COMPARE_CODE" != "404" ]]; then
diff --git a/web/next.config.js b/web/next.config.js
index c5db160..d81681e 100644
--- a/web/next.config.js
+++ b/web/next.config.js
@@ -1,11 +1,13 @@
 /** @type {import('next').NextConfig} */
+const apiOrigin = process.env.OWLSCOPE_API_ORIGIN || "http://127.0.0.1:8010";
+
 const nextConfig = {
   // API proxy to backend
   async rewrites() {
     return [
       {
         source: "/api/:path*",
-        destination: "http://localhost:8000/api/:path*",
+        destination: `${apiOrigin}/api/:path*`,
       },
     ];
   },
diff --git a/web/package.json b/web/package.json
index bb94abf..dbf3f2e 100644
--- a/web/package.json
+++ b/web/package.json
@@ -3,9 +3,9 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev -H 127.0.0.1 -p 3100",
     "build": "next build",
-    "start": "next start",
+    "start": "next start -H 127.0.0.1 -p 3100",
     "lint": "next lint"
   },
   "dependencies": {
diff --git a/web/src/app/idea/page.tsx b/web/src/app/idea/page.tsx
index 8e5d99e..4813de8 100644
--- a/web/src/app/idea/page.tsx
+++ b/web/src/app/idea/page.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useState } from "react";
-import { assessIdea } from "@/lib/api";
+import { assessIdea, assessIdeaBatch } from "@/lib/api";
 
 type Verdict = "already_exists" | "similar_projects_exist" | "likely_novel";
 
@@ -42,6 +42,14 @@ interface IdeaAssessResult {
   next_actions: string[];
 }
 
+interface IdeaAssessBatchResult {
+  total: number;
+  already_exists: number;
+  similar_projects_exist: number;
+  likely_novel: number;
+  results: IdeaAssessResult[];
+}
+
 const VERDICT_UI: Record<Verdict, { title: string; tone: string }> = {
   already_exists: {
     title: "Likely Already Implemented",
@@ -65,6 +73,12 @@ export default function IdeaPage() {
   const [error, setError] = useState("");
   const [copied, setCopied] = useState(false);
   const [result, setResult] = useState<IdeaAssessResult | null>(null);
+  const [batchInput, setBatchInput] = useState("");
+  const [batchLoading, setBatchLoading] = useState(false);
+  const [batchError, setBatchError] = useState("");
+  const [batchResult, setBatchResult] = useState<IdeaAssessBatchResult | null>(null);
+  const [maxConcurrency, setMaxConcurrency] = useState(2);
+  const [timeoutSeconds, setTimeoutSeconds] = useState(30);
 
   const buildMarkdownReport = () => {
     if (!result) return "";
@@ -142,6 +156,45 @@ export default function IdeaPage() {
     }
   };
 
+  const parseBatchItems = () => {
+    return batchInput
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        const [ideaPart, docPart] = line.split("||", 2);
+        return {
+          idea: ideaPart.trim(),
+          product_doc: docPart?.trim() || undefined,
+        };
+      })
+      .filter((item) => item.idea.length > 0)
+      .slice(0, 20);
+  };
+
+  const runBatchAssessment = async () => {
+    const items = parseBatchItems();
+    if (items.length === 0) return;
+
+    setBatchLoading(true);
+    setBatchError("");
+    setBatchResult(null);
+
+    try {
+      const data = await assessIdeaBatch<IdeaAssessBatchResult>({
+        items,
+        limit,
+        max_concurrency: maxConcurrency,
+        per_item_timeout_seconds: timeoutSeconds,
+      });
+      setBatchResult(data);
+    } catch {
+      setBatchError("Failed to assess batch ideas. Please retry in a moment.");
+    } finally {
+      setBatchLoading(false);
+    }
+  };
+
   return (
     <main className="max-w-5xl mx-auto px-4 py-10">
       <h1 className="text-3xl font-bold mb-2">💡 Idea Check</h1>
@@ -192,6 +245,52 @@ export default function IdeaPage() {
             {loading ? "Analyzing..." : "Assess Idea"}
           </button>
         </div>
+
+        <div className="pt-6 border-t border-gray-200 dark:border-gray-800 space-y-3">
+          <label className="block text-sm font-medium mb-1">
+            Batch Ideas (one per line, optional "|| product doc")
+          </label>
+          <textarea
+            value={batchInput}
+            onChange={(e) => setBatchInput(e.target.value)}
+            placeholder={"Open-source API mocking tool || Need scenario replay\nPR review assistant for OSS maintainers || Need triage automation"}
+            className="w-full px-4 py-3 border-2 border-gray-200 rounded-xl focus:border-owl-500 focus:outline-none dark:bg-gray-900 dark:border-gray-700 min-h-[150px]"
+          />
+
+          <div className="flex flex-wrap items-center gap-3">
+            <label className="text-sm text-gray-600 dark:text-gray-400">Max concurrency:</label>
+            <select
+              value={maxConcurrency}
+              onChange={(e) => setMaxConcurrency(Number(e.target.value))}
+              className="px-3 py-1.5 border rounded-lg dark:bg-gray-900 dark:border-gray-700"
+            >
+              <option value={1}>1</option>
+              <option value={2}>2</option>
+              <option value={4}>4</option>
+              <option value={6}>6</option>
+            </select>
+
+            <label className="text-sm text-gray-600 dark:text-gray-400">Timeout (s):</label>
+            <select
+              value={timeoutSeconds}
+              onChange={(e) => setTimeoutSeconds(Number(e.target.value))}
+              className="px-3 py-1.5 border rounded-lg dark:bg-gray-900 dark:border-gray-700"
+            >
+              <option value={15}>15</option>
+              <option value={25}>25</option>
+              <option value={30}>30</option>
+              <option value={45}>45</option>
+            </select>
+
+            <button
+              onClick={runBatchAssessment}
+              disabled={parseBatchItems().length === 0 || batchLoading}
+              className="ml-auto px-6 py-2.5 bg-gray-900 text-white rounded-xl hover:bg-black disabled:opacity-50 transition dark:bg-gray-100 dark:text-black dark:hover:bg-white"
+            >
+              {batchLoading ? "Assessing Batch..." : "Assess Batch"}
+            </button>
+          </div>
+        </div>
       </div>
 
       {error && (
@@ -200,6 +299,48 @@ export default function IdeaPage() {
         </div>
       )}
 
+      {batchError && (
+        <div className="mt-6 p-3 rounded-lg bg-red-50 text-red-700 dark:bg-red-900/20 dark:text-red-300 text-sm">
+          {batchError}
+        </div>
+      )}
+
+      {batchResult && (
+        <section className="mt-8 p-6 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900 space-y-4">
+          <h2 className="text-xl font-semibold">Batch Assessment Summary</h2>
+          <div className="grid grid-cols-2 md:grid-cols-4 gap-3 text-sm">
+            <div className="p-3 rounded bg-gray-50 dark:bg-gray-800">
+              <div className="text-gray-500">Total</div>
+              <div className="font-semibold">{batchResult.total}</div>
+            </div>
+            <div className="p-3 rounded bg-red-50 dark:bg-red-900/20">
+              <div className="text-gray-500">Already Exists</div>
+              <div className="font-semibold">{batchResult.already_exists}</div>
+            </div>
+            <div className="p-3 rounded bg-amber-50 dark:bg-amber-900/20">
+              <div className="text-gray-500">Similar Exists</div>
+              <div className="font-semibold">{batchResult.similar_projects_exist}</div>
+            </div>
+            <div className="p-3 rounded bg-green-50 dark:bg-green-900/20">
+              <div className="text-gray-500">Likely Novel</div>
+              <div className="font-semibold">{batchResult.likely_novel}</div>
+            </div>
+          </div>
+
+          <div className="space-y-2">
+            {batchResult.results.map((item, idx) => (
+              <div key={`${idx}-${item.idea}`} className="p-3 rounded-lg bg-gray-50 dark:bg-gray-800">
+                <div className="font-medium text-sm">{item.idea}</div>
+                <div className={`text-xs mt-1 ${VERDICT_UI[item.verdict].tone}`}>
+                  {VERDICT_UI[item.verdict].title} · {Math.round(item.existing_project_probability * 100)}%
+                </div>
+                <div className="text-xs mt-1 text-gray-500">Action: {item.action_recommendation}</div>
+              </div>
+            ))}
+          </div>
+        </section>
+      )}
+
       {result && (
         <section className="mt-8 space-y-6">
           <div className="p-6 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900">
diff --git a/web/src/lib/api.ts b/web/src/lib/api.ts
index 5caef30..1e58508 100644
--- a/web/src/lib/api.ts
+++ b/web/src/lib/api.ts
@@ -34,6 +34,20 @@ export interface IdeaAssessPayload {
   limit?: number;
 }
 
+export interface IdeaAssessBatchPayload {
+  items: Array<{
+    idea: string;
+    product_doc?: string;
+  }>;
+  limit?: number;
+  max_concurrency?: number;
+  per_item_timeout_seconds?: number;
+}
+
 export async function assessIdea<T = any>(payload: IdeaAssessPayload): Promise<T> {
   return apiPost<T>("/idea/assess", payload);
 }
+
+export async function assessIdeaBatch<T = any>(payload: IdeaAssessBatchPayload): Promise<T> {
+  return apiPost<T>("/idea/assess/batch", payload);
+}

From 8df130155192a670741a1c150dbad14f7589ced8 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Sun, 5 Apr 2026 23:09:23 +0800
Subject: [PATCH 05/17] feat(idea): add batch assessment export endpoint

---
 README.md              | 11 +++++++++++
 README.zh-CN.md        | 11 +++++++++++
 src/api/routes/idea.py | 45 ++++++++++++++++++++++++++++++++++++++++++
 src/models/schemas.py  |  6 ++++++
 tests/test_api.py      | 42 +++++++++++++++++++++++++++++++++++++++
 5 files changed, 115 insertions(+)

diff --git a/README.md b/README.md
index aab8b80..608b9e9 100644
--- a/README.md
+++ b/README.md
@@ -208,6 +208,16 @@ curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch" \
   -H "Content-Type: application/json" \
   -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
 
+# Export batch assessment report as Markdown
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch/export?format=markdown" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
+
+# Export batch assessment report as JSON envelope
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch/export?format=json" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
+
 # Response includes:
 # - verdict + existing_project_probability
 # - action_recommendation (build|fork|integrate) + action_rationale
@@ -216,6 +226,7 @@ curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch" \
 # - export endpoint supports markdown/json report output
 # - batch endpoint returns per-idea results + verdict counts
 # - batch supports max_concurrency and per_item_timeout_seconds
+# - batch export endpoint supports markdown/json report output
 ```
 
 Full API documentation available at `http://127.0.0.1:8010/docs` (Swagger UI) or `http://127.0.0.1:8010/redoc` (ReDoc).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index e965b0c..fb41d12 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -161,6 +161,16 @@ curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/export?format=json" \
 curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch" \
   -H "Content-Type: application/json" \
   -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
+
+# 导出批量评估 Markdown 报告
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch/export?format=markdown" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
+
+# 导出批量评估 JSON 报告
+curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch/export?format=json" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"idea":"Open-source API mocking tool","product_doc":"Need scenario replay"},{"idea":"PR review assistant for OSS maintainers","product_doc":"Need triage automation"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}'
 ```
 
 响应包含：
@@ -171,6 +181,7 @@ curl -X POST "http://127.0.0.1:8010/api/v1/idea/assess/batch" \
 - 导出接口支持 markdown/json 两种报告格式
 - 批量接口返回逐条结果和 verdict 统计
 - 批量接口支持 max_concurrency 与 per_item_timeout_seconds
+- 批量导出接口支持 markdown/json 两种报告格式
 
 ## 自托管
 
diff --git a/src/api/routes/idea.py b/src/api/routes/idea.py
index b063ab3..faa9423 100644
--- a/src/api/routes/idea.py
+++ b/src/api/routes/idea.py
@@ -18,6 +18,7 @@
 from src.core.query_engine.engine import QueryEngine
 from src.models.schemas import (
     DecisionSignals,
+    IdeaAssessBatchExportResponse,
     DifferentiationOpportunity,
     IdeaAssessBatchRequest,
     IdeaAssessBatchResponse,
@@ -233,6 +234,35 @@ def _render_markdown_report(assessment: IdeaAssessResponse) -> str:
     return "\n".join(lines)
 
 
+def _render_batch_markdown_report(batch: IdeaAssessBatchResponse) -> str:
+    lines: list[str] = [
+        "# Batch Idea Assessment Report",
+        "",
+        "## Summary",
+        f"- Total: {batch.total}",
+        f"- already_exists: {batch.already_exists}",
+        f"- similar_projects_exist: {batch.similar_projects_exist}",
+        f"- likely_novel: {batch.likely_novel}",
+        "",
+        "## Results",
+    ]
+
+    for idx, item in enumerate(batch.results, start=1):
+        lines.extend(
+            [
+                f"### {idx}. {item.idea}",
+                f"- Verdict: {item.verdict}",
+                f"- Confidence: {item.confidence}",
+                f"- Existing project probability: {item.existing_project_probability}",
+                f"- Recommended action: {item.action_recommendation}",
+                f"- Summary: {item.summary}",
+                "",
+            ]
+        )
+
+    return "\n".join(lines)
+
+
 async def _assess_core(request: IdeaAssessRequest) -> IdeaAssessResponse:
     """Core idea assessment logic shared by standard and export endpoints."""
     combined_query = request.idea.strip()
@@ -482,3 +512,18 @@ async def _assess_one(item) -> IdeaAssessResponse:
         likely_novel=counters["likely_novel"],
         results=results,
     )
+
+
+@router.post("/idea/assess/batch/export", response_model=IdeaAssessBatchExportResponse)
+async def export_batch_assessment_report(
+    request: IdeaAssessBatchRequest,
+    format: str = Query("markdown", pattern="^(markdown|json)$"),
+) -> IdeaAssessBatchExportResponse | PlainTextResponse:
+    """Export batch idea assessments as Markdown or JSON report."""
+    batch = await assess_idea_batch(request)
+
+    if format == "markdown":
+        markdown = _render_batch_markdown_report(batch)
+        return PlainTextResponse(content=markdown, media_type="text/markdown")
+
+    return IdeaAssessBatchExportResponse(report_type="json", assessment_batch=batch)
diff --git a/src/models/schemas.py b/src/models/schemas.py
index ad24967..3dc43bf 100644
--- a/src/models/schemas.py
+++ b/src/models/schemas.py
@@ -158,6 +158,12 @@ class IdeaAssessBatchResponse(BaseModel):
     generated_at: datetime = Field(default_factory=datetime.utcnow)
 
 
+class IdeaAssessBatchExportResponse(BaseModel):
+    report_type: str  # markdown|json
+    assessment_batch: IdeaAssessBatchResponse
+    generated_at: datetime = Field(default_factory=datetime.utcnow)
+
+
 # ── Evaluation ───────────────────────────────────────────────────────────────
 
 
diff --git a/tests/test_api.py b/tests/test_api.py
index 0e0cec6..35a3c52 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -171,3 +171,45 @@ async def test_assess_idea_batch(client: AsyncClient):
         + data["likely_novel"]
     )
     assert verdict_sum == 2
+
+
+@pytest.mark.asyncio
+async def test_assess_idea_batch_export_markdown(client: AsyncClient):
+    resp = await client.post(
+        "/api/v1/idea/assess/batch/export?format=markdown",
+        json={
+            "items": [
+                {"idea": "Open-source API mocking tool", "product_doc": "Need scenario replay"},
+                {"idea": "PR review assistant for OSS maintainers", "product_doc": "Need triage automation"},
+            ],
+            "limit": 6,
+            "max_concurrency": 2,
+            "per_item_timeout_seconds": 30,
+        },
+    )
+    assert resp.status_code == 200
+    assert resp.headers.get("content-type", "").startswith("text/markdown")
+    body = resp.text
+    assert "# Batch Idea Assessment Report" in body
+    assert "## Summary" in body
+
+
+@pytest.mark.asyncio
+async def test_assess_idea_batch_export_json(client: AsyncClient):
+    resp = await client.post(
+        "/api/v1/idea/assess/batch/export?format=json",
+        json={
+            "items": [
+                {"idea": "Open-source API mocking tool", "product_doc": "Need scenario replay"},
+                {"idea": "PR review assistant for OSS maintainers", "product_doc": "Need triage automation"},
+            ],
+            "limit": 6,
+            "max_concurrency": 2,
+            "per_item_timeout_seconds": 30,
+        },
+    )
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["report_type"] == "json"
+    assert "assessment_batch" in data
+    assert data["assessment_batch"]["total"] == 2

From 7fd5456d23360ec1604c845aa15800a7dddb363c Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 00:11:54 +0800
Subject: [PATCH 06/17] feat(web): add batch idea report export actions

---
 web/src/app/idea/page.tsx | 64 ++++++++++++++++++++++++++++++++++++++-
 web/src/lib/api.ts        | 18 +++++++++++
 2 files changed, 81 insertions(+), 1 deletion(-)

diff --git a/web/src/app/idea/page.tsx b/web/src/app/idea/page.tsx
index 4813de8..1a87229 100644
--- a/web/src/app/idea/page.tsx
+++ b/web/src/app/idea/page.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useState } from "react";
-import { assessIdea, assessIdeaBatch } from "@/lib/api";
+import { assessIdea, assessIdeaBatch, assessIdeaBatchExport } from "@/lib/api";
 
 type Verdict = "already_exists" | "similar_projects_exist" | "likely_novel";
 
@@ -77,6 +77,7 @@ export default function IdeaPage() {
   const [batchLoading, setBatchLoading] = useState(false);
   const [batchError, setBatchError] = useState("");
   const [batchResult, setBatchResult] = useState<IdeaAssessBatchResult | null>(null);
+  const [batchExportingFormat, setBatchExportingFormat] = useState<"markdown" | "json" | null>(null);
   const [maxConcurrency, setMaxConcurrency] = useState(2);
   const [timeoutSeconds, setTimeoutSeconds] = useState(30);
 
@@ -195,6 +196,53 @@ export default function IdeaPage() {
     }
   };
 
+  const downloadBatchReport = async (format: "markdown" | "json") => {
+    const items = parseBatchItems();
+    if (items.length === 0) return;
+
+    setBatchExportingFormat(format);
+    setBatchError("");
+
+    try {
+      const payload = {
+        items,
+        limit,
+        max_concurrency: maxConcurrency,
+        per_item_timeout_seconds: timeoutSeconds,
+      };
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+
+      if (format === "markdown") {
+        const report = (await assessIdeaBatchExport(payload, "markdown")) as string;
+        const blob = new Blob([report], { type: "text/markdown;charset=utf-8" });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = `owlscope-idea-batch-report-${stamp}.md`;
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+        URL.revokeObjectURL(url);
+        return;
+      }
+
+      const jsonReport = await assessIdeaBatchExport(payload, "json");
+      const blob = new Blob([JSON.stringify(jsonReport, null, 2)], { type: "application/json;charset=utf-8" });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = `owlscope-idea-batch-report-${stamp}.json`;
+      document.body.appendChild(a);
+      a.click();
+      a.remove();
+      URL.revokeObjectURL(url);
+    } catch {
+      setBatchError("Failed to export batch report. Please retry in a moment.");
+    } finally {
+      setBatchExportingFormat(null);
+    }
+  };
+
   return (
     <main className="max-w-5xl mx-auto px-4 py-10">
       <h1 className="text-3xl font-bold mb-2">💡 Idea Check</h1>
@@ -289,6 +337,20 @@ export default function IdeaPage() {
             >
               {batchLoading ? "Assessing Batch..." : "Assess Batch"}
             </button>
+            <button
+              onClick={() => downloadBatchReport("markdown")}
+              disabled={parseBatchItems().length === 0 || !!batchExportingFormat}
+              className="px-4 py-2.5 border rounded-xl hover:bg-gray-50 disabled:opacity-50 transition dark:border-gray-700 dark:hover:bg-gray-800"
+            >
+              {batchExportingFormat === "markdown" ? "Exporting MD..." : "Export Markdown"}
+            </button>
+            <button
+              onClick={() => downloadBatchReport("json")}
+              disabled={parseBatchItems().length === 0 || !!batchExportingFormat}
+              className="px-4 py-2.5 border rounded-xl hover:bg-gray-50 disabled:opacity-50 transition dark:border-gray-700 dark:hover:bg-gray-800"
+            >
+              {batchExportingFormat === "json" ? "Exporting JSON..." : "Export JSON"}
+            </button>
           </div>
         </div>
       </div>
diff --git a/web/src/lib/api.ts b/web/src/lib/api.ts
index 1e58508..a2a84ae 100644
--- a/web/src/lib/api.ts
+++ b/web/src/lib/api.ts
@@ -51,3 +51,21 @@ export async function assessIdea<T = any>(payload: IdeaAssessPayload): Promise<T
 export async function assessIdeaBatch<T = any>(payload: IdeaAssessBatchPayload): Promise<T> {
   return apiPost<T>("/idea/assess/batch", payload);
 }
+
+export async function assessIdeaBatchExport<T = any>(
+  payload: IdeaAssessBatchPayload,
+  format: "markdown" | "json" = "markdown"
+): Promise<string | T> {
+  const res = await fetch(`${API_BASE}/idea/assess/batch/export?format=${format}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!res.ok) {
+    throw new Error(`API error: ${res.status}`);
+  }
+  if (format === "markdown") {
+    return res.text();
+  }
+  return res.json();
+}

From 1babcb0a1fde33fd80ebc5e1fc2ac8bc104627d0 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 00:19:42 +0800
Subject: [PATCH 07/17] feat(web): show recent batch export history

---
 web/src/app/idea/page.tsx | 47 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/web/src/app/idea/page.tsx b/web/src/app/idea/page.tsx
index 1a87229..8f14428 100644
--- a/web/src/app/idea/page.tsx
+++ b/web/src/app/idea/page.tsx
@@ -50,6 +50,13 @@ interface IdeaAssessBatchResult {
   results: IdeaAssessResult[];
 }
 
+interface BatchExportHistoryEntry {
+  format: "markdown" | "json";
+  itemCount: number;
+  fileName: string;
+  exportedAt: string;
+}
+
 const VERDICT_UI: Record<Verdict, { title: string; tone: string }> = {
   already_exists: {
     title: "Likely Already Implemented",
@@ -78,6 +85,7 @@ export default function IdeaPage() {
   const [batchError, setBatchError] = useState("");
   const [batchResult, setBatchResult] = useState<IdeaAssessBatchResult | null>(null);
   const [batchExportingFormat, setBatchExportingFormat] = useState<"markdown" | "json" | null>(null);
+  const [batchExportHistory, setBatchExportHistory] = useState<BatchExportHistoryEntry[]>([]);
   const [maxConcurrency, setMaxConcurrency] = useState(2);
   const [timeoutSeconds, setTimeoutSeconds] = useState(30);
 
@@ -211,6 +219,14 @@ export default function IdeaPage() {
         per_item_timeout_seconds: timeoutSeconds,
       };
       const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+      const exportedAt = new Date().toISOString();
+
+      const pushExportHistory = (fileName: string) => {
+        setBatchExportHistory((prev) => [
+          { format, itemCount: items.length, fileName, exportedAt },
+          ...prev,
+        ].slice(0, 5));
+      };
 
       if (format === "markdown") {
         const report = (await assessIdeaBatchExport(payload, "markdown")) as string;
@@ -218,11 +234,13 @@ export default function IdeaPage() {
         const url = URL.createObjectURL(blob);
         const a = document.createElement("a");
         a.href = url;
-        a.download = `owlscope-idea-batch-report-${stamp}.md`;
+        const fileName = `owlscope-idea-batch-report-${stamp}.md`;
+        a.download = fileName;
         document.body.appendChild(a);
         a.click();
         a.remove();
         URL.revokeObjectURL(url);
+        pushExportHistory(fileName);
         return;
       }
 
@@ -231,11 +249,13 @@ export default function IdeaPage() {
       const url = URL.createObjectURL(blob);
       const a = document.createElement("a");
       a.href = url;
-      a.download = `owlscope-idea-batch-report-${stamp}.json`;
+      const fileName = `owlscope-idea-batch-report-${stamp}.json`;
+      a.download = fileName;
       document.body.appendChild(a);
       a.click();
       a.remove();
       URL.revokeObjectURL(url);
+      pushExportHistory(fileName);
     } catch {
       setBatchError("Failed to export batch report. Please retry in a moment.");
     } finally {
@@ -367,6 +387,29 @@ export default function IdeaPage() {
         </div>
       )}
 
+      {batchExportHistory.length > 0 && (
+        <section className="mt-6 p-4 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900">
+          <div className="flex items-center justify-between mb-3">
+            <h2 className="text-sm font-semibold">Recent Batch Exports</h2>
+            <span className="text-xs text-gray-500">Last {batchExportHistory.length}</span>
+          </div>
+          <div className="space-y-2">
+            {batchExportHistory.map((item, idx) => (
+              <div key={`${item.fileName}-${idx}`} className="p-2.5 rounded-lg bg-gray-50 dark:bg-gray-800 text-xs">
+                <div className="flex flex-wrap items-center gap-2">
+                  <span className="font-medium text-gray-700 dark:text-gray-200">{item.fileName}</span>
+                  <span className="px-1.5 py-0.5 rounded bg-owl-100 text-owl-700 dark:bg-owl-900 dark:text-owl-200">
+                    {item.format.toUpperCase()}
+                  </span>
+                  <span className="text-gray-500">{item.itemCount} items</span>
+                  <span className="text-gray-500">{new Date(item.exportedAt).toLocaleString()}</span>
+                </div>
+              </div>
+            ))}
+          </div>
+        </section>
+      )}
+
       {batchResult && (
         <section className="mt-8 p-6 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900 space-y-4">
           <h2 className="text-xl font-semibold">Batch Assessment Summary</h2>

From 9d8422386a98e5201319261c152335036d8cd746 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 00:39:14 +0800
Subject: [PATCH 08/17] feat(web): persist and clear batch export history

---
 web/src/app/idea/page.tsx | 54 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 52 insertions(+), 2 deletions(-)

diff --git a/web/src/app/idea/page.tsx b/web/src/app/idea/page.tsx
index 8f14428..fdd4af8 100644
--- a/web/src/app/idea/page.tsx
+++ b/web/src/app/idea/page.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { assessIdea, assessIdeaBatch, assessIdeaBatchExport } from "@/lib/api";
 
 type Verdict = "already_exists" | "similar_projects_exist" | "likely_novel";
@@ -57,6 +57,8 @@ interface BatchExportHistoryEntry {
   exportedAt: string;
 }
 
+const BATCH_EXPORT_HISTORY_KEY = "owlscope.idea.batch_export_history";
+
 const VERDICT_UI: Record<Verdict, { title: string; tone: string }> = {
   already_exists: {
     title: "Likely Already Implemented",
@@ -86,9 +88,45 @@ export default function IdeaPage() {
   const [batchResult, setBatchResult] = useState<IdeaAssessBatchResult | null>(null);
   const [batchExportingFormat, setBatchExportingFormat] = useState<"markdown" | "json" | null>(null);
   const [batchExportHistory, setBatchExportHistory] = useState<BatchExportHistoryEntry[]>([]);
+  const [historyLoaded, setHistoryLoaded] = useState(false);
   const [maxConcurrency, setMaxConcurrency] = useState(2);
   const [timeoutSeconds, setTimeoutSeconds] = useState(30);
 
+  useEffect(() => {
+    try {
+      const raw = window.localStorage.getItem(BATCH_EXPORT_HISTORY_KEY);
+      if (!raw) {
+        setHistoryLoaded(true);
+        return;
+      }
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) {
+        setHistoryLoaded(true);
+        return;
+      }
+      const normalized: BatchExportHistoryEntry[] = parsed
+        .filter((item) => item && typeof item === "object")
+        .map((item) => ({
+          format: (item.format === "json" ? "json" : "markdown") as "markdown" | "json",
+          itemCount: Number(item.itemCount) || 0,
+          fileName: String(item.fileName || ""),
+          exportedAt: String(item.exportedAt || ""),
+        }))
+        .filter((item) => item.fileName.length > 0)
+        .slice(0, 5);
+      setBatchExportHistory(normalized);
+    } catch {
+      setBatchExportHistory([]);
+    } finally {
+      setHistoryLoaded(true);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!historyLoaded) return;
+    window.localStorage.setItem(BATCH_EXPORT_HISTORY_KEY, JSON.stringify(batchExportHistory));
+  }, [batchExportHistory, historyLoaded]);
+
   const buildMarkdownReport = () => {
     if (!result) return "";
     const lines: string[] = [];
@@ -263,6 +301,10 @@ export default function IdeaPage() {
     }
   };
 
+  const clearBatchExportHistory = () => {
+    setBatchExportHistory([]);
+  };
+
   return (
     <main className="max-w-5xl mx-auto px-4 py-10">
       <h1 className="text-3xl font-bold mb-2">💡 Idea Check</h1>
@@ -391,7 +433,15 @@ export default function IdeaPage() {
         <section className="mt-6 p-4 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-900">
           <div className="flex items-center justify-between mb-3">
             <h2 className="text-sm font-semibold">Recent Batch Exports</h2>
-            <span className="text-xs text-gray-500">Last {batchExportHistory.length}</span>
+            <div className="flex items-center gap-3">
+              <span className="text-xs text-gray-500">Last {batchExportHistory.length}</span>
+              <button
+                onClick={clearBatchExportHistory}
+                className="text-xs px-2 py-1 rounded border border-gray-300 dark:border-gray-700 hover:bg-gray-50 dark:hover:bg-gray-800"
+              >
+                Clear History
+              </button>
+            </div>
           </div>
           <div className="space-y-2">
             {batchExportHistory.map((item, idx) => (

From 5af8ffa6b32913635e82b6d35baa3c37ac45c6db Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 00:50:48 +0800
Subject: [PATCH 09/17] feat(web): add one-click re-export from history

---
 web/src/app/idea/page.tsx | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/web/src/app/idea/page.tsx b/web/src/app/idea/page.tsx
index fdd4af8..e223a68 100644
--- a/web/src/app/idea/page.tsx
+++ b/web/src/app/idea/page.tsx
@@ -443,6 +443,9 @@ export default function IdeaPage() {
               </button>
             </div>
           </div>
+          <p className="text-xs text-gray-500 mb-2">
+            Re-export uses your current batch ideas and settings.
+          </p>
           <div className="space-y-2">
             {batchExportHistory.map((item, idx) => (
               <div key={`${item.fileName}-${idx}`} className="p-2.5 rounded-lg bg-gray-50 dark:bg-gray-800 text-xs">
@@ -453,6 +456,13 @@ export default function IdeaPage() {
                   </span>
                   <span className="text-gray-500">{item.itemCount} items</span>
                   <span className="text-gray-500">{new Date(item.exportedAt).toLocaleString()}</span>
+                  <button
+                    onClick={() => downloadBatchReport(item.format)}
+                    disabled={parseBatchItems().length === 0 || !!batchExportingFormat}
+                    className="ml-auto text-xs px-2 py-1 rounded border border-gray-300 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-700 disabled:opacity-50"
+                  >
+                    {batchExportingFormat === item.format ? "Re-exporting..." : "Re-export"}
+                  </button>
                 </div>
               </div>
             ))}

From 7df9769d7e791fab8fbe433dece0f389d5e240e0 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 01:12:27 +0800
Subject: [PATCH 10/17] feat(web): support snapshot re-export from history

---
 web/src/app/idea/page.tsx | 75 +++++++++++++++++++++++++++++----------
 1 file changed, 57 insertions(+), 18 deletions(-)

diff --git a/web/src/app/idea/page.tsx b/web/src/app/idea/page.tsx
index e223a68..73484f5 100644
--- a/web/src/app/idea/page.tsx
+++ b/web/src/app/idea/page.tsx
@@ -50,11 +50,22 @@ interface IdeaAssessBatchResult {
   results: IdeaAssessResult[];
 }
 
+interface BatchPayloadSnapshot {
+  items: Array<{
+    idea: string;
+    product_doc?: string;
+  }>;
+  limit: number;
+  max_concurrency: number;
+  per_item_timeout_seconds: number;
+}
+
 interface BatchExportHistoryEntry {
   format: "markdown" | "json";
   itemCount: number;
   fileName: string;
   exportedAt: string;
+  payload?: BatchPayloadSnapshot;
 }
 
 const BATCH_EXPORT_HISTORY_KEY = "owlscope.idea.batch_export_history";
@@ -106,12 +117,32 @@ export default function IdeaPage() {
       }
       const normalized: BatchExportHistoryEntry[] = parsed
         .filter((item) => item && typeof item === "object")
-        .map((item) => ({
-          format: (item.format === "json" ? "json" : "markdown") as "markdown" | "json",
-          itemCount: Number(item.itemCount) || 0,
-          fileName: String(item.fileName || ""),
-          exportedAt: String(item.exportedAt || ""),
-        }))
+        .map((item) => {
+          const rawPayload = item.payload;
+          const payload = rawPayload && Array.isArray(rawPayload.items)
+            ? {
+                items: rawPayload.items
+                  .filter((entry: unknown) => !!entry && typeof entry === "object")
+                  .map((entry: any) => ({
+                    idea: String(entry.idea || "").trim(),
+                    product_doc: entry.product_doc ? String(entry.product_doc) : undefined,
+                  }))
+                  .filter((entry: { idea: string }) => entry.idea.length > 0)
+                  .slice(0, 20),
+                limit: Number(rawPayload.limit) || 8,
+                max_concurrency: Number(rawPayload.max_concurrency) || 2,
+                per_item_timeout_seconds: Number(rawPayload.per_item_timeout_seconds) || 30,
+              }
+            : undefined;
+
+          return {
+            format: (item.format === "json" ? "json" : "markdown") as "markdown" | "json",
+            itemCount: Number(item.itemCount) || 0,
+            fileName: String(item.fileName || ""),
+            exportedAt: String(item.exportedAt || ""),
+            payload: payload && payload.items.length > 0 ? payload : undefined,
+          };
+        })
         .filter((item) => item.fileName.length > 0)
         .slice(0, 5);
       setBatchExportHistory(normalized);
@@ -242,26 +273,34 @@ export default function IdeaPage() {
     }
   };
 
-  const downloadBatchReport = async (format: "markdown" | "json") => {
+  const buildBatchPayloadFromCurrentInput = (): BatchPayloadSnapshot | null => {
     const items = parseBatchItems();
-    if (items.length === 0) return;
+    if (items.length === 0) return null;
+    return {
+      items,
+      limit,
+      max_concurrency: maxConcurrency,
+      per_item_timeout_seconds: timeoutSeconds,
+    };
+  };
+
+  const downloadBatchReport = async (
+    format: "markdown" | "json",
+    payloadOverride?: BatchPayloadSnapshot
+  ) => {
+    const payload = payloadOverride || buildBatchPayloadFromCurrentInput();
+    if (!payload || payload.items.length === 0) return;
 
     setBatchExportingFormat(format);
     setBatchError("");
 
     try {
-      const payload = {
-        items,
-        limit,
-        max_concurrency: maxConcurrency,
-        per_item_timeout_seconds: timeoutSeconds,
-      };
       const stamp = new Date().toISOString().replace(/[:.]/g, "-");
       const exportedAt = new Date().toISOString();
 
       const pushExportHistory = (fileName: string) => {
         setBatchExportHistory((prev) => [
-          { format, itemCount: items.length, fileName, exportedAt },
+          { format, itemCount: payload.items.length, fileName, exportedAt, payload },
           ...prev,
         ].slice(0, 5));
       };
@@ -444,7 +483,7 @@ export default function IdeaPage() {
             </div>
           </div>
           <p className="text-xs text-gray-500 mb-2">
-            Re-export uses your current batch ideas and settings.
+            Re-export replays the saved snapshot payload when available.
           </p>
           <div className="space-y-2">
             {batchExportHistory.map((item, idx) => (
@@ -457,8 +496,8 @@ export default function IdeaPage() {
                   <span className="text-gray-500">{item.itemCount} items</span>
                   <span className="text-gray-500">{new Date(item.exportedAt).toLocaleString()}</span>
                   <button
-                    onClick={() => downloadBatchReport(item.format)}
-                    disabled={parseBatchItems().length === 0 || !!batchExportingFormat}
+                    onClick={() => downloadBatchReport(item.format, item.payload)}
+                    disabled={(!item.payload && parseBatchItems().length === 0) || !!batchExportingFormat}
                     className="ml-auto text-xs px-2 py-1 rounded border border-gray-300 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-700 disabled:opacity-50"
                   >
                     {batchExportingFormat === item.format ? "Re-exporting..." : "Re-export"}

From 32af4e6977146cf5475b51c0d645be0209f2ae80 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 01:42:57 +0800
Subject: [PATCH 11/17] chore(release): automate preflight, observability, and
 deployment runbooks

---
 .env.example                               | 11 ++-
 .github/workflows/release-preflight.yml    | 85 ++++++++++++++++++++++
 README.md                                  | 21 ++++++
 README.zh-CN.md                            | 21 ++++++
 docs/deployment.md                         | 41 +++++++++++
 docs/migrations.md                         | 34 +++++++++
 docs/release-checklist.md                  |  8 ++
 docs/releases/TEMPLATE.md                  | 38 ++++++++++
 docs/self-hosting.md                       | 19 +++++
 docs/smoke-test.md                         | 27 +++++++
 scripts/check_rate_limit.sh                | 29 ++++++++
 scripts/release_check.sh                   | 24 +++++-
 scripts/run_integration_compare.sh         | 18 +++++
 scripts/validate_env.py                    | 44 +++++++++++
 src/api/main.py                            |  3 +-
 src/api/middleware/access_log.py           |  3 +
 src/api/routes/admin.py                    | 18 +++++
 src/api/telemetry.py                       | 44 +++++++++++
 tests/integration/test_compare_blackbox.py | 20 ++++-
 tests/test_api.py                          | 10 +++
 20 files changed, 508 insertions(+), 10 deletions(-)
 create mode 100644 .github/workflows/release-preflight.yml
 create mode 100644 docs/deployment.md
 create mode 100644 docs/migrations.md
 create mode 100644 docs/releases/TEMPLATE.md
 create mode 100644 docs/smoke-test.md
 create mode 100755 scripts/check_rate_limit.sh
 create mode 100755 scripts/run_integration_compare.sh
 create mode 100644 scripts/validate_env.py
 create mode 100644 src/api/routes/admin.py
 create mode 100644 src/api/telemetry.py

diff --git a/.env.example b/.env.example
index d662880..afb2319 100644
--- a/.env.example
+++ b/.env.example
@@ -6,8 +6,8 @@
 # -----------------------------------------------------------------------------
 # Server
 # -----------------------------------------------------------------------------
-OWLSCOPE_HOST=0.0.0.0
-OWLSCOPE_PORT=8000
+OWLSCOPE_HOST=127.0.0.1
+OWLSCOPE_PORT=8010
 OWLSCOPE_ENV=development
 OWLSCOPE_DEBUG=true
 OWLSCOPE_SECRET_KEY=change-me-to-a-random-secret-key
@@ -70,3 +70,10 @@ PYPI_API_URL=https://pypi.org/pypi
 # -----------------------------------------------------------------------------
 RATE_LIMIT_FREE=100
 RATE_LIMIT_PRO=10000
+
+# ----------------------------------------------------------------------------
+# Release Checks
+# ----------------------------------------------------------------------------
+# Set to 1 when running scripts/release_check.sh and you want integration test
+# included in the same pass.
+OWLSCOPE_RELEASE_CHECK_INTEGRATION=0
diff --git a/.github/workflows/release-preflight.yml b/.github/workflows/release-preflight.yml
new file mode 100644
index 0000000..c00c0d2
--- /dev/null
+++ b/.github/workflows/release-preflight.yml
@@ -0,0 +1,85 @@
+name: Release Preflight
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [dev]
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: owlscope
+          POSTGRES_PASSWORD: owlscope
+          POSTGRES_DB: owlscope
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U owlscope -d owlscope"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DATABASE_URL: postgresql+asyncpg://owlscope:owlscope@localhost:5432/owlscope
+      REDIS_URL: redis://localhost:6379/0
+      DEBUG: "false"
+      OWLSCOPE_RELEASE_CHECK_INTEGRATION: "1"
+      OWLSCOPE_RUN_INTEGRATION: "1"
+      OWLSCOPE_API_HOST: 127.0.0.1
+      OWLSCOPE_API_PORT: 8010
+      SECRET_KEY: ci-release-preflight-secret
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install backend dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Install web dependencies
+        run: npm ci
+        working-directory: web
+
+      - name: Prepare schema
+        run: |
+          python - <<'PY'
+          import asyncio
+          from src.models.database import Base
+          from src.models.db import engine
+
+          async def main() -> None:
+              async with engine.begin() as conn:
+                  await conn.run_sync(Base.metadata.create_all)
+              await engine.dispose()
+
+          asyncio.run(main())
+          print("schema-ready")
+          PY
+
+      - name: Run release preflight script
+        run: bash scripts/release_check.sh
diff --git a/README.md b/README.md
index 608b9e9..ba3d237 100644
--- a/README.md
+++ b/README.md
@@ -170,6 +170,27 @@ Notes:
 - The integration suite is excluded from default test runs.
 - CI always runs this test in a dedicated job with PostgreSQL + Redis services.
 
+## Release Preflight
+
+Use these commands before deployment:
+
+```bash
+# Validate production environment vars
+python scripts/validate_env.py --mode prod
+
+# One-command release validation (tests + build + smoke)
+bash scripts/release_check.sh
+
+# Include black-box integration test in the same run
+OWLSCOPE_RELEASE_CHECK_INTEGRATION=1 bash scripts/release_check.sh
+```
+
+Production-readiness docs:
+- Deployment runbook: `docs/deployment.md`
+- Migration/rollback: `docs/migrations.md`
+- Smoke checklist: `docs/smoke-test.md`
+- Release checklist: `docs/release-checklist.md`
+
 ## API Reference
 
 ### REST API
diff --git a/README.zh-CN.md b/README.zh-CN.md
index fb41d12..13d69cf 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -134,6 +134,27 @@ pytest -q -m integration tests/integration/test_compare_blackbox.py
 - 默认测试不会执行 integration 套件。
 - CI 会在独立 Job 中（PostgreSQL + Redis）强制执行该测试。
 
+## 发布前预检
+
+部署前建议执行：
+
+```bash
+# 校验生产环境变量
+python scripts/validate_env.py --mode prod
+
+# 一键发布前校验（测试 + 构建 + 冒烟）
+bash scripts/release_check.sh
+
+# 在同一流程中包含 integration 黑盒测试
+OWLSCOPE_RELEASE_CHECK_INTEGRATION=1 bash scripts/release_check.sh
+```
+
+上线文档：
+- 部署 Runbook：`docs/deployment.md`
+- 迁移/回滚：`docs/migrations.md`
+- 冒烟检查：`docs/smoke-test.md`
+- 发布清单：`docs/release-checklist.md`
+
 ## API 参考
 
 ```bash
diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000..64b9c88
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,41 @@
+# Deployment Runbook
+
+This runbook covers a safe baseline deployment for Owlscope.
+
+## 1. Preflight
+
+- Validate env vars:
+  - `python scripts/validate_env.py --mode prod`
+- Run release checks:
+  - `bash scripts/release_check.sh`
+- Run integration compare test:
+  - `bash scripts/run_integration_compare.sh`
+
+## 2. Build and Launch
+
+- Build web:
+  - `cd web && npm ci && npm run build`
+- Start services (example with Docker Compose):
+  - `docker compose up -d`
+
+## 3. Post-Deploy Verification
+
+- Health:
+  - `curl http://127.0.0.1:8010/health`
+- Admin monitor:
+  - `curl http://127.0.0.1:8010/api/v1/admin/monitor`
+- Rate-limit headers:
+  - `bash scripts/check_rate_limit.sh`
+- Core smoke APIs:
+  - `/api/v1/search`
+  - `/api/v1/evaluate/{id}`
+  - `/api/v1/compare`
+  - `/api/v1/idea/assess`
+
+## 4. Rollback
+
+- Roll app image/version back to the previous known-good release.
+- Run DB rollback only when schema migration requires it.
+- Re-run smoke checks after rollback.
+
+See also: `docs/migrations.md` and `docs/smoke-test.md`.
diff --git a/docs/migrations.md b/docs/migrations.md
new file mode 100644
index 0000000..06a27b6
--- /dev/null
+++ b/docs/migrations.md
@@ -0,0 +1,34 @@
+# Database Migration and Rollback Guide
+
+Use Alembic for schema changes in production.
+
+## Forward Migration
+
+```bash
+alembic upgrade head
+```
+
+## Rollback One Version
+
+```bash
+alembic downgrade -1
+```
+
+## Rollback to Specific Revision
+
+```bash
+alembic downgrade <revision_id>
+```
+
+## Safe Procedure
+
+1. Backup database before migration.
+2. Run migration in staging first.
+3. Deploy app with matching code and schema.
+4. If rollback is needed, roll app first when compatible, then rollback DB.
+5. Re-run smoke tests after rollback.
+
+## Verification
+
+- `alembic current`
+- `alembic history --verbose`
diff --git a/docs/release-checklist.md b/docs/release-checklist.md
index ab65cbc..9793669 100644
--- a/docs/release-checklist.md
+++ b/docs/release-checklist.md
@@ -5,9 +5,13 @@ Use this checklist before publishing a new release.
 ## Code and Tests
 
 - Run backend tests: `pytest -q`
+- Run integration compare test: `bash scripts/run_integration_compare.sh`
 - Build frontend: `cd web && npm run build`
 - Run one-command release validation: `bash scripts/release_check.sh`
+- Run full preflight in CI: GitHub Actions `Release Preflight`
 - Verify API health locally: `/health`
+- Verify monitor endpoint: `/api/v1/admin/monitor`
+- Verify rate-limit headers: `bash scripts/check_rate_limit.sh`
 - Smoke test critical endpoints:
   - `/api/v1/search`
   - `/api/v1/evaluate/{id}`
@@ -20,11 +24,15 @@ Use this checklist before publishing a new release.
 - Update `README.zh-CN.md` for major user-facing changes
 - Update `docs/ROADMAP.md` if priorities changed
 - Confirm `docs/self-hosting.md` still matches actual setup
+- Confirm deployment runbook: `docs/deployment.md`
+- Confirm smoke checklist: `docs/smoke-test.md`
+- Confirm migration/rollback guide: `docs/migrations.md`
 
 ## Versioning
 
 - Bump version in `pyproject.toml`
 - Prepare release notes (summary, changes, risks)
+- Include rollback notes and verification evidence
 - Tag release: `vX.Y.Z`
 
 ## GitHub Release
diff --git a/docs/releases/TEMPLATE.md b/docs/releases/TEMPLATE.md
new file mode 100644
index 0000000..189beb8
--- /dev/null
+++ b/docs/releases/TEMPLATE.md
@@ -0,0 +1,38 @@
+# Release Notes Template
+
+## Summary
+
+- What changed in this release.
+- Why this release matters.
+
+## Scope
+
+- Backend:
+- Web:
+- Data / Migrations:
+- Docs:
+
+## Verification Evidence
+
+- Backend tests:
+- Integration compare test:
+- Web build:
+- Release preflight:
+- Smoke test:
+
+## Risks
+
+- Known risks:
+- Mitigations:
+
+## Rollback Plan
+
+1. Roll application to previous release artifact.
+2. If schema rollback is required, run Alembic downgrade.
+3. Re-run smoke tests and monitor endpoint checks.
+
+## Operator Notes
+
+- Required environment updates:
+- Config flags changed:
+- Post-release watch items:
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index c3e70a5..27fb2f7 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -34,6 +34,12 @@ For LLM-backed features, set at least one provider key, for example:
 
 Owlscope has deterministic fallbacks for some retrieval flows when model services are unavailable.
 
+Validate environment before release/deploy:
+
+```bash
+python scripts/validate_env.py --mode prod
+```
+
 ## Local Dev Without Docker
 
 ### Backend
@@ -60,6 +66,16 @@ curl http://127.0.0.1:8010/health
 curl http://127.0.0.1:8010/api/v1/admin/monitor
 ```
 
+## Release Preflight
+
+```bash
+# Includes tests, optional integration, web build, and smoke checks.
+bash scripts/release_check.sh
+
+# Enable integration compare in the same run
+OWLSCOPE_RELEASE_CHECK_INTEGRATION=1 bash scripts/release_check.sh
+```
+
 ## Data Notes
 
 - In development, Qdrant may run in in-memory fallback mode.
@@ -71,3 +87,6 @@ curl http://127.0.0.1:8010/api/v1/admin/monitor
 - Run a persistent Qdrant instance (non-memory).
 - Put API behind a reverse proxy with TLS.
 - Configure log shipping and monitor /api/v1/admin/monitor.
+- Follow `docs/deployment.md` for release sequence.
+- Follow `docs/migrations.md` for migration and rollback.
+- Follow `docs/smoke-test.md` before and after deployment.
diff --git a/docs/smoke-test.md b/docs/smoke-test.md
new file mode 100644
index 0000000..e548d9a
--- /dev/null
+++ b/docs/smoke-test.md
@@ -0,0 +1,27 @@
+# Smoke Test Checklist
+
+Run these checks before production release and immediately after deployment.
+
+## API
+
+- `GET /health` returns 200.
+- `GET /api/v1/admin/monitor` returns status and telemetry.
+- `POST /api/v1/search` returns recommendations.
+- `GET /api/v1/evaluate/{resource_id}` returns 200 or expected 404.
+- `POST /api/v1/compare` returns 200 or expected 404 when data not seeded.
+- `POST /api/v1/idea/assess` returns verdict and recommendation.
+- `POST /api/v1/idea/assess/export?format=markdown` returns markdown.
+- `POST /api/v1/idea/assess/batch/export?format=json` returns JSON envelope.
+
+## Web
+
+- Home page loads.
+- Idea page can run single assessment.
+- Batch export works for markdown and JSON.
+- Export history appears and re-export works.
+
+## Platform
+
+- Rate-limit headers present on API responses.
+- Logs are collected and visible.
+- DB and Redis connectivity verified.
diff --git a/scripts/check_rate_limit.sh b/scripts/check_rate_limit.sh
new file mode 100755
index 0000000..c3a57a8
--- /dev/null
+++ b/scripts/check_rate_limit.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+API_BASE="${OWLSCOPE_API_BASE:-http://127.0.0.1:8010}"
+
+echo "[rate-limit] Checking rate-limit headers on /api/v1/search ..."
+headers=$(mktemp)
+code=$(curl -s -o /tmp/owlscope-rate-limit.out -D "$headers" -w "%{http_code}" \
+  -X POST "$API_BASE/api/v1/search" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"python web framework"}')
+
+if [[ "$code" != "200" ]]; then
+  echo "Unexpected response code: $code"
+  cat /tmp/owlscope-rate-limit.out
+  exit 1
+fi
+
+if ! grep -qi "^X-RateLimit-Limit:" "$headers"; then
+  echo "Missing X-RateLimit-Limit header"
+  exit 1
+fi
+
+if ! grep -qi "^X-RateLimit-Remaining:" "$headers"; then
+  echo "Missing X-RateLimit-Remaining header"
+  exit 1
+fi
+
+echo "[rate-limit] Headers present and endpoint reachable."
diff --git a/scripts/release_check.sh b/scripts/release_check.sh
index 01bc41c..15088aa 100755
--- a/scripts/release_check.sh
+++ b/scripts/release_check.sh
@@ -7,17 +7,29 @@ cd "$ROOT_DIR"
 API_HOST="${OWLSCOPE_API_HOST:-127.0.0.1}"
 API_PORT="${OWLSCOPE_API_PORT:-8010}"
 API_BASE="http://${API_HOST}:${API_PORT}"
+RUN_INTEGRATION="${OWLSCOPE_RELEASE_CHECK_INTEGRATION:-0}"
 
-echo "[1/4] Running backend tests..."
+echo "[1/6] Validating deployment environment..."
+python scripts/validate_env.py --mode dev
+
+echo "[2/6] Running backend tests..."
 source .venv/bin/activate
 pytest -q -m "not integration"
 
-echo "[2/4] Building web app..."
+if [[ "$RUN_INTEGRATION" == "1" ]]; then
+  echo "[3/6] Running integration compare test..."
+  export OWLSCOPE_RUN_INTEGRATION=1
+  pytest -q -m integration tests/integration/test_compare_blackbox.py
+else
+  echo "[3/6] Skipping integration compare test (set OWLSCOPE_RELEASE_CHECK_INTEGRATION=1 to enable)"
+fi
+
+echo "[4/6] Building web app..."
 pushd web >/dev/null
 npm run build
 popd >/dev/null
 
-echo "[3/4] Starting API for smoke checks..."
+echo "[5/6] Starting API for smoke checks..."
 lsof -ti:"$API_PORT" | xargs kill -9 2>/dev/null || true
 python -m uvicorn src.api.main:app --host "$API_HOST" --port "$API_PORT" --log-level warning >/tmp/owlscope-release-check.log 2>&1 &
 API_PID=$!
@@ -37,11 +49,13 @@ if ! curl -fsS "$API_BASE/health" >/dev/null 2>&1; then
   exit 1
 fi
 
-echo "[4/4] Smoke testing key endpoints..."
+echo "[6/6] Smoke testing key endpoints..."
 curl -fsS -X POST "$API_BASE/api/v1/search" \
   -H "Content-Type: application/json" \
   -d '{"query":"python web framework"}' >/dev/null
 
+curl -fsS "$API_BASE/api/v1/admin/monitor" >/dev/null
+
 curl -fsS -X POST "$API_BASE/api/v1/idea/assess" \
   -H "Content-Type: application/json" \
   -d '{"idea":"Open-source assistant for startup idea validation"}' >/dev/null
@@ -61,4 +75,6 @@ if [[ "$COMPARE_CODE" != "200" && "$COMPARE_CODE" != "404" ]]; then
   exit 1
 fi
 
+bash scripts/check_rate_limit.sh
+
 echo "Release check passed."
diff --git a/scripts/run_integration_compare.sh b/scripts/run_integration_compare.sh
new file mode 100755
index 0000000..fad2593
--- /dev/null
+++ b/scripts/run_integration_compare.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT_DIR"
+
+echo "[integration] Ensuring local infra is up (postgres, redis)..."
+if ! docker compose up -d postgres redis; then
+	echo "[integration] docker compose failed (often due port conflicts)."
+	echo "[integration] Continuing with currently running local postgres/redis if reachable."
+fi
+
+echo "[integration] Running black-box compare integration test..."
+source .venv/bin/activate
+export OWLSCOPE_RUN_INTEGRATION=1
+pytest -q -m integration tests/integration/test_compare_blackbox.py
+
+echo "[integration] Passed."
diff --git a/scripts/validate_env.py b/scripts/validate_env.py
new file mode 100644
index 0000000..5a6f542
--- /dev/null
+++ b/scripts/validate_env.py
@@ -0,0 +1,44 @@
+"""Validate required runtime environment variables for deployment stages."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+from src.config import Settings
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate Owlscope deployment environment")
+    parser.add_argument("--mode", choices=["dev", "prod"], default="prod")
+    args = parser.parse_args()
+
+    resolved = Settings()
+    missing: list[str] = []
+
+    if not resolved.database_url:
+        missing.append("DATABASE_URL")
+    if not resolved.redis_url:
+        missing.append("REDIS_URL")
+
+    if args.mode == "prod":
+        if resolved.secret_key == "change-me-to-a-random-secret-key":
+            missing.append("SECRET_KEY(non-default)")
+
+    if missing:
+        print("[env-validate] Missing required settings:")
+        for item in sorted(set(missing)):
+            print(f"- {item}")
+        return 1
+
+    print(f"[env-validate] OK ({args.mode})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/src/api/main.py b/src/api/main.py
index ae95c75..028eceb 100644
--- a/src/api/main.py
+++ b/src/api/main.py
@@ -15,7 +15,7 @@
 from fastapi.middleware.cors import CORSMiddleware
 from redis.asyncio import Redis
 
-from src.api.routes import search, evaluate, recommend, resources, sessions, auth, idea
+from src.api.routes import search, evaluate, recommend, resources, sessions, auth, idea, admin
 from src.api.middleware.rate_limit import RateLimitMiddleware
 from src.api.middleware.access_log import AccessLogMiddleware
 from src.config import settings
@@ -111,6 +111,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
 app.include_router(resources.router, prefix="/api/v1", tags=["Resources"])
 app.include_router(sessions.router, prefix="/api/v1", tags=["Sessions"])
 app.include_router(auth.router, prefix="/api/v1", tags=["Auth"])
+app.include_router(admin.router, prefix="/api/v1", tags=["Admin"])
 
 
 @app.get("/health")
diff --git a/src/api/middleware/access_log.py b/src/api/middleware/access_log.py
index 13d090e..c200d00 100644
--- a/src/api/middleware/access_log.py
+++ b/src/api/middleware/access_log.py
@@ -10,6 +10,8 @@
 from starlette.requests import Request
 from starlette.responses import Response
 
+from src.api.telemetry import record_request
+
 logger = logging.getLogger("owlscope.access")
 
 # Paths to skip (noisy health checks, static assets)
@@ -42,3 +44,4 @@ async def dispatch(self, request: Request, call_next) -> Response:
                 status,
                 elapsed_ms,
             )
+            record_request(status_code=status, latency_ms=elapsed_ms)
diff --git a/src/api/routes/admin.py b/src/api/routes/admin.py
new file mode 100644
index 0000000..82611cb
--- /dev/null
+++ b/src/api/routes/admin.py
@@ -0,0 +1,18 @@
+"""Operational/admin endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from src.api.telemetry import snapshot
+
+router = APIRouter()
+
+
+@router.get("/admin/monitor")
+async def monitor() -> dict[str, object]:
+    """Return lightweight runtime monitoring counters."""
+    return {
+        "status": "ok",
+        "telemetry": snapshot(),
+    }
diff --git a/src/api/telemetry.py b/src/api/telemetry.py
new file mode 100644
index 0000000..507617f
--- /dev/null
+++ b/src/api/telemetry.py
@@ -0,0 +1,44 @@
+"""In-process telemetry helpers for lightweight operational monitoring."""
+
+from __future__ import annotations
+
+from collections import deque
+from datetime import datetime, timezone
+from threading import Lock
+
+_lock = Lock()
+_started_at = datetime.now(timezone.utc)
+_total_requests = 0
+_total_errors = 0
+_total_latency_ms = 0.0
+_recent_statuses: deque[int] = deque(maxlen=200)
+
+
+def record_request(status_code: int, latency_ms: float) -> None:
+    """Record a request outcome for lightweight runtime monitoring."""
+    global _total_requests, _total_errors, _total_latency_ms
+    with _lock:
+        _total_requests += 1
+        _total_latency_ms += float(latency_ms)
+        _recent_statuses.append(int(status_code))
+        if status_code >= 500:
+            _total_errors += 1
+
+
+def snapshot() -> dict[str, object]:
+    """Return an atomic snapshot of telemetry counters."""
+    with _lock:
+        total_requests = _total_requests
+        total_errors = _total_errors
+        avg_latency_ms = (_total_latency_ms / total_requests) if total_requests else 0.0
+        recent = list(_recent_statuses)
+
+    return {
+        "started_at": _started_at.isoformat(),
+        "total_requests": total_requests,
+        "total_errors": total_errors,
+        "error_rate": round((total_errors / total_requests), 4) if total_requests else 0.0,
+        "avg_latency_ms": round(avg_latency_ms, 2),
+        "recent_requests": len(recent),
+        "recent_5xx": sum(1 for code in recent if code >= 500),
+    }
diff --git a/tests/integration/test_compare_blackbox.py b/tests/integration/test_compare_blackbox.py
index 846ba38..aa6b45f 100644
--- a/tests/integration/test_compare_blackbox.py
+++ b/tests/integration/test_compare_blackbox.py
@@ -7,6 +7,7 @@
 import socket
 import subprocess
 import sys
+import tempfile
 import time
 from urllib.parse import urlparse
 from pathlib import Path
@@ -151,6 +152,8 @@ def test_compare_endpoint_blackbox() -> None:
 
     _require_local_infra_or_skip(env["DATABASE_URL"], env["REDIS_URL"])
 
+    log_file = tempfile.NamedTemporaryFile(mode="w+", encoding="utf-8", delete=False)
+
     proc = subprocess.Popen(
         [
             sys.executable,
@@ -166,7 +169,7 @@ def test_compare_endpoint_blackbox() -> None:
         ],
         cwd=str(root),
         env=env,
-        stdout=subprocess.PIPE,
+        stdout=log_file,
         stderr=subprocess.STDOUT,
         text=True,
     )
@@ -197,10 +200,21 @@ def test_compare_endpoint_blackbox() -> None:
     finally:
         proc.terminate()
         try:
-            _, logs = proc.communicate(timeout=10)
+            proc.wait(timeout=10)
         except subprocess.TimeoutExpired:
             proc.kill()
-            _, logs = proc.communicate(timeout=5)
+            proc.wait(timeout=5)
+
+        try:
+            with open(log_file.name, encoding="utf-8") as fh:
+                logs = fh.read()
+        except Exception:
+            logs = ""
+        finally:
+            try:
+                os.unlink(log_file.name)
+            except Exception:
+                pass
 
     if logs:
         # Keep output concise while still preserving the error context.
diff --git a/tests/test_api.py b/tests/test_api.py
index 35a3c52..9261b20 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -76,6 +76,16 @@ async def test_discover_skills_endpoint(client: AsyncClient):
     assert resp.status_code == 200
 
 
+@pytest.mark.asyncio
+async def test_admin_monitor_endpoint(client: AsyncClient):
+    resp = await client.get("/api/v1/admin/monitor")
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["status"] == "ok"
+    assert "telemetry" in data
+    assert "total_requests" in data["telemetry"]
+
+
 @pytest.mark.asyncio
 async def test_assess_idea_endpoint(client: AsyncClient):
     resp = await client.post(

From d9d8012136770015113175913a67476f93504e93 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 01:53:45 +0800
Subject: [PATCH 12/17] feat(deploy): add production compose override and
 post-deploy checks

---
 README.md                    |  7 ++++++
 README.zh-CN.md              |  7 ++++++
 docker-compose.prod.yml      | 24 ++++++++++++++++++
 docs/deployment.md           |  6 +++--
 docs/self-hosting.md         | 12 +++++++++
 scripts/post_deploy_check.sh | 49 ++++++++++++++++++++++++++++++++++++
 6 files changed, 103 insertions(+), 2 deletions(-)
 create mode 100644 docker-compose.prod.yml
 create mode 100755 scripts/post_deploy_check.sh

diff --git a/README.md b/README.md
index ba3d237..6730b45 100644
--- a/README.md
+++ b/README.md
@@ -191,6 +191,13 @@ Production-readiness docs:
 - Smoke checklist: `docs/smoke-test.md`
 - Release checklist: `docs/release-checklist.md`
 
+Production launch commands:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+bash scripts/post_deploy_check.sh
+```
+
 ## API Reference
 
 ### REST API
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 13d69cf..e149f8a 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -155,6 +155,13 @@ OWLSCOPE_RELEASE_CHECK_INTEGRATION=1 bash scripts/release_check.sh
 - 冒烟检查：`docs/smoke-test.md`
 - 发布清单：`docs/release-checklist.md`
 
+生产部署命令：
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+bash scripts/post_deploy_check.sh
+```
+
 ## API 参考
 
 ```bash
diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml
new file mode 100644
index 0000000..0e104e6
--- /dev/null
+++ b/docker-compose.prod.yml
@@ -0,0 +1,24 @@
+services:
+  api:
+    restart: unless-stopped
+    command: uvicorn src.api.main:app --host 0.0.0.0 --port 8000
+    volumes: []
+    environment:
+      - DEBUG=false
+
+  web:
+    restart: unless-stopped
+    volumes: []
+    environment:
+      - NODE_ENV=production
+      - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL:-http://127.0.0.1:8010}
+      - OWLSCOPE_API_ORIGIN=${OWLSCOPE_API_ORIGIN:-http://api:8000}
+
+  postgres:
+    restart: unless-stopped
+
+  redis:
+    restart: unless-stopped
+
+  qdrant:
+    restart: unless-stopped
diff --git a/docs/deployment.md b/docs/deployment.md
index 64b9c88..5520c6e 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -15,8 +15,8 @@ This runbook covers a safe baseline deployment for Owlscope.
 
 - Build web:
   - `cd web && npm ci && npm run build`
-- Start services (example with Docker Compose):
-  - `docker compose up -d`
+- Start services (production profile with override):
+  - `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build`
 
 ## 3. Post-Deploy Verification
 
@@ -24,6 +24,8 @@ This runbook covers a safe baseline deployment for Owlscope.
   - `curl http://127.0.0.1:8010/health`
 - Admin monitor:
   - `curl http://127.0.0.1:8010/api/v1/admin/monitor`
+- One-command post-deploy checks:
+  - `bash scripts/post_deploy_check.sh`
 - Rate-limit headers:
   - `bash scripts/check_rate_limit.sh`
 - Core smoke APIs:
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index 27fb2f7..6757f62 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -76,6 +76,18 @@ bash scripts/release_check.sh
 OWLSCOPE_RELEASE_CHECK_INTEGRATION=1 bash scripts/release_check.sh
 ```
 
+## Production Compose Launch
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+```
+
+Then run post-deploy checks:
+
+```bash
+bash scripts/post_deploy_check.sh
+```
+
 ## Data Notes
 
 - In development, Qdrant may run in in-memory fallback mode.
diff --git a/scripts/post_deploy_check.sh b/scripts/post_deploy_check.sh
new file mode 100755
index 0000000..9dcf2ec
--- /dev/null
+++ b/scripts/post_deploy_check.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+API_BASE="${OWLSCOPE_API_BASE:-http://127.0.0.1:8010}"
+
+echo "[post-deploy] Waiting for API readiness ..."
+for _ in {1..90}; do
+  if curl -fsS "$API_BASE/health" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 1
+done
+
+if ! curl -fsS "$API_BASE/health" >/dev/null 2>&1; then
+  echo "[post-deploy] API did not become ready in time"
+  exit 1
+fi
+
+echo "[post-deploy] Checking /health ..."
+curl -fsS "$API_BASE/health" >/dev/null
+
+echo "[post-deploy] Checking /api/v1/admin/monitor ..."
+curl -fsS "$API_BASE/api/v1/admin/monitor" >/dev/null
+
+echo "[post-deploy] Checking search endpoint ..."
+curl -fsS -X POST "$API_BASE/api/v1/search" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"python web framework"}' >/dev/null
+
+echo "[post-deploy] Checking idea assess endpoint ..."
+curl -fsS -X POST "$API_BASE/api/v1/idea/assess" \
+  -H "Content-Type: application/json" \
+  -d '{"idea":"Open-source assistant for startup idea validation"}' >/dev/null
+
+echo "[post-deploy] Checking batch export markdown endpoint ..."
+code=$(curl -s -o /tmp/owlscope-post-deploy-batch.out -w "%{http_code}" \
+  -X POST "$API_BASE/api/v1/idea/assess/batch/export?format=markdown" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"idea":"Open-source API mocking tool"},{"idea":"PR review assistant for OSS maintainers"}],"limit":6,"max_concurrency":2,"per_item_timeout_seconds":30}')
+if [[ "$code" != "200" ]]; then
+  echo "Unexpected batch export status: $code"
+  cat /tmp/owlscope-post-deploy-batch.out
+  exit 1
+fi
+
+echo "[post-deploy] Checking rate-limit headers ..."
+bash scripts/check_rate_limit.sh
+
+echo "[post-deploy] All checks passed."

From 75f42c5b946d4cede9bb42e55f8ed7a76249d0a0 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 10:29:22 +0800
Subject: [PATCH 13/17] feat(cli): add local-first ops deploy commands

---
 README.md            |  16 +++++
 README.zh-CN.md      |  21 +++++++
 cli/__init__.py      | 136 ++++++++++++++++++++++++++++++++++++++++++-
 docs/deployment.md   |   5 ++
 docs/self-hosting.md |   8 +++
 5 files changed, 185 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6730b45..e1dab38 100644
--- a/README.md
+++ b/README.md
@@ -140,6 +140,15 @@ pip install -e ".[cli]"
 
 # Search for projects
 owlscope search "Python async HTTP client with HTTP/2"
+
+# Ops preflight (local-first)
+owlscope ops preflight
+
+# Ops deploy (local direct mode, docker as fallback)
+owlscope ops deploy --mode local
+
+# Ops deploy via docker explicitly
+owlscope ops deploy --mode docker
 ```
 
 ## Usage Guidelines
@@ -198,6 +207,13 @@ docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
 bash scripts/post_deploy_check.sh
 ```
 
+CLI-first alternative:
+
+```bash
+owlscope ops deploy --mode local
+# if needed: owlscope ops deploy --mode docker
+```
+
 ## API Reference
 
 ### REST API
diff --git a/README.zh-CN.md b/README.zh-CN.md
index e149f8a..94003eb 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -106,6 +106,20 @@ npm install
 npm run dev
 ```
 
+CLI：
+```bash
+pip install -e ".[cli]"
+
+# 发布前预检
+owlscope ops preflight
+
+# 本地直跑优先（失败可自动回退 Docker）
+owlscope ops deploy --mode local
+
+# 显式走 Docker
+owlscope ops deploy --mode docker
+```
+
 ## 使用指南
 
 - BYOK（自带 Key）：使用 LLM 功能前，必须在 `.env` 配置你自己的 API Key。
@@ -162,6 +176,13 @@ docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
 bash scripts/post_deploy_check.sh
 ```
 
+CLI 方式（优先本地直跑）：
+
+```bash
+owlscope ops deploy --mode local
+# 备选：owlscope ops deploy --mode docker
+```
+
 ## API 参考
 
 ```bash
diff --git a/cli/__init__.py b/cli/__init__.py
index b25b240..3987be7 100644
--- a/cli/__init__.py
+++ b/cli/__init__.py
@@ -3,8 +3,12 @@
 from __future__ import annotations
 
 import os
+import subprocess
 import sys
+import time
 from pathlib import Path
+from urllib.error import URLError
+from urllib.request import urlopen
 
 import typer
 from rich.console import Console
@@ -22,16 +26,146 @@
     help="🦉 Owlscope CLI — search, evaluate, and compare open-source projects and Agent Skills.",
     no_args_is_help=True,
 )
+ops_app = typer.Typer(help="Release and deployment operations (local-first, docker optional).")
+app.add_typer(ops_app, name="ops")
 console = Console()
+ROOT_DIR = Path(__file__).resolve().parent.parent
 
 
 def _get_client() -> OwlscopeClient:
     return OwlscopeClient(OwlscopeConfig(
-        base_url=os.environ.get("OWLSCOPE_API_URL", "http://localhost:8000"),
+        base_url=os.environ.get("OWLSCOPE_API_URL", "http://127.0.0.1:8010"),
         api_key=os.environ.get("OWLSCOPE_API_KEY"),
     ))
 
 
+def _run(cmd: list[str], env: dict[str, str] | None = None) -> None:
+    subprocess.run(cmd, cwd=str(ROOT_DIR), env=env, check=True)
+
+
+def _is_healthy(api_base: str) -> bool:
+    try:
+        with urlopen(f"{api_base}/health", timeout=2.0) as resp:
+            return resp.status == 200
+    except (URLError, TimeoutError, ValueError):
+        return False
+
+
+def _wait_health(api_base: str, timeout_s: int = 90) -> bool:
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        if _is_healthy(api_base):
+            return True
+        time.sleep(1)
+    return False
+
+
+def _deploy_docker(api_base: str) -> None:
+    console.print("[bold cyan]Deploying with Docker (backup path)...[/bold cyan]")
+    _run([
+        "docker",
+        "compose",
+        "-f",
+        "docker-compose.yml",
+        "-f",
+        "docker-compose.prod.yml",
+        "up",
+        "-d",
+        "--build",
+    ])
+    env = os.environ.copy()
+    env["OWLSCOPE_API_BASE"] = api_base
+    _run(["bash", "scripts/post_deploy_check.sh"], env=env)
+
+
+@ops_app.command("preflight")
+def ops_preflight(
+    integration: bool = typer.Option(False, "--integration", help="Include integration compare test"),
+) -> None:
+    """Run one-command release preflight checks."""
+    env = os.environ.copy()
+    env["OWLSCOPE_RELEASE_CHECK_INTEGRATION"] = "1" if integration else "0"
+    _run(["bash", "scripts/release_check.sh"], env=env)
+    console.print("[green]Preflight checks passed.[/green]")
+
+
+@ops_app.command("check")
+def ops_check(
+    api_base: str = typer.Option("http://127.0.0.1:8010", help="API base URL"),
+) -> None:
+    """Run post-deploy checks against a running API."""
+    env = os.environ.copy()
+    env["OWLSCOPE_API_BASE"] = api_base
+    _run(["bash", "scripts/post_deploy_check.sh"], env=env)
+    console.print("[green]Post-deploy checks passed.[/green]")
+
+
+@ops_app.command("deploy")
+def ops_deploy(
+    mode: str = typer.Option("local", help="Deployment mode: local or docker"),
+    api_host: str = typer.Option("127.0.0.1", help="API host for local mode"),
+    api_port: int = typer.Option(8010, help="API port for local mode"),
+    fallback_docker: bool = typer.Option(True, "--fallback-docker/--no-fallback-docker", help="Use docker deployment if local mode fails"),
+) -> None:
+    """Deploy with local-first strategy; optionally fallback to docker."""
+    selected_mode = mode.strip().lower()
+    api_base = f"http://{api_host}:{api_port}"
+
+    if selected_mode not in {"local", "docker"}:
+        console.print("[red]mode must be 'local' or 'docker'[/red]")
+        raise typer.Exit(1)
+
+    if selected_mode == "docker":
+        _deploy_docker(api_base)
+        console.print("[green]Docker deploy completed.[/green]")
+        return
+
+    env = os.environ.copy()
+    try:
+        _run([sys.executable, "scripts/validate_env.py", "--mode", "prod"], env=env)
+
+        api_proc: subprocess.Popen[str] | None = None
+        log_file = "/tmp/owlscope-cli-local-api.log"
+
+        if not _is_healthy(api_base):
+            console.print("[bold cyan]Starting local API (direct mode)...[/bold cyan]")
+            log_handle = open(log_file, "a", encoding="utf-8")
+            api_proc = subprocess.Popen(
+                [
+                    sys.executable,
+                    "-m",
+                    "uvicorn",
+                    "src.api.main:app",
+                    "--host",
+                    api_host,
+                    "--port",
+                    str(api_port),
+                    "--log-level",
+                    "warning",
+                ],
+                cwd=str(ROOT_DIR),
+                stdout=log_handle,
+                stderr=subprocess.STDOUT,
+                text=True,
+            )
+
+            if not _wait_health(api_base):
+                raise RuntimeError("Local API did not become healthy in time")
+
+        env["OWLSCOPE_API_BASE"] = api_base
+        _run(["bash", "scripts/post_deploy_check.sh"], env=env)
+
+        console.print("[green]Local deployment checks passed.[/green]")
+        if api_proc is not None:
+            console.print(f"[dim]Local API started by CLI, PID={api_proc.pid}, logs={log_file}[/dim]")
+    except Exception as exc:
+        console.print(f"[yellow]Local mode failed: {exc}[/yellow]")
+        if not fallback_docker:
+            raise typer.Exit(1)
+        _deploy_docker(api_base)
+        console.print("[green]Fallback docker deploy completed.[/green]")
+
+
 @app.command()
 def search(
     query: str = typer.Argument(..., help="Natural language search query"),
diff --git a/docs/deployment.md b/docs/deployment.md
index 5520c6e..fd186c4 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -15,8 +15,12 @@ This runbook covers a safe baseline deployment for Owlscope.
 
 - Build web:
   - `cd web && npm ci && npm run build`
+- CLI-first launch (local direct mode):
+  - `owlscope ops deploy --mode local`
 - Start services (production profile with override):
   - `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build`
+- CLI docker backup path:
+  - `owlscope ops deploy --mode docker`
 
 ## 3. Post-Deploy Verification
 
@@ -26,6 +30,7 @@ This runbook covers a safe baseline deployment for Owlscope.
   - `curl http://127.0.0.1:8010/api/v1/admin/monitor`
 - One-command post-deploy checks:
   - `bash scripts/post_deploy_check.sh`
+  - `owlscope ops check`
 - Rate-limit headers:
   - `bash scripts/check_rate_limit.sh`
 - Core smoke APIs:
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index 6757f62..21238e4 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -88,6 +88,14 @@ Then run post-deploy checks:
 bash scripts/post_deploy_check.sh
 ```
 
+CLI-first alternative (direct mode first, docker backup optional):
+
+```bash
+owlscope ops preflight
+owlscope ops deploy --mode local
+# backup path: owlscope ops deploy --mode docker
+```
+
 ## Data Notes
 
 - In development, Qdrant may run in in-memory fallback mode.

From 0b0b0fa14a847cfb3e44e51b1d9608868b798037 Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 10:46:11 +0800
Subject: [PATCH 14/17] feat(cli): support optional web startup and checks

---
 README.md            |  4 +++
 README.zh-CN.md      |  4 +++
 cli/__init__.py      | 81 +++++++++++++++++++++++++++++++++++++++++---
 docs/deployment.md   |  4 +++
 docs/self-hosting.md |  2 ++
 scripts/check_web.sh | 27 +++++++++++++++
 6 files changed, 117 insertions(+), 5 deletions(-)
 create mode 100755 scripts/check_web.sh

diff --git a/README.md b/README.md
index e1dab38..e056349 100644
--- a/README.md
+++ b/README.md
@@ -147,6 +147,9 @@ owlscope ops preflight
 # Ops deploy (local direct mode, docker as fallback)
 owlscope ops deploy --mode local
 
+# Include frontend startup and checks
+owlscope ops deploy --mode local --with-web
+
 # Ops deploy via docker explicitly
 owlscope ops deploy --mode docker
 ```
@@ -212,6 +215,7 @@ CLI-first alternative:
 ```bash
 owlscope ops deploy --mode local
 # if needed: owlscope ops deploy --mode docker
+# include web checks: owlscope ops check --with-web
 ```
 
 ## API Reference
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 94003eb..60d6d6b 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -116,6 +116,9 @@ owlscope ops preflight
 # 本地直跑优先（失败可自动回退 Docker）
 owlscope ops deploy --mode local
 
+# 包含前端启动与校验
+owlscope ops deploy --mode local --with-web
+
 # 显式走 Docker
 owlscope ops deploy --mode docker
 ```
@@ -181,6 +184,7 @@ CLI 方式（优先本地直跑）：
 ```bash
 owlscope ops deploy --mode local
 # 备选：owlscope ops deploy --mode docker
+# 包含前端检查：owlscope ops check --with-web
 ```
 
 ## API 参考
diff --git a/cli/__init__.py b/cli/__init__.py
index 3987be7..19e47b4 100644
--- a/cli/__init__.py
+++ b/cli/__init__.py
@@ -39,8 +39,8 @@ def _get_client() -> OwlscopeClient:
     ))
 
 
-def _run(cmd: list[str], env: dict[str, str] | None = None) -> None:
-    subprocess.run(cmd, cwd=str(ROOT_DIR), env=env, check=True)
+def _run(cmd: list[str], env: dict[str, str] | None = None, cwd: Path | None = None) -> None:
+    subprocess.run(cmd, cwd=str(cwd or ROOT_DIR), env=env, check=True)
 
 
 def _is_healthy(api_base: str) -> bool:
@@ -60,7 +60,24 @@ def _wait_health(api_base: str, timeout_s: int = 90) -> bool:
     return False
 
 
-def _deploy_docker(api_base: str) -> None:
+def _is_url_ok(url: str) -> bool:
+    try:
+        with urlopen(url, timeout=2.0) as resp:
+            return 200 <= resp.status < 500
+    except (URLError, TimeoutError, ValueError):
+        return False
+
+
+def _wait_url(url: str, timeout_s: int = 120) -> bool:
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        if _is_url_ok(url):
+            return True
+        time.sleep(1)
+    return False
+
+
+def _deploy_docker(api_base: str, web_base: str, with_web: bool) -> None:
     console.print("[bold cyan]Deploying with Docker (backup path)...[/bold cyan]")
     _run([
         "docker",
@@ -76,6 +93,9 @@ def _deploy_docker(api_base: str) -> None:
     env = os.environ.copy()
     env["OWLSCOPE_API_BASE"] = api_base
     _run(["bash", "scripts/post_deploy_check.sh"], env=env)
+    if with_web:
+        env["OWLSCOPE_WEB_BASE"] = web_base
+        _run(["bash", "scripts/check_web.sh"], env=env)
 
 
 @ops_app.command("preflight")
@@ -92,11 +112,16 @@ def ops_preflight(
 @ops_app.command("check")
 def ops_check(
     api_base: str = typer.Option("http://127.0.0.1:8010", help="API base URL"),
+    with_web: bool = typer.Option(False, "--with-web", help="Also validate web endpoint"),
+    web_base: str = typer.Option("http://127.0.0.1:3100", help="Web base URL"),
 ) -> None:
     """Run post-deploy checks against a running API."""
     env = os.environ.copy()
     env["OWLSCOPE_API_BASE"] = api_base
     _run(["bash", "scripts/post_deploy_check.sh"], env=env)
+    if with_web:
+        env["OWLSCOPE_WEB_BASE"] = web_base
+        _run(["bash", "scripts/check_web.sh"], env=env)
     console.print("[green]Post-deploy checks passed.[/green]")
 
 
@@ -105,18 +130,28 @@ def ops_deploy(
     mode: str = typer.Option("local", help="Deployment mode: local or docker"),
     api_host: str = typer.Option("127.0.0.1", help="API host for local mode"),
     api_port: int = typer.Option(8010, help="API port for local mode"),
+    with_web: bool = typer.Option(False, "--with-web", help="Also ensure web is started and validated"),
+    web_host: str = typer.Option("127.0.0.1", help="Web host for local mode"),
+    web_port: int = typer.Option(3100, help="Web port for local mode"),
+    web_mode: str = typer.Option("start", help="Web mode for local: start or dev"),
     fallback_docker: bool = typer.Option(True, "--fallback-docker/--no-fallback-docker", help="Use docker deployment if local mode fails"),
 ) -> None:
     """Deploy with local-first strategy; optionally fallback to docker."""
     selected_mode = mode.strip().lower()
     api_base = f"http://{api_host}:{api_port}"
+    web_base = f"http://{web_host}:{web_port}"
+    selected_web_mode = web_mode.strip().lower()
 
     if selected_mode not in {"local", "docker"}:
         console.print("[red]mode must be 'local' or 'docker'[/red]")
         raise typer.Exit(1)
 
+    if selected_web_mode not in {"start", "dev"}:
+        console.print("[red]web-mode must be 'start' or 'dev'[/red]")
+        raise typer.Exit(1)
+
     if selected_mode == "docker":
-        _deploy_docker(api_base)
+        _deploy_docker(api_base, web_base, with_web)
         console.print("[green]Docker deploy completed.[/green]")
         return
 
@@ -125,7 +160,9 @@ def ops_deploy(
         _run([sys.executable, "scripts/validate_env.py", "--mode", "prod"], env=env)
 
         api_proc: subprocess.Popen[str] | None = None
+        web_proc: subprocess.Popen[str] | None = None
         log_file = "/tmp/owlscope-cli-local-api.log"
+        web_log_file = "/tmp/owlscope-cli-local-web.log"
 
         if not _is_healthy(api_base):
             console.print("[bold cyan]Starting local API (direct mode)...[/bold cyan]")
@@ -155,14 +192,48 @@ def ops_deploy(
         env["OWLSCOPE_API_BASE"] = api_base
         _run(["bash", "scripts/post_deploy_check.sh"], env=env)
 
+        if with_web:
+            if not _is_url_ok(web_base):
+                console.print("[bold cyan]Starting local Web...[/bold cyan]")
+                web_env = os.environ.copy()
+                web_env["OWLSCOPE_API_ORIGIN"] = api_base
+                web_log_handle = open(web_log_file, "a", encoding="utf-8")
+                if selected_web_mode == "start":
+                    _run(["npm", "run", "build"], env=web_env, cwd=ROOT_DIR / "web")
+                    web_proc = subprocess.Popen(
+                        ["npx", "next", "start", "-H", web_host, "-p", str(web_port)],
+                        cwd=str(ROOT_DIR / "web"),
+                        env=web_env,
+                        stdout=web_log_handle,
+                        stderr=subprocess.STDOUT,
+                        text=True,
+                    )
+                else:
+                    web_proc = subprocess.Popen(
+                        ["npx", "next", "dev", "-H", web_host, "-p", str(web_port)],
+                        cwd=str(ROOT_DIR / "web"),
+                        env=web_env,
+                        stdout=web_log_handle,
+                        stderr=subprocess.STDOUT,
+                        text=True,
+                    )
+
+                if not _wait_url(web_base):
+                    raise RuntimeError("Local web did not become ready in time")
+
+            env["OWLSCOPE_WEB_BASE"] = web_base
+            _run(["bash", "scripts/check_web.sh"], env=env)
+
         console.print("[green]Local deployment checks passed.[/green]")
         if api_proc is not None:
             console.print(f"[dim]Local API started by CLI, PID={api_proc.pid}, logs={log_file}[/dim]")
+        if web_proc is not None:
+            console.print(f"[dim]Local Web started by CLI, PID={web_proc.pid}, logs={web_log_file}[/dim]")
     except Exception as exc:
         console.print(f"[yellow]Local mode failed: {exc}[/yellow]")
         if not fallback_docker:
             raise typer.Exit(1)
-        _deploy_docker(api_base)
+        _deploy_docker(api_base, web_base, with_web)
         console.print("[green]Fallback docker deploy completed.[/green]")
 
 
diff --git a/docs/deployment.md b/docs/deployment.md
index fd186c4..b67d5b4 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -17,10 +17,13 @@ This runbook covers a safe baseline deployment for Owlscope.
   - `cd web && npm ci && npm run build`
 - CLI-first launch (local direct mode):
   - `owlscope ops deploy --mode local`
+- CLI launch with frontend validation:
+  - `owlscope ops deploy --mode local --with-web`
 - Start services (production profile with override):
   - `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build`
 - CLI docker backup path:
   - `owlscope ops deploy --mode docker`
+  - `owlscope ops deploy --mode docker --with-web`
 
 ## 3. Post-Deploy Verification
 
@@ -31,6 +34,7 @@ This runbook covers a safe baseline deployment for Owlscope.
 - One-command post-deploy checks:
   - `bash scripts/post_deploy_check.sh`
   - `owlscope ops check`
+  - `owlscope ops check --with-web`
 - Rate-limit headers:
   - `bash scripts/check_rate_limit.sh`
 - Core smoke APIs:
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index 21238e4..dc06186 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -93,7 +93,9 @@ CLI-first alternative (direct mode first, docker backup optional):
 ```bash
 owlscope ops preflight
 owlscope ops deploy --mode local
+owlscope ops deploy --mode local --with-web
 # backup path: owlscope ops deploy --mode docker
+owlscope ops check --with-web
 ```
 
 ## Data Notes
diff --git a/scripts/check_web.sh b/scripts/check_web.sh
new file mode 100755
index 0000000..eac287e
--- /dev/null
+++ b/scripts/check_web.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+WEB_BASE="${OWLSCOPE_WEB_BASE:-http://127.0.0.1:3100}"
+
+echo "[web-check] Waiting for web readiness ..."
+for _ in {1..120}; do
+  if curl -fsS "$WEB_BASE" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 1
+done
+
+if ! curl -fsS "$WEB_BASE" >/dev/null 2>&1; then
+  echo "[web-check] Web did not become ready in time: $WEB_BASE"
+  exit 1
+fi
+
+echo "[web-check] Checking /idea page ..."
+code=$(curl -s -o /tmp/owlscope-web-idea.out -w "%{http_code}" "$WEB_BASE/idea")
+if [[ "$code" != "200" ]]; then
+  echo "[web-check] Unexpected /idea status: $code"
+  cat /tmp/owlscope-web-idea.out
+  exit 1
+fi
+
+echo "[web-check] Web checks passed."

From 0085c020e760a17884f5bb1441567058593ef13f Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 11:08:49 +0800
Subject: [PATCH 15/17] feat(cli): add detached lifecycle and stop command

---
 README.md            |   7 +++
 README.zh-CN.md      |   7 +++
 cli/__init__.py      | 130 +++++++++++++++++++++++++++++++++++++++++--
 docs/deployment.md   |   4 ++
 docs/self-hosting.md |   2 +
 5 files changed, 144 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index e056349..0e7bcaf 100644
--- a/README.md
+++ b/README.md
@@ -150,8 +150,14 @@ owlscope ops deploy --mode local
 # Include frontend startup and checks
 owlscope ops deploy --mode local --with-web
 
+# Run checks without leaving background processes
+owlscope ops deploy --mode local --with-web --no-detached
+
 # Ops deploy via docker explicitly
 owlscope ops deploy --mode docker
+
+# Stop processes started by CLI deploy
+owlscope ops stop
 ```
 
 ## Usage Guidelines
@@ -216,6 +222,7 @@ CLI-first alternative:
 owlscope ops deploy --mode local
 # if needed: owlscope ops deploy --mode docker
 # include web checks: owlscope ops check --with-web
+# stop local managed processes: owlscope ops stop
 ```
 
 ## API Reference
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 60d6d6b..5bac98d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -119,8 +119,14 @@ owlscope ops deploy --mode local
 # 包含前端启动与校验
 owlscope ops deploy --mode local --with-web
 
+# 校验完成后自动回收本次启动进程
+owlscope ops deploy --mode local --with-web --no-detached
+
 # 显式走 Docker
 owlscope ops deploy --mode docker
+
+# 停止 CLI 启动的本地进程
+owlscope ops stop
 ```
 
 ## 使用指南
@@ -185,6 +191,7 @@ CLI 方式（优先本地直跑）：
 owlscope ops deploy --mode local
 # 备选：owlscope ops deploy --mode docker
 # 包含前端检查：owlscope ops check --with-web
+# 停止 CLI 托管进程：owlscope ops stop
 ```
 
 ## API 参考
diff --git a/cli/__init__.py b/cli/__init__.py
index 19e47b4..31a027c 100644
--- a/cli/__init__.py
+++ b/cli/__init__.py
@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import json
 import os
+import signal
 import subprocess
 import sys
 import time
@@ -30,6 +32,7 @@
 app.add_typer(ops_app, name="ops")
 console = Console()
 ROOT_DIR = Path(__file__).resolve().parent.parent
+STATE_FILE = Path("/tmp/owlscope-cli-runtime.json")
 
 
 def _get_client() -> OwlscopeClient:
@@ -43,6 +46,57 @@ def _run(cmd: list[str], env: dict[str, str] | None = None, cwd: Path | None = N
     subprocess.run(cmd, cwd=str(cwd or ROOT_DIR), env=env, check=True)
 
 
+def _load_state() -> dict[str, object]:
+    if not STATE_FILE.exists():
+        return {}
+    try:
+        return json.loads(STATE_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _save_state(state: dict[str, object]) -> None:
+    STATE_FILE.write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+
+def _clear_state() -> None:
+    try:
+        STATE_FILE.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def _is_pid_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+def _stop_pid(pid: int, name: str, timeout_s: float = 8.0) -> bool:
+    if not _is_pid_running(pid):
+        return False
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except OSError:
+        return False
+
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        if not _is_pid_running(pid):
+            return True
+        time.sleep(0.2)
+
+    try:
+        os.kill(pid, signal.SIGKILL)
+        return True
+    except OSError:
+        console.print(f"[yellow]Unable to force-stop {name} process (pid={pid})[/yellow]")
+        return False
+
+
 def _is_healthy(api_base: str) -> bool:
     try:
         with urlopen(f"{api_base}/health", timeout=2.0) as resp:
@@ -134,6 +188,7 @@ def ops_deploy(
     web_host: str = typer.Option("127.0.0.1", help="Web host for local mode"),
     web_port: int = typer.Option(3100, help="Web port for local mode"),
     web_mode: str = typer.Option("start", help="Web mode for local: start or dev"),
+    detached: bool = typer.Option(True, "--detached/--no-detached", help="Keep CLI-started processes running after checks"),
     fallback_docker: bool = typer.Option(True, "--fallback-docker/--no-fallback-docker", help="Use docker deployment if local mode fails"),
 ) -> None:
     """Deploy with local-first strategy; optionally fallback to docker."""
@@ -156,11 +211,12 @@ def ops_deploy(
         return
 
     env = os.environ.copy()
+    started_state: dict[str, object] = {}
+    api_proc: subprocess.Popen[str] | None = None
+    web_proc: subprocess.Popen[str] | None = None
     try:
         _run([sys.executable, "scripts/validate_env.py", "--mode", "prod"], env=env)
 
-        api_proc: subprocess.Popen[str] | None = None
-        web_proc: subprocess.Popen[str] | None = None
         log_file = "/tmp/owlscope-cli-local-api.log"
         web_log_file = "/tmp/owlscope-cli-local-web.log"
 
@@ -189,6 +245,14 @@ def ops_deploy(
             if not _wait_health(api_base):
                 raise RuntimeError("Local API did not become healthy in time")
 
+            started_state["api"] = {
+                "pid": api_proc.pid,
+                "host": api_host,
+                "port": api_port,
+                "base": api_base,
+                "log": log_file,
+            }
+
         env["OWLSCOPE_API_BASE"] = api_base
         _run(["bash", "scripts/post_deploy_check.sh"], env=env)
 
@@ -221,15 +285,40 @@ def ops_deploy(
                 if not _wait_url(web_base):
                     raise RuntimeError("Local web did not become ready in time")
 
+                started_state["web"] = {
+                    "pid": web_proc.pid,
+                    "host": web_host,
+                    "port": web_port,
+                    "base": web_base,
+                    "mode": selected_web_mode,
+                    "log": web_log_file,
+                }
+
             env["OWLSCOPE_WEB_BASE"] = web_base
             _run(["bash", "scripts/check_web.sh"], env=env)
 
         console.print("[green]Local deployment checks passed.[/green]")
-        if api_proc is not None:
-            console.print(f"[dim]Local API started by CLI, PID={api_proc.pid}, logs={log_file}[/dim]")
-        if web_proc is not None:
-            console.print(f"[dim]Local Web started by CLI, PID={web_proc.pid}, logs={web_log_file}[/dim]")
+        if started_state and detached:
+            _save_state(started_state)
+            console.print(f"[dim]Runtime state saved: {STATE_FILE}[/dim]")
+            if "api" in started_state:
+                console.print(f"[dim]Local API started by CLI, PID={started_state['api']['pid']}, logs={started_state['api']['log']}[/dim]")
+            if "web" in started_state:
+                console.print(f"[dim]Local Web started by CLI, PID={started_state['web']['pid']}, logs={started_state['web']['log']}[/dim]")
+            console.print("[dim]Use 'owlscope ops stop' to stop CLI-managed processes.[/dim]")
+        elif started_state and not detached:
+            if "web" in started_state:
+                _stop_pid(int(started_state["web"]["pid"]), "web")
+            if "api" in started_state:
+                _stop_pid(int(started_state["api"]["pid"]), "api")
+            _clear_state()
+            console.print("[dim]Stopped CLI-started processes because --no-detached was set.[/dim]")
     except Exception as exc:
+        if started_state.get("web"):
+            _stop_pid(int(started_state["web"]["pid"]), "web")
+        if started_state.get("api"):
+            _stop_pid(int(started_state["api"]["pid"]), "api")
+        _clear_state()
         console.print(f"[yellow]Local mode failed: {exc}[/yellow]")
         if not fallback_docker:
             raise typer.Exit(1)
@@ -237,6 +326,35 @@ def ops_deploy(
         console.print("[green]Fallback docker deploy completed.[/green]")
 
 
+@ops_app.command("stop")
+def ops_stop() -> None:
+    """Stop API/Web processes that were started by `owlscope ops deploy`."""
+    state = _load_state()
+    if not state:
+        console.print("[yellow]No CLI-managed runtime state found.[/yellow]")
+        return
+
+    stopped_any = False
+
+    web = state.get("web")
+    if isinstance(web, dict) and "pid" in web:
+        pid = int(web["pid"])
+        if _stop_pid(pid, "web"):
+            console.print(f"[green]Stopped web process (pid={pid}).[/green]")
+            stopped_any = True
+
+    api = state.get("api")
+    if isinstance(api, dict) and "pid" in api:
+        pid = int(api["pid"])
+        if _stop_pid(pid, "api"):
+            console.print(f"[green]Stopped api process (pid={pid}).[/green]")
+            stopped_any = True
+
+    _clear_state()
+    if not stopped_any:
+        console.print("[yellow]State found, but managed processes were already stopped.[/yellow]")
+
+
 @app.command()
 def search(
     query: str = typer.Argument(..., help="Natural language search query"),
diff --git a/docs/deployment.md b/docs/deployment.md
index b67d5b4..b88061d 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -19,6 +19,8 @@ This runbook covers a safe baseline deployment for Owlscope.
   - `owlscope ops deploy --mode local`
 - CLI launch with frontend validation:
   - `owlscope ops deploy --mode local --with-web`
+- Ephemeral run (auto-stop after checks):
+  - `owlscope ops deploy --mode local --with-web --no-detached`
 - Start services (production profile with override):
   - `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build`
 - CLI docker backup path:
@@ -35,6 +37,8 @@ This runbook covers a safe baseline deployment for Owlscope.
   - `bash scripts/post_deploy_check.sh`
   - `owlscope ops check`
   - `owlscope ops check --with-web`
+- Stop CLI-managed local processes:
+  - `owlscope ops stop`
 - Rate-limit headers:
   - `bash scripts/check_rate_limit.sh`
 - Core smoke APIs:
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index dc06186..2693cbd 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -94,8 +94,10 @@ CLI-first alternative (direct mode first, docker backup optional):
 owlscope ops preflight
 owlscope ops deploy --mode local
 owlscope ops deploy --mode local --with-web
+owlscope ops deploy --mode local --with-web --no-detached
 # backup path: owlscope ops deploy --mode docker
 owlscope ops check --with-web
+owlscope ops stop
 ```
 
 ## Data Notes

From f9ab477dabae98f122d32a727d98ac6334684e0a Mon Sep 17 00:00:00 2001
From: JT Wei <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 11:23:47 +0800
Subject: [PATCH 16/17] feat(web): add Chinese pages and premium light theme

---
 README.md                             |  8 +++
 README.zh-CN.md                       |  8 +++
 web/src/app/globals.css               | 24 ++++----
 web/src/app/page.tsx                  | 26 ++++----
 web/src/app/zh/chat/page.tsx          |  1 +
 web/src/app/zh/compare/page.tsx       |  1 +
 web/src/app/zh/idea/page.tsx          |  1 +
 web/src/app/zh/page.tsx               | 85 +++++++++++++++++++++++++++
 web/src/app/zh/project/[id]/page.tsx  |  1 +
 web/src/app/zh/stack/page.tsx         |  1 +
 web/src/components/navbar.tsx         | 64 ++++++++++++++++----
 web/src/components/search-bar.tsx     | 25 +++++---
 web/src/components/search-results.tsx | 22 +++----
 13 files changed, 210 insertions(+), 57 deletions(-)
 create mode 100644 web/src/app/zh/chat/page.tsx
 create mode 100644 web/src/app/zh/compare/page.tsx
 create mode 100644 web/src/app/zh/idea/page.tsx
 create mode 100644 web/src/app/zh/page.tsx
 create mode 100644 web/src/app/zh/project/[id]/page.tsx
 create mode 100644 web/src/app/zh/stack/page.tsx

diff --git a/README.md b/README.md
index 0e7bcaf..397c9a3 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,14 @@
 ```
 
   </p>
+  <p align="center">
+    <img alt="Python" src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" />
+    <img alt="FastAPI" src="https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white" />
+    <img alt="Next.js" src="https://img.shields.io/badge/Next.js-111111?style=for-the-badge&logo=nextdotjs&logoColor=white" />
+    <img alt="PostgreSQL" src="https://img.shields.io/badge/PostgreSQL-336791?style=for-the-badge&logo=postgresql&logoColor=white" />
+    <img alt="Redis" src="https://img.shields.io/badge/Redis-DC382D?style=for-the-badge&logo=redis&logoColor=white" />
+    <img alt="Qdrant" src="https://img.shields.io/badge/Qdrant-6A4CFF?style=for-the-badge" />
+  </p>
   <p align="center">
     <strong>Open-source intelligence engine for discovering, evaluating, and adopting open-source libraries, frameworks, and agent skills.</strong>
   </p>
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 5bac98d..7e675bd 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -13,6 +13,14 @@
 ```
 
   </p>
+  <p align="center">
+    <img alt="Python" src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" />
+    <img alt="FastAPI" src="https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white" />
+    <img alt="Next.js" src="https://img.shields.io/badge/Next.js-111111?style=for-the-badge&logo=nextdotjs&logoColor=white" />
+    <img alt="PostgreSQL" src="https://img.shields.io/badge/PostgreSQL-336791?style=for-the-badge&logo=postgresql&logoColor=white" />
+    <img alt="Redis" src="https://img.shields.io/badge/Redis-DC382D?style=for-the-badge&logo=redis&logoColor=white" />
+    <img alt="Qdrant" src="https://img.shields.io/badge/Qdrant-6A4CFF?style=for-the-badge" />
+  </p>
   <p align="center">
     <strong>开源情报引擎：帮助开发者与 AI Agent 检索、评估、推荐开源项目与 Agent Skills，并在立项阶段避免重复造轮子。</strong>
   </p>
diff --git a/web/src/app/globals.css b/web/src/app/globals.css
index 2d24ac2..47cde86 100644
--- a/web/src/app/globals.css
+++ b/web/src/app/globals.css
@@ -2,20 +2,24 @@
 @tailwind components;
 @tailwind utilities;
 
-:root {
-  --foreground: #171717;
-  --background: #ffffff;
-}
+@import url("https://fonts.googleapis.com/css2?family=Manrope:wght@400;600;700;800&family=Fraunces:opsz,wght@9..144,600&display=swap");
 
-@media (prefers-color-scheme: dark) {
-  :root {
-    --foreground: #ededed;
-    --background: #0a0a0a;
-  }
+:root {
+  --foreground: #382611;
+  --background: #fffaf3;
 }
 
 body {
   color: var(--foreground);
   background: var(--background);
-  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  font-family: "Manrope", "Segoe UI", sans-serif;
+  background-image:
+    radial-gradient(circle at 16% 8%, #f5e8d2 0%, transparent 35%),
+    radial-gradient(circle at 85% 2%, #f6ecd9 0%, transparent 28%);
+}
+
+h1,
+h2,
+h3 {
+  font-family: "Fraunces", Georgia, serif;
 }
diff --git a/web/src/app/page.tsx b/web/src/app/page.tsx
index 4fec189..8620025 100644
--- a/web/src/app/page.tsx
+++ b/web/src/app/page.tsx
@@ -28,56 +28,52 @@ export default function Home() {
   };
 
   return (
-    <main className="min-h-screen flex flex-col items-center px-4 py-16">
-      {/* Hero */}
-      <div className="text-center mb-12 max-w-2xl">
-        <h1 className="text-5xl font-bold mb-4">
-          🦉 <span className="text-owl-600">Owlscope</span>
+    <main className="min-h-screen flex flex-col items-center px-4 py-16 bg-[radial-gradient(circle_at_20%_10%,#f8f1e4_0,#fffaf1_45%,#fffefc_100%)]">
+      <div className="text-center mb-12 max-w-3xl p-10 rounded-3xl border border-[#eadbc1] bg-white/80 shadow-[0_24px_60px_rgba(154,118,73,0.12)]">
+        <h1 className="text-5xl font-bold mb-4 tracking-tight">
+          🦉 <span className="text-[#7f5f37]">Owlscope</span>
         </h1>
-        <p className="text-lg text-gray-600 dark:text-gray-400">
+        <p className="text-lg text-[#6e5b43]">
           Deep search, evaluation & recommendation for open-source projects,
           libraries, and Agent Skills.
         </p>
       </div>
 
-      {/* Search */}
       <SearchBar onSearch={handleSearch} loading={loading} />
 
-      {/* Quick Actions */}
-      <div className="flex gap-3 mt-6 text-sm text-gray-500">
+      <div className="flex flex-wrap justify-center gap-3 mt-6 text-sm text-[#7f6a4f]">
         <button
           onClick={() => handleSearch("popular open source projects")}
-          className="px-3 py-1 rounded-full border hover:bg-gray-50 dark:hover:bg-gray-800 transition"
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
         >
           🔍 Search Projects
         </button>
         <button
           onClick={() => router.push("/compare")}
-          className="px-3 py-1 rounded-full border hover:bg-gray-50 dark:hover:bg-gray-800 transition"
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
         >
           📊 Compare
         </button>
         <button
           onClick={() => router.push("/idea")}
-          className="px-3 py-1 rounded-full border hover:bg-gray-50 dark:hover:bg-gray-800 transition"
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
         >
           💡 Idea Check
         </button>
         <button
           onClick={() => router.push("/stack")}
-          className="px-3 py-1 rounded-full border hover:bg-gray-50 dark:hover:bg-gray-800 transition"
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
         >
           🧩 Tech Stack
         </button>
         <button
           onClick={() => router.push("/chat")}
-          className="px-3 py-1 rounded-full border hover:bg-gray-50 dark:hover:bg-gray-800 transition"
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
         >
           💬 Chat
         </button>
       </div>
 
-      {/* Results */}
       <SearchResults results={results} loading={loading} />
     </main>
   );
diff --git a/web/src/app/zh/chat/page.tsx b/web/src/app/zh/chat/page.tsx
new file mode 100644
index 0000000..168487a
--- /dev/null
+++ b/web/src/app/zh/chat/page.tsx
@@ -0,0 +1 @@
+export { default } from "../../chat/page";
diff --git a/web/src/app/zh/compare/page.tsx b/web/src/app/zh/compare/page.tsx
new file mode 100644
index 0000000..815de86
--- /dev/null
+++ b/web/src/app/zh/compare/page.tsx
@@ -0,0 +1 @@
+export { default } from "../../compare/page";
diff --git a/web/src/app/zh/idea/page.tsx b/web/src/app/zh/idea/page.tsx
new file mode 100644
index 0000000..f8806fb
--- /dev/null
+++ b/web/src/app/zh/idea/page.tsx
@@ -0,0 +1 @@
+export { default } from "../../idea/page";
diff --git a/web/src/app/zh/page.tsx b/web/src/app/zh/page.tsx
new file mode 100644
index 0000000..894e1ae
--- /dev/null
+++ b/web/src/app/zh/page.tsx
@@ -0,0 +1,85 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { SearchBar } from "@/components/search-bar";
+import { SearchResults } from "@/components/search-results";
+
+export default function HomeZh() {
+  const [results, setResults] = useState<any[]>([]);
+  const [loading, setLoading] = useState(false);
+  const router = useRouter();
+
+  const handleSearch = async (query: string) => {
+    setLoading(true);
+    try {
+      const res = await fetch("/api/v1/search", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ query, limit: 20 }),
+      });
+      const data = await res.json();
+      setResults(data.recommendations || []);
+    } catch {
+      setResults([]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <main className="min-h-screen flex flex-col items-center px-4 py-16 bg-[radial-gradient(circle_at_20%_10%,#f8f1e4_0,#fffaf1_45%,#fffefc_100%)]">
+      <div className="text-center mb-12 max-w-3xl p-10 rounded-3xl border border-[#eadbc1] bg-white/80 shadow-[0_24px_60px_rgba(154,118,73,0.12)]">
+        <h1 className="text-5xl font-bold mb-4 tracking-tight">
+          🦉 <span className="text-[#7f5f37]">Owlscope</span>
+        </h1>
+        <p className="text-lg text-[#6e5b43]">
+          面向开发者与 AI Agent 的开源情报引擎，帮助你快速检索、评估与选择开源方案。
+        </p>
+      </div>
+
+      <SearchBar
+        onSearch={handleSearch}
+        loading={loading}
+        placeholder="描述你的需求，例如：支持 HTTP/2 的 Python 异步 HTTP 客户端"
+        searchLabel="开始搜索"
+        loadingLabel="搜索中..."
+      />
+
+      <div className="flex flex-wrap justify-center gap-3 mt-6 text-sm text-[#7f6a4f]">
+        <button
+          onClick={() => handleSearch("热门开源项目")}
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
+        >
+          🔍 搜索项目
+        </button>
+        <button
+          onClick={() => router.push("/zh/compare")}
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
+        >
+          📊 对比
+        </button>
+        <button
+          onClick={() => router.push("/zh/idea")}
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
+        >
+          💡 想法验证
+        </button>
+        <button
+          onClick={() => router.push("/zh/stack")}
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
+        >
+          🧩 技术栈建议
+        </button>
+        <button
+          onClick={() => router.push("/zh/chat")}
+          className="px-3 py-1 rounded-full border border-[#e7d7bc] bg-white hover:bg-[#fbf1df] transition"
+        >
+          💬 对话
+        </button>
+      </div>
+
+      <SearchResults results={results} loading={loading} localePrefix="/zh" />
+    </main>
+  );
+}
diff --git a/web/src/app/zh/project/[id]/page.tsx b/web/src/app/zh/project/[id]/page.tsx
new file mode 100644
index 0000000..393f97e
--- /dev/null
+++ b/web/src/app/zh/project/[id]/page.tsx
@@ -0,0 +1 @@
+export { default } from "../../../project/[id]/page";
diff --git a/web/src/app/zh/stack/page.tsx b/web/src/app/zh/stack/page.tsx
new file mode 100644
index 0000000..574677a
--- /dev/null
+++ b/web/src/app/zh/stack/page.tsx
@@ -0,0 +1 @@
+export { default } from "../../stack/page";
diff --git a/web/src/components/navbar.tsx b/web/src/components/navbar.tsx
index 5d7cf43..1070059 100644
--- a/web/src/components/navbar.tsx
+++ b/web/src/components/navbar.tsx
@@ -13,28 +13,66 @@ const NAV_ITEMS = [
 
 export function Navbar() {
   const pathname = usePathname();
+  const isZh = pathname === "/zh" || pathname.startsWith("/zh/");
+  const localPath = isZh ? pathname.replace(/^\/zh/, "") || "/" : pathname;
+  const enHref = localPath;
+  const zhHref = localPath === "/" ? "/zh" : `/zh${localPath}`;
+
+  const navItems = isZh
+    ? [
+        { href: "/zh", label: "搜索", icon: "🔍" },
+        { href: "/zh/idea", label: "想法验证", icon: "💡" },
+        { href: "/zh/chat", label: "对话", icon: "💬" },
+        { href: "/zh/compare", label: "对比", icon: "⚖️" },
+        { href: "/zh/stack", label: "技术栈", icon: "🧩" },
+      ]
+    : NAV_ITEMS;
 
   return (
-    <nav className="border-b border-gray-200 dark:border-gray-800 bg-white/80 dark:bg-gray-950/80 backdrop-blur-sm sticky top-0 z-50">
-      <div className="max-w-6xl mx-auto px-4 flex items-center justify-between h-14">
-        <Link href="/" className="flex items-center gap-2 font-bold text-lg">
+    <nav className="border-b border-[#e8dcc6] bg-[#fffbf5]/90 backdrop-blur-md sticky top-0 z-50 shadow-[0_8px_24px_rgba(120,92,56,0.08)]">
+      <div className="max-w-6xl mx-auto px-4 flex items-center justify-between h-16">
+        <Link href={isZh ? "/zh" : "/"} className="flex items-center gap-2 font-bold text-lg tracking-tight">
           <span>🦉</span>
-          <span className="text-owl-600">Owlscope</span>
+          <span className="text-[#7f5f37]">Owlscope</span>
         </Link>
-        <div className="flex items-center gap-1">
-          {NAV_ITEMS.map((item) => (
+        <div className="flex items-center gap-2">
+          <div className="hidden md:flex items-center gap-1">
+            {navItems.map((item) => (
+              <Link
+                key={item.href}
+                href={item.href}
+                className={`px-3 py-1.5 rounded-lg text-sm transition-colors ${
+                  pathname === item.href
+                    ? "bg-[#efe2cc] text-[#6f4b1f]"
+                    : "text-[#7b674d] hover:bg-[#f6eddc]"
+                }`}
+              >
+                {item.icon} {item.label}
+              </Link>
+            ))}
+          </div>
+          <div className="flex items-center rounded-full border border-[#e7d7bd] bg-white/80 p-1">
+            <Link
+              href={enHref}
+              className={`px-3 py-1.5 rounded-lg text-sm transition-colors ${
+                !isZh
+                  ? "bg-[#f3e6d0] text-[#6f4b1f]"
+                  : "text-[#7b674d] hover:bg-[#f8efdf]"
+              }`}
+            >
+              EN
+            </Link>
             <Link
-              key={item.href}
-              href={item.href}
+              href={zhHref}
               className={`px-3 py-1.5 rounded-lg text-sm transition-colors ${
-                pathname === item.href
-                  ? "bg-owl-50 text-owl-700 dark:bg-owl-900 dark:text-owl-100"
-                  : "text-gray-600 hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-gray-800"
+                isZh
+                  ? "bg-[#f3e6d0] text-[#6f4b1f]"
+                  : "text-[#7b674d] hover:bg-[#f8efdf]"
               }`}
             >
-              {item.icon} {item.label}
+              中文
             </Link>
-          ))}
+          </div>
         </div>
       </div>
     </nav>
diff --git a/web/src/components/search-bar.tsx b/web/src/components/search-bar.tsx
index c4636eb..9c6a6a0 100644
--- a/web/src/components/search-bar.tsx
+++ b/web/src/components/search-bar.tsx
@@ -5,9 +5,18 @@ import { useState, type FormEvent } from "react";
 interface SearchBarProps {
   onSearch: (query: string) => void;
   loading: boolean;
+  placeholder?: string;
+  searchLabel?: string;
+  loadingLabel?: string;
 }
 
-export function SearchBar({ onSearch, loading }: SearchBarProps) {
+export function SearchBar({
+  onSearch,
+  loading,
+  placeholder = "Describe what you need... e.g., 'Python async HTTP client with HTTP/2'",
+  searchLabel = "Search",
+  loadingLabel = "Searching...",
+}: SearchBarProps) {
   const [query, setQuery] = useState("");
 
   const handleSubmit = (e: FormEvent) => {
@@ -24,10 +33,10 @@ export function SearchBar({ onSearch, loading }: SearchBarProps) {
           type="text"
           value={query}
           onChange={(e) => setQuery(e.target.value)}
-          placeholder="Describe what you need... e.g., 'Python async HTTP client with HTTP/2'"
-          className="w-full px-6 py-4 text-lg border-2 border-gray-200 rounded-2xl 
-                     focus:border-owl-500 focus:outline-none
-                     dark:bg-gray-900 dark:border-gray-700 dark:focus:border-owl-500
+          placeholder={placeholder}
+          className="w-full px-6 py-4 text-lg border-2 border-[#eadcc4] rounded-2xl 
+                     focus:border-[#c89a5d] focus:outline-none bg-white/95 text-[#402b0f]
+                     shadow-[0_18px_40px_rgba(160,120,78,0.10)]
                      transition-colors"
           disabled={loading}
         />
@@ -35,11 +44,11 @@ export function SearchBar({ onSearch, loading }: SearchBarProps) {
           type="submit"
           disabled={loading || !query.trim()}
           className="absolute right-3 top-1/2 -translate-y-1/2 
-                     px-5 py-2 bg-owl-600 text-white rounded-xl
-                     hover:bg-owl-700 disabled:opacity-50
+                     px-5 py-2 bg-[#8f6737] text-white rounded-xl
+                     hover:bg-[#7d582e] disabled:opacity-50
                      transition-colors"
         >
-          {loading ? "Searching..." : "Search"}
+          {loading ? loadingLabel : searchLabel}
         </button>
       </div>
     </form>
diff --git a/web/src/components/search-results.tsx b/web/src/components/search-results.tsx
index b2de7a3..fff6899 100644
--- a/web/src/components/search-results.tsx
+++ b/web/src/components/search-results.tsx
@@ -3,12 +3,13 @@ import Link from "next/link";
 interface SearchResultsProps {
   results: any[];
   loading: boolean;
+  localePrefix?: string;
 }
 
-export function SearchResults({ results, loading }: SearchResultsProps) {
+export function SearchResults({ results, loading, localePrefix = "" }: SearchResultsProps) {
   if (loading) {
     return (
-      <div className="mt-12 text-center text-gray-500">
+      <div className="mt-12 text-center text-[#8b7659]">
         <div className="animate-pulse">Analyzing projects...</div>
       </div>
     );
@@ -27,34 +28,33 @@ export function SearchResults({ results, loading }: SearchResultsProps) {
         return (
           <Link
             key={i}
-            href={`/project/${encodedId}`}
-            className="block p-5 border rounded-xl hover:shadow-md transition-shadow
-                       dark:border-gray-700"
+            href={`${localePrefix}/project/${encodedId}`}
+            className="block p-5 border border-[#eadac0] rounded-2xl bg-white/90 hover:shadow-[0_20px_42px_rgba(160,120,78,0.14)] transition-shadow"
           >
             <div className="flex items-center justify-between mb-2">
               <h3 className="text-xl font-semibold">
-                <span className="text-gray-400 mr-2">#{item.rank}</span>
+                <span className="text-[#bca487] mr-2">#{item.rank}</span>
                 {item.project}
               </h3>
-              <span className="text-sm px-3 py-1 bg-owl-50 text-owl-700 rounded-full dark:bg-owl-900 dark:text-owl-100">
+              <span className="text-sm px-3 py-1 bg-[#f3e4cc] text-[#714d21] rounded-full">
                 Score: {item.score?.toFixed(1)}
               </span>
             </div>
-            <p className="text-gray-600 dark:text-gray-400 mb-2">
+            <p className="text-[#715d43] mb-2">
               {item.match_reason}
             </p>
             <div className="flex items-center gap-3 text-sm">
               {item.resource_type && (
-                <span className="px-2 py-0.5 bg-gray-100 dark:bg-gray-800 rounded text-xs">
+                <span className="px-2 py-0.5 bg-[#f6eddd] rounded text-xs text-[#6f5a3e]">
                   {item.resource_type}
                 </span>
               )}
               {item.source && (
-                <span className="text-gray-400 text-xs">{item.source}</span>
+                <span className="text-[#a38d71] text-xs">{item.source}</span>
               )}
             </div>
             {item.beginner_summary && (
-              <p className="text-sm text-gray-500 italic mt-2">
+              <p className="text-sm text-[#80684a] italic mt-2">
                 💡 {item.beginner_summary}
               </p>
             )}

From a90894490af637da6d161cd41d327e5dabf9709a Mon Sep 17 00:00:00 2001
From: Your Name <weijt_pro@192.168.1.15>
Date: Mon, 6 Apr 2026 11:52:03 +0800
Subject: [PATCH 17/17] fix(ci): remove hard dependency on local virtualenv

---
 scripts/release_check.sh           | 8 +++++++-
 scripts/run_integration_compare.sh | 6 +++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/scripts/release_check.sh b/scripts/release_check.sh
index 15088aa..a841a4d 100755
--- a/scripts/release_check.sh
+++ b/scripts/release_check.sh
@@ -13,7 +13,13 @@ echo "[1/6] Validating deployment environment..."
 python scripts/validate_env.py --mode dev
 
 echo "[2/6] Running backend tests..."
-source .venv/bin/activate
+if [[ -f ".venv/bin/activate" ]]; then
+  # Local development path
+  source .venv/bin/activate
+else
+  # CI path typically installs deps into the runner Python environment
+  echo "[release-check] .venv not found, using system Python environment"
+fi
 pytest -q -m "not integration"
 
 if [[ "$RUN_INTEGRATION" == "1" ]]; then
diff --git a/scripts/run_integration_compare.sh b/scripts/run_integration_compare.sh
index fad2593..a43f84b 100755
--- a/scripts/run_integration_compare.sh
+++ b/scripts/run_integration_compare.sh
@@ -11,7 +11,11 @@ if ! docker compose up -d postgres redis; then
 fi
 
 echo "[integration] Running black-box compare integration test..."
-source .venv/bin/activate
+if [[ -f ".venv/bin/activate" ]]; then
+	source .venv/bin/activate
+else
+	echo "[integration] .venv not found, using system Python environment"
+fi
 export OWLSCOPE_RUN_INTEGRATION=1
 pytest -q -m integration tests/integration/test_compare_blackbox.py