# Investibook Docs

A reference for architecture, configuration, features, and planning.

---

## Architecture & Design

| Doc | Description |
|-----|-------------|
| [Product Design](./specs/2026-02-27-design.md) | NotebookLM-style three-column layout (Sources / Chat / Studio) for TiDB Cloud alert investigation |
| [产品设计（中文）](./specs/2026-02-27-design.zh.md) | 产品设计文档中文版 |
| [Project Structure](./specs/2026-03-03-project-structure.md) | Key files and their roles in the project |
| [Alert Source Pipeline](./specs/2026-03-03-alert-source-pipeline.md) | Pipeline that fetches and enriches O11Y alerts and JSM tickets for workspace initialization |
| [Clinic Auth](./specs/2026-03-03-clinic-auth.md) | API key and cookie/CSRF token auth for the Clinic HTTP API |
| [Screenshot Integration](./specs/2026-03-03-screenshot-integration.md) | Auto-extracts cluster metadata so Grafana screenshots need no manual configuration |
| [CLI Design](./specs/2026-03-08-investibook-cli.md) | Design of `investibook-cli`, a thin terminal REST+SSE client for on-call engineers |
| [Entity Relationship Diagram](./specs/2026-03-11-entity-relationship-diagram.md) | Data model and entity relationships |
| [CLI Auto-Update Design](./specs/2026-03-11-cli-auto-update.md) | Transparent self-update mechanism — silently replaces the binary from S3 on every run |
| [Flexible Panels Design](./specs/2026-03-12-flexible-panels-design.md) | Flexible panel layout spec |
| [Ranking Page Design](./specs/2026-03-12-ranking-page.md) | Ranking page feature design |
| [messages_v2](./specs/2026-03-16-messages-v2.md) | Per-row chat history storage and message persistence contract |

---

## Configuration Guides

| Doc | Description |
|-----|-------------|
| [App Configuration](./guides/2026-03-03-config.md) | YAML files and `INVESTIBOOK_`-prefixed environment variables |
| [Auth0 SSO](./guides/2026-03-09-auth0-sso.md) | Google SSO restricted to `@pingcap.com` accounts via Auth0 |
| [Workspace Transfer Ownership](./guides/2026-04-17-workspace-transfer-owner.md) | Transfer workspace ownership between users |

---

## Evaluation

| Doc | Description |
|-----|-------------|
| [Evaluation Current Implementation（中文）](../evaluation/current-implementation.zh.md) | 当前 evaluation 实际实现总览，覆盖运行流程、formal registry、防信息暴露设计、judge 与判分系统 |
| [Evaluation Runtime](../evaluation/README.md) | Current evaluation CLI usage, runtime behavior, output locations, and environment requirements |
| [Regression Registry](../evaluation/regression/README.md) | Formal regression registry layout, case/suite contract, and authoring rules |
| [Judge Pipeline（中文）](../evaluation/judge-pipeline-explainer.zh.md) | 当前 judge 实现流程、bucket 划分、facts 提取与 verdict precedence |
| [Judge Pipeline](../evaluation/judge-pipeline-explainer.md) | English explainer for the current judge implementation |

---

## Research

| Doc | Description |
|-----|-------------|
| [Agent Runtime 对比（中文）](./research/2026-04-21-agent-runtime-comparison.zh.md) | 面向诊断系统比较 OpenCode、Claude Code、Codex 的定位、优缺点与选型建议 |
| [Diagnosis Knowledge Orchestration 研究（中文）](./research/2026-04-21-diagnosis-knowledge-orchestration.zh.md) | 诊断知识持续增长、按阶段投递、guard rail 和反馈闭环的研究方案 |
| [run9 API 参考与 Investibook 执行迁移评估（中文）](./research/2026-07-14-run9-api-and-investibook-runtime-migration.zh.md) | run9 box/exec/file/snap API 参考，以及将 Investibook agent 执行迁移到 run9 的适配范围、风险和阶段计划 |

---

## Operations

| Doc | Description |
|-----|-------------|
| [Troubleshooting](./troubleshooting.md) | Deployment, cluster access, logs, and workspace diagnostic session inspection |
| [CLI Release](./specs/2026-03-12-cli-release.md) | Release workflows and tag conventions (`investibook/v*`, `investibook/cli/v*`) |
| [TCOC Postmortem](./sops/tcoc-postmortem.md) | Standard postmortem template and process notes |
| [TCOC Postmortem（中文）](./sops/tcoc-postmortem.zh.md) | TCOC 复盘模板与流程说明 |

---

## Backlog & Planning

| Doc | Description |
|-----|-------------|
| [Alert Debugging Roadmap](./plans/2026-03-04-alert-debugging-roadmap.md) | Historical roadmap for autonomous end-to-end alert debugging（中文）|
| [Backlog](./plans/2026-03-04-backlog.md) | Development backlog organized by milestone and category |
| [Backlog（中文）](./plans/2026-03-08-backlog.zh.md) | 开发 Backlog（中文）|
| [Flexible Panels Implementation Plan](./plans/2026-03-12-flexible-panels-implementation-plan.md) | Implementation plan for flexible panel layout |
| [Active Capabilities 设计方案（中文）](./plans/2026-04-20-active-capabilities-design-plan.zh.md) | 讨论如何让用户理解哪些数据和能力已经接入 AI 分析回路 |
| [Diagnosis Knowledge Orchestration 设计（中文）](./plans/2026-05-06-diagnosis-knowledge-orchestration-code-architecture.zh.md) | 诊断知识编排的 Frame / Action / Guard / Evidence 实体模型、注入策略、阶段目标和风险边界 |
| [Diagnosis Knowledge Orchestration Phase 0 设计范围（中文）](./plans/2026-05-06-diagnosis-knowledge-orchestration-phase0-plan.zh.md) | Phase 0 的目标、实体边界、注入策略、scope、验收口径和后续 phase 边界 |
| [Prompt / Context / MCP 入口收敛设计（中文）](./plans/2026-05-06-prompt-context-mcp-consolidation-design.zh.md) | 梳理主 agent、workspace context、MCP activation、backend-only LLM prompts 的入口分层和收敛目标 |
| [TiDB 源码辅助诊断设计（中文）](./plans/2026-05-07-tidb-source-code-diagnosis-plan.zh.md) | 设计诊断中的按需源码分析能力，明确 Clinic component inventory、image tag 到 code ref 翻译规则和源码证据边界 |
| [分层诊断：信号打标、故障分类和专项 Skill 拆分设计（中文）](./plans/2026-05-21-layered-diagnosis-signal-classification-design.zh.md) | 设计分层诊断中的 SignalTag、FaultClass、专项 skill 拆分和 evaluation 分层评分点 |

---

## Fixes

| Doc | Description |
|-----|-------------|
| [Login Redirect](./fixes/2026-03-13-login-redirect.md) | Login redirection handling for Auth0 and session storage |