feat(cli): long-turn recap card + /recap, /insight toggles + setup-first README

[mabry1985]

Summary

• Recap card: appends a "※ where we left off" message after agent turns longer than 5 min OR with more than 15 tool calls. Modeled on cc-2.18's awaySummary, but triggered by turn duration / tool count rather than terminal blur (which protoCLI doesn't have a focus listener for).
• Settings: new top-level recap.{enabled,thresholdSeconds,thresholdToolCalls} and insight.enabled keys. Default ON — no experimental gate.
• Slash commands: /recap (status|enable|disable). /insight gains the same subactions; bare /insight still runs the report but errors with a hint when disabled.
• README: proto setup becomes the recommended Quick Start path; manual JSON kept below as advanced.

Files

• packages/core/src/recap/recapGenerator.ts — LLM call (generateContent, 30-msg window, 1-3 sentence prompt). Returns null on abort/error.
• packages/cli/src/ui/hooks/useRecap.ts — watches streamingState Idle ↔ non-Idle edges, tracks per-turn duration + tool_group count, fires recap when thresholds exceeded.
• packages/cli/src/ui/components/messages/RecapMessage.tsx — dim text + ※ (U+203B) marker.
• packages/cli/src/ui/commands/recapCommand.ts — new toggle command.
• packages/cli/src/ui/commands/insightCommand.ts — extended with status/enable/disable subactions.
• packages/cli/src/config/settingsSchema.ts — schema entries.
• packages/cli/src/ui/AppContainer.tsx — mounts useRecap.
• README.md — proto setup-first quick start.

Test plan

• vitest run packages/cli (3,767 pass, 7 skipped)
• tsc -p packages/core clean
• tsc -p packages/cli clean
• Manual: trigger a long turn, verify the ※ card appears
• Manual: /recap disable → verify no card next long turn
• Manual: /insight disable → verify bare /insight errors with hint

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Reworked Quick Start guide to use wizard-first setup flow with proto setup command

• New Features

  • Added recap feature to summarize conversation after long turns with configurable duration and activity thresholds
  • Added insight feature with enable/disable controls
  • Added /recap and /insight slash commands with status, enable, and disable subcommands

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ab893525-aa16-4c1f-b364-930228293fe4

📥 Commits

Reviewing files that changed from the base of the PR and between ee5cd29 and b35990d.

📒 Files selected for processing (13)

• README.md
• packages/cli/src/config/settingsSchema.ts
• packages/cli/src/services/BuiltinCommandLoader.ts
• packages/cli/src/ui/AppContainer.tsx
• packages/cli/src/ui/commands/insightCommand.ts
• packages/cli/src/ui/commands/recapCommand.ts
• packages/cli/src/ui/components/HistoryItemDisplay.tsx
• packages/cli/src/ui/components/messages/RecapMessage.tsx
• packages/cli/src/ui/hooks/useRecap.ts
• packages/cli/src/ui/types.ts
• packages/core/src/index.ts
• packages/core/src/recap/index.ts
• packages/core/src/recap/recapGenerator.ts

---

Walkthrough

This pull request introduces a new "Recap" feature that summarizes where the conversation left off after long agent turns, along with configuration controls. It adds recap generation logic to the core package, CLI slash commands for enable/disable/status, UI components for displaying recaps, and updates the settings schema with recap configuration options.

Changes

Cohort / File(s)	Summary
Documentation & Configuration README.md, packages/cli/src/config/settingsSchema.ts	Updates quick-start guidance to wizard-first flow; adds two new top-level config groups (recap and insight) with enablement toggles, duration thresholds, and tool-call thresholds.
Core Recap Generation packages/core/src/recap/recapGenerator.ts, packages/core/src/recap/index.ts, packages/core/src/index.ts	Implements recap generator that summarizes recent conversation history via model inference when completion criteria are met; exports through core package entrypoint.
Slash Commands packages/cli/src/ui/commands/recapCommand.ts, packages/cli/src/ui/commands/insightCommand.ts, packages/cli/src/services/BuiltinCommandLoader.ts	Adds new /recap command with status, enable, disable subcommands; updates /insight command with similar subcommand structure and early-exit when disabled; registers recap command in command loader.
UI Components & Hooks packages/cli/src/ui/components/messages/RecapMessage.tsx, packages/cli/src/ui/components/HistoryItemDisplay.tsx, packages/cli/src/ui/hooks/useRecap.ts, packages/cli/src/ui/AppContainer.tsx	Adds RecapMessage component for rendering recap in CLI; introduces useRecap hook that monitors streaming state, detects turn completion, triggers generation when thresholds are exceeded, and appends recap to history; integrates hook into app container with recap settings.
Type Definitions packages/cli/src/ui/types.ts	Adds MessageType.RECAP enum value and HistoryItemRecap history card type with discriminator and text field.

Sequence Diagram

sequenceDiagram
    participant User
    participant UI as AppContainer/UI
    participant Hook as useRecap Hook
    participant Client as geminiClient
    participant Config as Config
    participant History as HistoryManager

    User->>UI: Starts turn (streaming begins)
    activate Hook
    Hook->>Hook: Record turn start time & history length
    
    User->>UI: Turn completes (streaming ends)
    Hook->>Hook: Calculate elapsed time & tool_call count
    
    alt Duration or Tool Count Exceeds Threshold
        Hook->>Hook: Check for existing recap in recent history
        
        alt No existing recap found
            Hook->>Client: getHistory() for conversation context
            Client-->>Hook: Return recent conversation
            
            Hook->>Config: Get content generator & model
            Config-->>Hook: Return generator
            
            Hook->>Client: generateRecap(config, conversation, abortSignal)
            Client->>Client: Slice last 30 content items
            Client->>Client: Invoke model with recap prompt
            Client-->>Hook: Return recap text
            
            Hook->>History: addItem(type: RECAP, text)
            History-->>UI: Update history display
            
            UI->>UI: Render RecapMessage component
            User->>User: See recap summary
        else Recap already exists
            Hook->>Hook: Skip generation
        end
    else Thresholds not met
        Hook->>Hook: Do nothing
    end
    
    deactivate Hook

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/recap-and-insight-toggles

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}