Translate design docs and migration comments to English

docs/PRD.md

@@ -1,70 +1,70 @@
 # Research Topic Agent PRD
 
-## 1. 产品目标
+## 1. Product goals
 
-面向科研人群提供一个 `选题前决策系统`，把“模糊兴趣”转为“可执行选题路径”。
+Give researchers a `pre-topic decision system` that turns a "vague interest" into an "actionable research path".
 
-核心目标：
-- 在 20 分钟内形成 3 条候选路径并给出推荐。
-- 每条推荐必须可追溯证据、可被人工复核、可被实验否证。
-- 对用户而言是“决策增强器”，不是“替代科研判断”的黑箱。
+Core goals:
+- Produce 3 candidate paths and a recommendation within 20 minutes.
+- Every recommendation must be traceable to evidence, reviewable by a human, and falsifiable by experiment.
+- For the user it is a "decision amplifier", not a black box that "replaces research judgment".
 
-## 2. 用户细分与 JTBD
+## 2. User segments and JTBD
 
-- 研一/博一：需要快速建立方向感，避免开题后大幅返工。
-- 课题组新人：需要在导师约束下快速定位可起步方向。
-- 独立研究者：需要资源受限下的高质量方向筛选。
+- First-year master's / PhD students: need a sense of direction fast, to avoid major rework after the proposal.
+- New lab members: need to find a direction they can start on quickly, within their advisor's constraints.
+- Independent researchers: need high-quality direction screening with limited resources.
 
 JTBD:
-- 当我只有兴趣和一些零散想法时，我想快速得到可比较的方向路径，以便我能在组会或开题前做出可辩护选择。
+- When I only have an interest and some scattered ideas, I want comparable direction paths quickly, so that I can make a defensible choice before a group meeting or my proposal defense.
 
-## 3. 范围收敛
+## 3. Scope
 
 ### In Scope
-- 研究兴趣输入与约束建模
-- 文献检索与证据池构建
-- 候选路径比较（新颖性/可行性/影响力/风险/证据）
-- 收敛推荐与 7 天行动计划
-- 高参与与低参与两种交互模式
+- Research interest input and constraint modeling
+- Literature retrieval and evidence pool construction
+- Candidate path comparison (novelty / feasibility / impact / risk / evidence)
+- Converged recommendation and a 7-day action plan
+- Two interaction modes: high involvement and low involvement
 
 ### Out of Scope
-- 论文全文写作
-- 长周期实验管理平台
-- 通用学术搜索引擎替代
+- Writing full papers
+- A long-running experiment management platform
+- Replacing general academic search engines
 
-## 4. 关键功能
+## 4. Key features
 
-1. **模式选择**
-   - 高参与：逐步人工确认门
-   - 低参与：自动跑完全流程，终局后纠偏
+1. **Mode selection**
+   - High involvement: human confirmation gates at each step
+   - Low involvement: runs the whole pipeline automatically; the user corrects course at the end
 
-2. **复杂度感知路由**
-   - 输入复杂度评估 -> 自动选择架构：
-   - 单 Agent / 工作流编排 / 多 Agent / RAG / 知识图谱
+2. **Complexity-aware routing**
+   - Assess input complexity -> automatically choose an architecture:
+   - Single agent / workflow orchestration / multi-agent / RAG / knowledge graph
 
-3. **证据治理**
-   - 来源分级：T1/T2/T3
-   - 引用模板标准化
-   - 冲突证据硬门（未解冲突不得自动终局）
+3. **Evidence governance**
+   - Source tiers: T1/T2/T3
+   - Standardized citation template
+   - Hard gate on conflicting evidence (no automatic final answer while conflicts are unresolved)
 
-4. **决策输出**
-   - 候选路径评分矩阵
-   - 推荐路径 + 备选路径 + 可证伪实验 + 止损条件
+4. **Decision output**
+   - Scoring matrix for candidate paths
+   - Recommended path + fallback paths + falsifiable experiments + stop-loss conditions
 
-## 5. 非功能性要求
+## 5. Non-functional requirements
 
-- 可用性：桌面优先，移动端可用
-- 性能：首屏 < 2s，关键交互 < 200ms（不含 LLM）
-- 可追溯：所有关键决策有 Evidence ID
-- 安全：最小化敏感数据上传，审计日志可回放
-- 可观测：产品与 AI 双指标均可观测
+- Usability: desktop first, usable on mobile
+- Performance: first screen < 2s, key interactions < 200ms (excluding LLM calls)
+- Traceability: every key decision has an Evidence ID
+- Security: minimize upload of sensitive data; audit logs can be replayed
+- Observability: both product and AI metrics are observable
 
-## 6. 北极星指标与守护指标
+## 6. North star and guardrail metrics
 
-北极星：
+North star:
 - `accepted_recommendation_within_24h`
 
-守护指标：
+Guardrail metrics:
 - Hallucination Incident Rate
-- 冲突检测召回率
-- 人工纠偏率（过低或过高都说明系统偏移）
+- Conflict detection recall
+- Human correction rate (too low or too high both indicate the system has drifted)

docs/SYSTEM_ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # System Architecture
 
-## 1. 总体架构
+## 1. Overall architecture
 
 ```text
 Web App (React SPA)
@@ -14,7 +14,7 @@ Web App (React SPA)
     -> PostHog Analytics / Audit Events
 ```
 
-生产扩展路径：
+Production scaling path:
 ```text
 Web App (React/Next)
     -> BFF Gateway
@@ -26,97 +26,97 @@ Web App (React/Next)
         -> Session Store / Analytics / Audit Log
 ```
 
-## 2. 架构路由策略
+## 2. Architecture routing strategy
 
-输入维度：
-- 问题复杂度
-- 风险等级（医疗/金融/法律等）
-- 是否强依赖跨文献关系图
+Input dimensions:
+- Problem complexity
+- Risk level (medical / finance / legal, etc.)
+- Whether the problem depends heavily on cross-paper relationship graphs
 
-路由结果：
+Routing outcomes:
 - `single_agent`
 - `workflow_orchestrator`
 - `multi_agent`
 - `rag_workflow`
 - `kg_orchestrated`
 
-## 3. 关键模块职责
+## 3. Key module responsibilities
 
 ### Pipeline Engine (`engine.ts`)
-- 拆分阶段任务：检索 → 梳理 → 比较 → 收敛
-- 管理 LLM 流式调用与 Mock 降级
-- 触发人工确认门（HIGH 模式）
-- 复杂度感知路由决策
+- Splits the work into stages: retrieve → map → compare → converge
+- Manages streaming LLM calls and the Mock fallback
+- Triggers human confirmation gates (HIGH mode)
+- Makes complexity-aware routing decisions
 
 ### LLM Client (`llm.ts`)
-- SSE 流式传输（OpenAI / Anthropic 双协议）
-- 输入净化（`sanitizeInput`）
-- 健壮 JSON 解析（三级降级 + 大小保护）
+- SSE streaming (OpenAI and Anthropic protocols)
+- Input sanitization (`sanitizeInput`)
+- Robust JSON parsing (three fallback levels + size guard)
 
 ### IndexedDB Storage (`lib/db.ts`)
-- `sessions` store：完整运行结果（含 AgentRunResult + TopicInput）
-- `iterations` store：迭代计划、日志、状态
-- 自动从 localStorage 迁移历史数据
+- `sessions` store: full run results (AgentRunResult + TopicInput)
+- `iterations` store: iteration plans, logs, status
+- Automatically migrates legacy data from localStorage
 
 ### Key Vault (`lib/keyVault.ts`)
-- 默认 sessionStorage（关闭标签页即清除）
-- 可选加密持久化：PBKDF2 密钥派生 → AES-GCM 加密 → localStorage
-- 登出时清除所有密钥数据
+- sessionStorage by default (cleared when the tab closes)
+- Optional encrypted persistence: PBKDF2 key derivation → AES-GCM encryption → localStorage
+- Clears all key data on sign-out
 
 ### Auth Module (`hooks/useAuth.ts`)
-- SHA-256 + 盐哈希密码（Web Crypto API）
-- localStorage 会话管理
-- 支持扩展集成 Clerk/Auth0
+- Passwords hashed with salted SHA-256 (Web Crypto API)
+- Session management in localStorage
+- Can be extended to integrate Clerk/Auth0
 
 ### Subscription (`components/Paywall.tsx`)
-- Free / Pro 双层订阅
-- 导出功能按 Plan 限制
-- localStorage 持久化（可扩展至后端校验）
-
-## 4. 数据模型与存储
-
-当前实现（纯前端）：
-- 会话记录：IndexedDB `sessions` store
-- 迭代计划：IndexedDB `iterations` store
-- 用户设置：localStorage `copilot_settings`
-- API Key：sessionStorage / 加密 localStorage
-- 用户认证：localStorage `copilot_users` + `copilot_session`
-
-生产扩展：
-- 会话存储：`topic_sessions`（PostgreSQL）
-- 证据存储：`evidence_items`
-- 评分存储：`candidate_paths`
-- 审计日志：`decision_events`
-- 向量检索：`pgvector`
-- 图结构：`neo4j`（或 Postgres graph projection）
-
-## 5. 可靠性与可观测
-
-- 产品埋点：PostHog（页面浏览、运行启动/完成/失败、模式选择、路径采纳等）
-- Pipeline 阶段级进度反馈
-- 失败降级：LLM 不可用时自动回退 Mock 数据
-- 未配置 API Key 时弹窗守卫（配置 / Mock 预览 / 取消）
-
-生产扩展：
-- 任务级 tracing：OpenTelemetry
-- 失败重试：按阶段幂等重试
-- 告警策略
-
-## 6. 安全与隐私
-
-- API Key：AES-GCM 加密存储（PBKDF2 派生，100k 迭代）
-- 密码：SHA-256 + 盐哈希（Web Crypto API）
-- LLM 输入：控制字符净化
-- JSON 解析：500KB 大小上限
-- 设置校验：`validateSettings` 防注入
-- 默认结构化摘要输入，不强制上传原文
-- 登出时清除所有密钥与会话数据
-
-## 7. 全链路国际化
-
-- **Engine 函数**：`createDefaultInput`、`assessComplexity`、`decideArchitecture`、`buildEvidence`、`buildCandidates`、`buildRecommendation`、`buildSourcePolicy`、`buildEvaluationPlan` 等均接受 `locale` 参数，保证数据层与 UI 语言一致。
-- **LLM User Prompt**：用户侧提示为完整双语模板（中文 / 英文），字段标签、示例与要求说明随 `locale` 切换。
-- **LLM System Prompt**：系统提示中强制响应语言，例如 `IMPORTANT: You MUST respond entirely in English` 或 `IMPORTANT: You MUST respond entirely in Chinese`。
-- **Mock 数据**：Mock 流式输出与静态占位内容按 `locale` 解析，与真实 LLM 路径行为对齐。
-- **导出报告**：`ShareExport` 等导出路径根据 `locale` 切换表头、标签与文案。
-- **正则与关键词**：`engine.ts` 中用于领域检测、路由等用途的正则同时覆盖中英文关键词（如 `医疗|medical`），避免仅匹配单一语言导致路由偏差。
+- Two tiers: Free / Pro
+- Export features gated by plan
+- Persisted in localStorage (can be extended to server-side checks)
+
+## 4. Data model and storage
+
+Current implementation (frontend only):
+- Session records: IndexedDB `sessions` store
+- Iteration plans: IndexedDB `iterations` store
+- User settings: localStorage `copilot_settings`
+- API keys: sessionStorage / encrypted localStorage
+- User auth: localStorage `copilot_users` + `copilot_session`
+
+Production scaling:
+- Session storage: `topic_sessions` (PostgreSQL)
+- Evidence storage: `evidence_items`
+- Score storage: `candidate_paths`
+- Audit log: `decision_events`
+- Vector search: `pgvector`
+- Graph structure: `neo4j` (or a Postgres graph projection)
+
+## 5. Reliability and observability
+
+- Product analytics: PostHog (page views, run start/complete/fail, mode selection, path adoption, etc.)
+- Per-stage pipeline progress feedback
+- Failure fallback: automatically falls back to Mock data when the LLM is unavailable
+- Guard dialog when no API key is configured (configure / Mock preview / cancel)
+
+Production scaling:
+- Task-level tracing: OpenTelemetry
+- Failure retries: idempotent per-stage retries
+- Alerting policy
+
+## 6. Security and privacy
+
+- API keys: stored with AES-GCM encryption (PBKDF2-derived, 100k iterations)
+- Passwords: salted SHA-256 hashes (Web Crypto API)
+- LLM input: control characters stripped
+- JSON parsing: 500KB size limit
+- Settings validation: `validateSettings` guards against injection
+- Structured summaries are the default input; uploading full source text is never required
+- Clears all keys and session data on sign-out
+
+## 7. End-to-end internationalization
+
+- **Engine functions**: `createDefaultInput`, `assessComplexity`, `decideArchitecture`, `buildEvidence`, `buildCandidates`, `buildRecommendation`, `buildSourcePolicy`, `buildEvaluationPlan`, etc. all take a `locale` parameter so the data layer matches the UI language.
+- **LLM user prompt**: the user-side prompt is a full bilingual template (Chinese / English); field labels, examples and requirements switch with `locale`.
+- **LLM system prompt**: the system prompt enforces the response language, e.g. `IMPORTANT: You MUST respond entirely in English` or `IMPORTANT: You MUST respond entirely in Chinese`.
+- **Mock data**: Mock streaming output and static placeholder content are resolved by `locale`, matching the behavior of the real LLM path.
+- **Exported reports**: `ShareExport` and other export paths switch table headers, labels and copy based on `locale`.
+- **Regexes and keywords**: the regexes in `engine.ts` used for domain detection, routing, etc. cover both Chinese and English keywords (e.g. `医疗|medical`, where 医疗 means "medical"), so routing is not skewed by matching only one language.