# Investibook v0.2

> Released: 2026-03-12
> Tag: investibook/v0.2

## Overview

Investibook v0.2 builds on the v0.1 production foundation with six major themes: **Nutshell Skills integration** (bringing TiDB Cloud's internal knowledge base into Investibook's agent), **CLI distribution & release automation** (cross-platform binaries, auto-update, one-click install, documented release workflow), **MCP & workspace configuration enhancements** (workspace-scoped env vars, Grafana skill overhaul, Jira MCP), **Jira Issue source unification** (all O11Y/TCOC/TCID ticket types under one model), **observability telemetry** (OpenCode plugin + admin stats dashboard), and **UI & discovery improvements** (Ranking page, consistent labels, UI polish).

---

## New Features

### Nutshell Skills Integration

- **Nutshell-skills bundled into Investibook**: the TiDB Cloud ops team's `nutshell-skills` knowledge base (TiDB performance diagnosis docs, TiKV tuning decision trees, Clinic API guides, O11Y metrics, autoscaler dashboard, etc.) is now included directly in the repository and loaded into the OpenCode agent at runtime via `skills.paths` in each workspace's `opencode.json`. ([#194], [#198], [#199])
- **Skills sync infrastructure**: a `sync-skills.sh` script and CI job keep Investibook's local copy of nutshell-skills in sync with the upstream source while protecting workspace-specific overrides (e.g., the Grafana panel finder skill) from being clobbered. ([#220], [#221])
- **Workspace skill auto-configuration**: a new `SKILL_CLINIC_API_KEY` mechanism lets the backend auto-inject per-user API keys into `opencode.json` when a workspace is created, so skills that call Clinic APIs work without manual configuration. ([#214])
- **Grafana panel finder skill refactor**: the `grafana-panel-finder` skill was rewritten to be goal-oriented rather than keyword-based, producing more reliable panel selection for screenshot and diagnostics workflows. ([#207], [#221])
- **System prompt optimization**: the agent system prompt was tuned to reduce noise, improve diagnostic focus, and better handle the workspace context. ([#219])

### Workspace Environment Configuration

- **Workspace env var API** (`GET/PUT /api/workspace/{id}/env`): each workspace now has a `.env` file in its session directory, readable and writable via dedicated API endpoints. ([#213])
- **Auto-create `.env` on workspace creation**: `POST /api/workspaces` now immediately creates the workspace directory and a default `.env` file, avoiding configuration errors when the agent starts before setup is complete. ([#216])

### Jira Issue Source Unification

- **Unified `jira_issue` source type**: the former `alert` source type has been fully renamed and consolidated into `jira_issue` across the entire stack — backend API, CLI, and all frontend components. Users now add "Jira Issues" (not "Alerts") to their workspace. ([#236], [#237], [#238], [#249])
- **TCOC and TCID ticket support**: the source preparer now handles three Jira issue prefixes:
  - `O11Y-*` — Observability alerts (existing)
  - `TCOC-*` — TiDB Cloud Oncall tickets (raw alert JSON extraction, same as O11Y)
  - `TCID-*` — TiDB Cloud Service tickets (direct custom fields `customfield_10088` / `customfield_10086`)
  
  Each prefix routes to the correct extraction method automatically. ([#231], [#234])
- **UTF-8 issue metadata output**: issue metadata JSON (`issue_meta.json`) is now written with proper UTF-8 encoding, supporting CJK and other non-ASCII characters in Jira fields. ([#239])

### CLI: Distribution, Auto-Update & Release Automation

- **Cross-platform binary distribution via GitHub Actions** (`investibook/cli/v0.2`): `cli` is now built for `linux/amd64`, `linux/arm64`, `darwin/amd64`, and `darwin/arm64` and published to S3 on every tagged release via a GitHub Actions workflow. ([#206])
- **CLI auto-update** (`investibook/cli/v0.3`): every CLI invocation silently checks S3 for a newer binary (5 s timeout). If found, it atomically replaces itself and re-executes — transparent to the user. `INVESTIBOOK_SKIP_UPDATE=1` disables the check. `BuildTime = "0"` (dev builds) also disables it. ([#212], [#217])
- **One-click install script** (`cli/install.sh`): detects OS/arch, downloads the correct binary from S3, installs to `~/.local/bin/investibook`, and adds it to `PATH`. ([#222])
- **CLI release workflow documentation & automation** (`docs/CLI_RELEASE.md`): documented the two-mode release system — *linked release* (pushing `investibook/v*` auto-creates a matching `investibook/cli/v*` tag via GitHub API) and *standalone CLI release* (push `investibook/cli/v*` directly). CI now automatically creates the CLI tag from the main pipeline without requiring a PAT. ([#232])

### Time-Conversion Skill

- **`time-conversion` skill**: a new deterministic timestamp utility skill that converts between Unix timestamps (seconds, milliseconds, nanoseconds) and human-readable datetimes across timezones. The agent system prompt now instructs the agent to always use `time-conversion` instead of doing timezone math in its head, eliminating a common class of off-by-one errors in time-windowed queries. ([#241])

### Jira MCP Integration

- **Jira MCP server** (`aiops-mcp-demo/jira`): a dedicated Jira MCP server now ships inside Investibook with four tools — `jira_get_issue`, `jira_get_alert_info`, `jira_add_comment`, `jira_get_comments`. The server runs in stdio mode alongside other MCP connectors and is automatically configured when the `jira` connector is active in a workspace. The agent can now read and annotate Jira issues directly during diagnosis. ([#251])

### OpenCode Telemetry & Admin Stats Dashboard

- **`ya-opencode-telemetry` OpenCode plugin** (`agentkit/plugins/ya-opencode-telemetry`): a new OpenCode plugin that hooks into every tool call and logs call metadata (tool name, type, MCP server, session, duration, success) to a per-workspace SQLite file at `.opencode/statistics.db`. No changes to agent behavior; purely observational. ([#233])
- **Admin stats dashboard** (`/admin/stats`): a new admin-only page that aggregates tool usage across all workspaces (total calls, breakdown by type) and surfaces the top skills, MCP tools, and built-in tools by call count. Data is read from each workspace's `statistics.db` via the `GET /api/stats/summary` backend endpoint. ([#233])
- **Dockerfile plugin path fix**: corrected a missing plugin path in the Dockerfile so the telemetry plugin is correctly included in production images. ([#245])
- **Agentkit excluded from Next.js build**: `agentkit/` (a Bun/Node plugin) is now excluded from the Next.js build process to prevent build failures caused by incompatible module formats. ([#244])

### UI Improvements

- **Ranking page** (`/ranking`): a new discovery page that surfaces the most effective diagnostic tools and skills as a leaderboard. Sections include a weekly usage trend chart (stacked bar), a skill leaderboard by invocation count, a tool usage table, and "trending techniques" cards. Backed by mock data in this release; will connect to `statistics.db` in a future update. The app header also gains a "Rankings" navigation link. ([#243])
- **Consistent "Jira Issue" labeling**: all UI text that previously said "Alert" in the Sources panel and Insight Report header now reads "Jira Issue", consistent with the source type rename. ([#249])
- **Logo and icons** added to the application (backported to v0.1 release branch as well). ([#196], [#208])
- **Simplified workspace header**: removed clutter from the top bar, making the three-column layout cleaner. ([#225])
- **Header style polish**: final visual refinements to padding, typography, and button layout in the workspace header. ([#227])
- **Mobile settings fix**: corrected layout/overflow issues in the settings modal on small screens. ([#223])
- **API key copy button polish**: adjusted padding and label text on the Clinic API key copy button for better alignment. ([#242])

### DevOps & MCP Fixes

- **DevOps MCP fix**: resolved configuration issue preventing DevOps-related MCP tools from connecting. ([#205])
- **SSO environment setup order fix**: backend now runs `setup-env` before starting the SSO middleware to prevent Auth0 breakage during startup. ([#201])
- **Development backend hot-reload fix**: `uvicorn --reload` now works correctly in local dev without crashing on file changes. ([#228])

### Guardian Insight Report

- **Crash fix for `direct_cause` field**: the Guardian Insight Report component no longer crashes when the `direct_cause` field in `insight.json` is missing or malformed. ([#202])

### Knowledge Base

- **Remove regular row panels from PSC knowledge base** (follow-up to v0.1's collapsed-panel removal): additional noisy row-level panels are now excluded from the Grafana panel knowledge base. ([#195])
- **PSC metrics expanded to DM / Lightning / TiFlash / TiProxy**: the PSC (Performance Statistics Center) Grafana panel knowledge base now includes panels for Data Migration (DM), Lightning, TiFlash, and TiProxy components, enabling the agent to capture screenshots and reference metrics for these components during diagnosis. ([#229])
- **mdbook documentation** (`tools/mdbook/`): the `docs/` directory can now be compiled into a browsable HTML book using mdbook, making the design docs, backlog, and skills integration guides easier to navigate. ([#235])

### Production

- **Release branch CI**: GitHub Actions now builds and publishes Docker images for the `investibook/release-*` branches in addition to the main feature branch. ([#209], [#210])
- **Dev domain update**: development environment domain updated to the correct host. ([#197])

---

## Bug Fixes

| PR | Fix |
|----|-----|
| [#195] | Remove regular row panels from PSC Grafana knowledge base |
| [#198] | Replace broken nutshell-skills submodule with actual files |
| [#199] | Fix nutshell-skills build (missing `package.json` resolution) |
| [#201] | Fix SSO break caused by wrong env setup order |
| [#202] | Fix Guardian Insight Report crash on missing `direct_cause` field |
| [#205] | Fix DevOps MCP connectivity |
| [#216] | Auto-create `.env` file in `POST /api/workspaces` |
| [#217] | Fix CLI auto-upgrade race condition and version comparison logic |
| [#218] | Fix cluster ID extraction from alert metadata |
| [#219] | Optimize system prompt for more focused diagnostics |
| [#223] | Fix mobile settings modal overflow |
| [#228] | Fix backend hot-reload in development |
| [#237] | Complete alert → Jira Issue renaming in Studio components |
| [#239] | Fix UTF-8 encoding for issue metadata output |
| [#240] | Fix frontend rendering error |
| [#244] | Exclude agentkit from Next.js build to prevent build failures |
| [#245] | Fix missing plugin path in Dockerfile |
| [#249] | Update alert label to "Jira Issue" in SourcesPanel |
| [#250] | Fix opencode template skills list (prevent loading all skills by default) |

---

## What's Changed Since v0.1

| Area | v0.1 | v0.2 |
|------|------|------|
| Skills / Knowledge | None (bare agent) | Nutshell-skills bundled; auto-synced from upstream |
| Grafana skill | Basic keyword finder | Goal-oriented panel finder |
| Clinic API keys | Manual per-workspace setup | Auto-injected via `SKILL_CLINIC_API_KEY` |
| Workspace config | No per-workspace env API | `.env` API + auto-creation on workspace init |
| Jira issue types | O11Y alerts only | O11Y + TCOC (oncall) + TCID (service ticket) |
| Source type model | `alert` type | Unified `jira_issue` type across stack |
| CLI distribution | Single manual build | Cross-platform CI builds + S3 distribution |
| CLI updates | Manual re-download | Transparent auto-update on every invocation |
| CLI install | Manual binary copy | One-click `install.sh` |
| CLI release process | Ad-hoc | Documented linked + standalone workflows; auto-tagging in CI |
| Jira MCP | Not available | Jira MCP server with get/comment tools |
| Telemetry | No tool usage data | OpenCode plugin logs all tool calls to `statistics.db` |
| Admin visibility | None | Stats dashboard showing top tools/skills across all workspaces |
| Tool/skill discovery | None | Ranking page at `/ranking` |
| UI | Functional but raw | Logo, simplified header, ranking page, consistent Jira labels |
| PSC coverage | Core TiDB/TiKV panels | + DM, Lightning, TiFlash, TiProxy panels |
| Time handling | Manual by agent | `time-conversion` skill; agent always uses it |
| System prompt | Basic | Optimized and tuned |

---

## Contributors

@handlerww · @llt-sudo · @iguoyr · @Yujie-Xie · @nolouch