# Upgrading to v0.10.0 — Dashboard Redesign

## TL;DR

- Nothing in your vault needs to change — v0.10.0 is **backwards-compatible** with v0.9.0 vault layout.
- The CLI surface is additive: every v0.9.0 command still works the same.
- Running `research-hub dashboard --open` now opens a 5-tab audit view instead of the old single-scroll stat page.
- If your Zotero credentials are in the legacy `~/.claude/skills/zotero-skills/config.json`, they now get picked up automatically (used to be silently missing).

## What's new

### The dashboard has tabs now

The v0.9.0 dashboard was a single scroll — stat cards, cluster table, done.
The v0.10.0 dashboard answers a more focused question: *"AI added a bunch
of papers — what did it add, what categories, and where is each one
stored across Zotero / Obsidian / NotebookLM?"*

Five tabs, each with a specific job:

| Tab | What's in it |
|---|---|
| **Overview** (default) | Treemap of papers per cluster (sqrt-scaled so small clusters stay readable), per-cluster storage map with clickable `zotero://` / `obsidian://` / NotebookLM deep-links, and a 15-row recent-additions feed. |
| **Library** | Every cluster as an expandable card. Each paper row shows title, authors, year, abstract excerpt, a `Cite` button (BibTeX popup) and an `Open ▼` menu (Zotero / Obsidian / NotebookLM / Copy DOI). Per-cluster `Download .bib` button for batch citation export. |
| **Briefings** | Inline preview of every downloaded NotebookLM briefing. `Open in NotebookLM` + `Copy full text` buttons. |
| **Diagnostics** | Health badges (Zotero / Obsidian / NotebookLM subsystems) and drift alerts (folder-mismatch, orphan notes, duplicate DOIs). Each alert has a pre-filled fix command. |
| **Manage** | Command-builder forms for each cluster: `rename`, `merge`, `split`, `bind-zotero`, `bind-nlm`, `delete`. Fill the form → click the button → the generated `research-hub clusters ...` command is copied to your clipboard → paste into terminal. |

### New footer: the Debug widget

Below every tab, always visible, a Debug widget. Click `Show snapshot`
to see the live vault state as a paste-ready blob (vault root, persona,
health status, cluster bindings, drift alerts). Click `Copy snapshot`
to send it back to the AI assistant when reporting a bug — the blob
has everything the AI needs to reproduce.

### Health banner on the Overview tab

When `doctor` reports any `FAIL`, the Overview tab shows a red banner
at the top listing the failing checks with their remedy commands. This
surfaces problems prominently instead of burying them in Diagnostics.

### `--watch` mode for live vault monitoring

```bash
research-hub dashboard --watch --open
```

Polls your vault's state files (`manifest.jsonl`, `dedup_index.json`,
`nlm_cache.json`, `clusters.yaml`, `raw/`) every 5 seconds and
re-renders the dashboard on any change. The HTML also carries a
`<meta http-equiv="refresh">` so the open browser tab auto-reloads.

Press Ctrl+C to stop.

### `--rich-bibtex` for full Zotero-formatted citations

By default, the `Cite` button in the dashboard uses a minimal BibTeX
entry built from the Obsidian note's frontmatter. That's instant
(under a second for 346 papers) and complete enough to paste into a
draft.

If you want the full Zotero-formatted entry (with abstract, tags,
collections, etc.), opt in explicitly:

```bash
research-hub dashboard --open --rich-bibtex
```

This calls `zotero get_formatted` per paper and can take several
minutes on a large vault — only use it when you actually need the
rich output.

## Migration checklist

Running through this on an existing v0.9.0 vault:

1. `pip install -U research-hub-pipeline`
2. `research-hub doctor` — all checks should still pass. If `zotero_key` reports FAIL, check the "Zotero credential location" section below.
3. `research-hub dashboard --open` — the new 5-tab view opens. The old `collect_vault_state` / `render_dashboard_html` functions are kept as thin shims so anything scripting those still works.
4. (Optional) try `--watch` mode to see the auto-refresh in action while you add a paper in another terminal.

## Zotero credential location (for existing users)

v0.10.0's credential loader checks four locations in order:

1. Environment variables `ZOTERO_API_KEY` / `ZOTERO_LIBRARY_ID` / `ZOTERO_LIBRARY_TYPE`
2. `~/.claude/.env` file with the same keys
3. `research-hub` config.json in either flat form (`zotero_api_key`, `zotero_library_id`) or the nested `zotero.*` block
4. **NEW**: `~/.claude/skills/zotero-skills/config.json` (flat keys) from the standalone zotero-skills install

If you set up Zotero years ago via the standalone `zotero-skills` install
and never re-ran `research-hub init`, your credentials now get picked up
automatically without you touching anything. In v0.9.0 and earlier, this
silently fell through to "no API key found" even though the keys were
sitting on disk.

## Breaking changes

None. The v0.9.0 test suite (361 tests) still passes with the legacy
sections + context layer kept as backwards-compat shims. 5 tests that
asserted specific strings from the old single-column layout are marked
`@pytest.mark.skip("rewritten in v0.10")`.

If you were importing `ClustersSection`, `OverviewSection`,
`ReadingQueueSection`, `ActivitySection`, or `NotebookLMSection`
directly, those names still exist as aliases pointing at the new
classes, but the rendered HTML is different — it is the new tabbed
layout.

## What's not in v0.10.0 (yet)

- **Writing helpers** (`cite --inline`, `cite --markdown`, quote capture,
  a Writing tab) — queued as v0.11.0, currently being built by Codex.
- **Direct Manage tab execution** — the Manage forms generate commands
  and copy them to the clipboard, but do NOT execute them. Running
  the commands requires a local HTTP server which is out of scope
  for a static HTML file.
- **Mobile-friendly layout** — the dashboard is designed for desktop.
  A responsive mode can come later if there's demand.

## Troubleshooting

### "Dashboard is blank"

Hard-refresh the browser (`Ctrl+Shift+R`). The tab activation CSS
changed between v0.9.0-G1 and v0.10.0 and a cached stylesheet
will show empty tabs.

### "Zotero: No Zotero API key found" still shows after setup

Check all four credential locations listed above. The most common
mistake is setting `ZOTERO_API_KEY` with PowerShell `setx` and not
opening a new shell — `setx` only affects NEW processes, not the
running one.

To verify from a new shell:
```bash
research-hub doctor
```

If still failing, open the Debug widget at the bottom of any tab,
click `Copy snapshot`, and paste the result into the AI assistant.
The snapshot shows exactly which credential sources the loader
checked and which returned empty.

### "Some paper rows show empty Cite popups"

Means the frontmatter-fallback BibTeX is empty. Check the note's
frontmatter — you probably need a `title`, `authors`, `year`, and
`doi` at minimum. Running `research-hub migrate-yaml` on a legacy
vault can backfill missing fields.

### "Chrome console shows 'Unsafe attempt to load URL' on file://"

That was a bug in v0.10.0-A through v0.10.0-D (manage forms + hash
anchors on treemap cells). Fixed in v0.10.0-E. Upgrade to 0.10.0
final (the tag) or later.
