feat: ship batch idea export workflow, CLI-first deploy ops, and Chinese light-theme web experience

.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

.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

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>
@@ -99,7 +107,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 +129,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)
@@ -140,6 +148,24 @@ 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
+
+# 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
@@ -170,37 +196,103 @@ 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`
+
+Production launch commands:
+
+```bash
+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
+# include web checks: owlscope ops check --with-web
+# stop local managed processes: owlscope ops stop
+```
+
 ## API Reference
 
 ### REST API
 
 ```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://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://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://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
 # - decision_signals for explainability
 # - 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
+# - batch export endpoint supports markdown/json report output
 ```
 
-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