# Investibook v0.4

> Released: 2026-03-25
> Tag: `investibook/v0.4`

## Overview

Investibook v0.4 is a diagnosis-quality and platform-hardening release centered on 4 themes:
- **Evaluation pipeline hardening** — admin evaluation now sees `messages_v2` workspaces, runs as a background task, and produces correct per-day trend snapshots.
- **Starter/Essential serverless support** — Investibook closes the gap left in v0.3 by supporting TiDB Cloud Starter/Essential clusters across source preparation, prompt context, dashboard routing, and chat UI.
- **`tidb-clinic-diagnosis` overhaul** — the built-in diagnosis skill now uses a stricter decision tree, product-line-aware routing, and MCP → `clinic-api` fallback for missing metrics.
- **Skill Hub polish** — skill descriptions now render correctly from YAML front matter.

---

## New Features

### Evaluation & Admin Operations

- **`messages_v2`-aware evaluation scan** — the evaluation system now reads from `messages_v2_meta` first, with legacy `workspace_messages` as a fallback and deduplication. Workspaces created after the `messages_v2` migration are no longer skipped. ([#311])
- **Background evaluation execution** — `POST /api/admin/evaluations/run` now starts an async background task instead of blocking the request. The admin page stays responsive, large deployments avoid bulk message loading spikes, and a status endpoint supports progress polling. ([#317])
- **Correct daily trend snapshots** — evaluation trend charts now show averages for workspaces created on each specific day rather than cumulative averages over all earlier workspaces. ([#312])

### TiDB Cloud Starter/Essential Support

- **Starter/Essential diagnosis support across the stack** — Investibook now supports serverless TiDB Cloud clusters in the same diagnosis workflow: PSC knowledge bases and dashboard mappings add serverless coverage, routing rules distinguish Dedicated vs Premium vs Starter/Essential, and the chat UI exposes cluster-type-specific fields. ([#330])
- **Enriched cluster metadata for serverless clusters** — source preparation now fills `shoot_name`, `cloud_provider`, `region`, and derived `control_plane_info` for Starter/Essential clusters, giving Grafana URL generation and agent prompts the context they need. ([#330])
- **Automatic `keyspace_id` discovery** — source preparation now discovers `keyspace_id` from the metrics series API and stores it in `cluster_meta.json`, so TiDB metric queries on Starter/Essential clusters no longer require manual discovery during diagnosis. ([#332])

### Diagnosis Skills & Knowledge Base

- **`tidb-clinic-diagnosis` decision-tree rewrite** — the built-in diagnosis skill is no longer a linear checklist. It now enforces an infra-first decision tree (Node A → E), separates app vs infra metric strategies, adds PromQL template cleanup guidance, and requires explicit gate answers before the agent concludes a diagnosis. ([#333])
- **MCP → `clinic-api` metric fallback** — when Clinic MCP metric queries return empty data or errors, the agent is now instructed to retry the same PromQL through the `clinic-api` skill before giving up, reducing false "no data" paths in diagnosis. ([#329])
- **Synced nutshell knowledge and routing** — this release syncs the latest nutshell-skills updates into Investibook, including new or reorganized diagnosis and ops skills such as `tikv-memory`, `tikv-recovery`, `transaction-oncall-handbook`, and TiCDC / TiDB-X operation workflows. ([#333])

### CLI Release Workflow

- **Manual CLI release trigger** — the Investibook CLI release workflow now supports `workflow_dispatch`, making it possible to trigger a CLI release manually without waiting for a tag-driven pipeline. ([#315])

### Skill Management & Source Preparation

- **Skill description parsing fixed** — the backend now reads skill descriptions from YAML front matter in `SKILL.md` instead of showing the useless `---` first line in Skill Hub responses. ([#327])
- **Clinic auth fallback chain in source preparation** — source preparation now uses the same key resolution order as ACP: `SKILL_CLINIC_API_KEY` → `CLINIC_API_KEY` → `INVESTIBOOK_CLINIC_API_KEY`, avoiding 401s in environments where the settings key is not the Clinic API key. ([#331])

---

## Bug Fixes

| PR | Fix |
|----|-----|
| [#311] | Evaluation now scans `messages_v2` workspaces instead of missing newer workspaces |
| [#312] | Evaluation trend chart now shows per-day averages rather than cumulative averages |
| [#315] | Add `workflow_dispatch` trigger for manual CLI releases |
| [#317] | Run evaluations as a background task to prevent OOM and page blocking |
| [#327] | Fix skill description extraction from `SKILL.md` front matter |
| [#329] | Retry metric queries via `clinic-api` when MCP returns empty data or errors |
| [#330] | Add Starter / Essential serverless support and product-line-aware routing |
| [#331] | Use the correct Clinic API key fallback chain in `source_preparer` |
| [#332] | Auto-discover `keyspace_id` for Starter / Essential clusters |
| [#333] | Restructure `tidb-clinic-diagnosis` and sync upstream nutshell-skills |

---

## What's Changed Since v0.3

| Area | v0.3 | v0.4 |
|------|------|------|
| Evaluation execution | Initial evaluation system introduced | Async background execution with progress polling and lower memory pressure |
| Evaluation coverage | Could miss workspaces already migrated to `messages_v2` | Reads `messages_v2` first, with legacy fallback and deduplication |
| Evaluation trends | Daily chart used cumulative averages | Daily chart shows true per-day averages |
| TiDB-X support | Premium fully supported; Starter/Essential still pending | Starter/Essential supported across source prep, prompt routing, dashboards, and chat context |
| Serverless metadata | Partial cluster metadata | Adds `shoot_name`, `cloud_provider`, `region`, `control_plane_info`, and auto-discovered `keyspace_id` |
| Diagnosis workflow | First version of `tidb-clinic-diagnosis` | Decision-tree workflow with infra gates, routing rules, and MCP → `clinic-api` fallback |
| Skill Hub descriptions | Could show incorrect placeholder text | Parses YAML front matter and shows real descriptions |
| CLI release operations | Tag-driven release flow | Supports manual `workflow_dispatch` release trigger |

---

## Contributors

@llt-sudo · @handlerww · @kennytm