Dashboard: LLM unconfigured empty state nudge for Ollama

[melagiri]

Summary

When no LLM provider is configured, the Insights and Patterns pages currently show empty/loading states with no explanation or call to action. Add a friendly nudge that surfaces Ollama as the zero-friction path to unlocking AI analysis — without blocking access to the rest of the dashboard.

Depends on: #234 (Ollama-first experience — auto-detect, model unification)

---

Problem

A user who installs Code Insights, runs code-insights sync, and opens the dashboard will see their sessions, activity charts, and cost data. But the Insights tab and Patterns tab will be empty or show a spinner that never resolves — because no LLM is configured.

There is currently no messaging explaining why, and no affordance to fix it. The user has to discover code-insights config llm on their own.

This is a missed "aha moment." The fix is a non-blocking nudge that:

1. Explains why AI features are inactive
2. Points to Ollama as the free, local, zero-setup path
3. Offers a shortcut to configure

---

Proposed UX

On the Insights page (session detail view, AI analysis section) and Patterns page (reflect/weekly synthesis), when llmProvider is null or unconfigured in the user's settings:

Replace the empty/spinner state with a friendly callout:

No AI analysis configured

Install Ollama for free, local AI analysis — no API key or account needed.
Sessions, stats, and timeline are fully available without it.

[Install Ollama]  [Configure LLM]

• "Install Ollama" links to https://ollama.com
• "Configure LLM" opens the Settings page (or a modal) pre-scrolled to the LLM section
• The callout is informational — not a modal, not a gate, not a wall
• The rest of the dashboard remains fully functional: navigation, stats, activity charts, timeline, cost tracking all work unchanged

Design notes

• Use a card or inline alert style consistent with existing shadcn/ui components
• Should not flash on page load — only render after the settings query has resolved and confirmed no LLM is set
• If the user dismisses the nudge, it should stay dismissed for the session (not persist across restarts — keep it visible as a helpful reminder on next open)

---

Acceptance Criteria

• When no LLM is configured, the Insights page AI analysis section shows the nudge instead of an empty or perpetual loading state
• When no LLM is configured, the Patterns page (reflect/weekly synthesis) shows the nudge instead of empty state
• The nudge includes a link to https://ollama.com and a link/button to the Settings LLM config section
• The rest of the dashboard (stats, timeline, activity, cost) is fully usable with no LLM configured — the nudge does not block navigation
• The nudge does not appear once an LLM is configured (settings query has resolved with a valid provider)
• The nudge does not flash on load — it renders only after the settings state is known
• pnpm build passes from repo root with zero errors

Files Expected to Change

• dashboard/src/pages/InsightsPage.tsx (or equivalent session detail component)
• dashboard/src/pages/PatternsPage.tsx (or equivalent reflect component)
• Possibly a new shared LLMNudge component in dashboard/src/components/

Size

M — UI-only change within the dashboard package. No CLI changes, no schema changes, no API changes. Two page components + one shared nudge component.

Notes

• The auto-detect feature in Ollama-first experience: README callout, model list unification, auto-detect on sync #234 reduces how often this nudge appears (Ollama users get configured automatically on first sync). This nudge is the fallback for users who don't have Ollama and need to set up a paid provider, or who ran sync before Ollama was installed.
• Do NOT implement this as a modal, interstitial, or anything that blocks dashboard use. The dashboard is valuable without LLM — analytics, session history, cost tracking all work. The nudge is additive, not a gate.

[melagiri]

UX Engineer Feedback (from PR #236 review)

Carry these forward into this issue — address alongside the empty state nudge:

Tweaks from PR #236 (deferred to this issue)

1. Confirmation message wording — Change from "using" to "configured" + add next-step hint:

   Ollama detected — configured llama3.3 for AI analysis (free & local).
   Open the dashboard and click "Analyze" on any session to generate insights.
   Run `code-insights config llm` to change provider.
   

2. README example — Use npx @code-insights/cli instead of code-insights sync in the Ollama callout (matches actual zero-config flow)

3. README architecture diagram — Line mentioning LLM Providers — (your API key) should say (your API key or Ollama) to reinforce local option

Empty State Nudge Design (from UX review)

• Dismissible banner at top of Insights/Patterns pages, not a wall
• Store dismissal in localStorage — don't nag on every visit, show again only if config cleared
• Context-sensitive copy: Insights page → "Get AI-powered insights", Patterns page → "Enable cross-session pattern detection"
• One CTA: "Configure AI Provider" links to Settings with LLM card in view
• Info/muted styling (not warning/amber) — insights are a bonus, not a requirement
• Check config state, not insight count (don't show if configured but analysis hasn't run yet)
• Don't probe Ollama from browser — check server-side config only (CORS issues)

Future Enhancements (beyond #235, captured for roadmap)

1. Auto-analyze 1-2 sessions on first Ollama detection (the "instant wow" moment)
2. Validate detected model works for structured JSON output (smoke test)
3. Print a one-liner for users without Ollama on first sync when no LLM configured
4. Verify config clear sets dashboard.llm to undefined, not {}

[melagiri]

Implementation Handoff

Worktree: `/Users/melagiri/Workspace/codeInsights/code-insights-ollama-dashboard-nudge/`
Branch: `feature/ollama-dashboard-nudge`

---

A. Dashboard Empty State Nudge (main feature)

Goal: Show a dismissible, info-styled banner on Insights and Patterns pages when no LLM is configured. Not a wall — the dashboard stays fully usable.

How to check LLM config state

Use the existing useLlmConfig hook from dashboard/src/hooks/useConfig.ts:

import { useLlmConfig } from '@/hooks/useConfig';
const { data: llmConfig, isLoading: configLoading } = useLlmConfig();
const llmConfigured = !configLoading && !!llmConfig?.provider;

• llmConfig.provider is null/undefined when unconfigured
• Wait for configLoading === false before rendering the nudge (prevents flash)

New component: LlmNudgeBanner

Create dashboard/src/components/LlmNudgeBanner.tsx.

Props:

interface LlmNudgeBannerProps {
  context: 'insights' | 'patterns';
}

Behavior:

• Uses useLlmConfig() internally — renders null while loading, null if configured
• Stores dismissal in localStorage with key llm-nudge-dismissed-{context} (e.g. llm-nudge-dismissed-insights)
• When dismissed, renders null
• If config was previously dismissed but LLM is now configured, the localStorage key is irrelevant (component returns null due to llmConfigured check first)

UX spec:

• Styling: Info/muted — use bg-muted/50 border border-border or similar neutral card style. NOT amber/warning colors.
• Dismiss: An X button (top-right) that sets localStorage and hides the banner
• Insights copy: "Get AI-powered insights — configure a provider to extract decisions, learnings, and patterns from your sessions."
• Patterns copy: "Enable cross-session pattern detection — an AI provider is required to generate weekly friction and pattern analysis."
• CTA button text: "Configure AI Provider" → links to /settings (with hash #llm if the Settings page supports it, otherwise just /settings)
• Placement: Below the page header, above the content area. Full-width within the content area.

InsightsPage changes

File: dashboard/src/pages/InsightsPage.tsx

The current empty state (lines ~293-303) shows a generic nudge when insights.length === 0. This needs to be extended:

• Add LlmNudgeBanner context="insights" at the top of the scrollable content area (before the isError/isLoading/filtered.length === 0 conditional), so it shows even when there are existing insights from before LLM was cleared.
• The banner only renders when unconfigured (the component handles its own visibility), so placement is safe regardless of data state.

Current empty state copy can remain as-is (it already has a "Configure LLM provider" link). The new LlmNudgeBanner is additive context at the top.

PatternsPage changes

File: dashboard/src/pages/PatternsPage.tsx

• Add LlmNudgeBanner context="patterns" at the top of the main return JSX (after the header block, before the week-at-a-glance strip or generation controls).
• Same principle — the component handles its own visibility, placement is safe.

---

B. CLI Confirmation Message Wording

File: cli/src/utils/ollama-detect.ts (in the worktree)

Current message (line 87-90):

console.log(
  chalk.green(`\n  Ollama detected — using ${chalk.bold(model)} for AI analysis (free & local).`) +
  chalk.dim('\n  Run `code-insights config llm` to change.\n'),
);

Replace with:

console.log(
  chalk.green(`\n  Ollama detected — configured ${chalk.bold(model)} for AI analysis (free & local).`) +
  chalk.dim('\n  Open the dashboard and click "Analyze" on any session to get insights.') +
  chalk.dim('\n  Run `code-insights config llm` to change provider.\n'),
);

Changes: using → configured, add next-step hint on second dim line, change last dim line to to change provider.

---

C. README Updates

File: README.md (in the worktree)

Two targeted changes:

1. Ollama callout example (around line 39) — change code-insights sync to npx @code-insights/cli:

   • Current: > code-insights sync # Ollama detected automatically
   • New: > npx @code-insights/cli # Ollama detected automatically

2. Architecture diagram (around line 158-159) — update LLM Providers label:

   • Current: │ LLM Providers │ analysis, facets, / │ (your API key) │ reflect, export
   • New: │ LLM Providers │ analysis, facets, / │(API key or Ollama)│ reflect, export

---

Scope Tags

• VISUAL — dashboard nudge banner (UI only, no API changes)
• No NEW_DEPS — uses existing shadcn/ui components and hooks
• No API_CHANGE — /api/config/llm already exists and is used
• No OUTPUT_ARTIFACT — CLI message tweak uses existing chalk output pattern
• No SCHEMA_CHANGE

Pre-PR Gate

Run from repo root: pnpm build — zero errors required before creating the PR.

[melagiri]

Completed in PR #237. All checks passed. Ready for merge.

• LlmNudgeBanner component: dismissible, localStorage-namespaced (code-insights:llm-nudge-dismissed-{context}), flash-free, accessibility-compliant
• Wired into InsightsPage + PatternsPage
• CLI ollama-detect.ts: wording updated + next-step hint
• README: npx callout + architecture diagram updated
• pnpm build + 808 tests pass
• Triple-layer review complete