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

- Recap: appends a "※ where we left off" card after agent turns longer
  than recap.thresholdSeconds (300s) or recap.thresholdToolCalls (15).
  Modeled on cc-2.18's awaySummary, but triggered by turn duration/tool
  count rather than terminal blur. Generated by `generateRecap`
  (packages/core/src/recap/) using the configured model with a 1-3
  sentence prompt; returns null on abort/error so it can never crash a
  turn. Wired into AppContainer via useRecap.
- Settings: new top-level `recap` (enabled, thresholdSeconds,
  thresholdToolCalls) and `insight` (enabled) keys on the user-scope
  schema. Both default to enabled — no experimental gate.
- Slash commands: new /recap with status|enable|disable subactions.
  /insight gains the same subactions; bare /insight still runs the
  report but errors with a hint when disabled.
- Rendering: new MessageType.RECAP + HistoryItemRecap, rendered dim
  with the U+203B (※) marker via RecapMessage.
- README: replace hand-written settings.json in the Quick Start with
  `proto setup` (the existing interactive wizard); keep the JSON
  example below as advanced/manual setup.

Co-authored-by: Automaker <automaker@localhost>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

README.md

@@ -51,9 +51,40 @@ cargo install beads_rust
 
 ## Quick Start
 
-### 1. Configure your endpoint
+### 1. Run the setup wizard
 
-proto connects to any OpenAI-compatible API. Create `~/.proto/settings.json`:
+```bash
+proto setup
+```
+
+`proto setup` is an interactive wizard that picks a provider (OpenAI, Anthropic, Gemini, or any OpenAI-compatible endpoint), discovers the available models, optionally configures voice/STT, and writes everything to `~/.proto/settings.json` for you. Re-run it any time to switch providers or pick a different default model.
+
+### 2. Set your API key
+
+The wizard tells you which env var it expects (e.g. `OPENAI_API_KEY`). Set it once:
+
+```bash
+export OPENAI_API_KEY=sk-your-key-here
+```
+
+Or persist it in `~/.proto/.env`:
+
+```
+OPENAI_API_KEY=sk-your-key-here
+```
+
+### 3. Run proto
+
+```bash
+proto                            # interactive mode
+proto -p "explain this codebase" # one-shot mode
+```
+
+No auth screen — proto connects directly to your endpoint.
+
+### Manual setup (advanced)
+
+If you'd rather skip the wizard, drop a `~/.proto/settings.json` of your own:
 
 ```json
 {
@@ -74,25 +105,6 @@ proto connects to any OpenAI-compatible API. Create `~/.proto/settings.json`:
 }
 ```
 
-### 2. Set your API key
-
-Create `~/.proto/.env`:
-
-```
-MY_API_KEY=sk-your-key-here
-```
-
-Or export it in your shell: `export MY_API_KEY=sk-your-key-here`
-
-### 3. Run proto
-
-```bash
-proto                            # interactive mode
-proto -p "explain this codebase" # one-shot mode
-```
-
-No auth screen — proto connects directly to your endpoint.
-
 ### Example: Multiple models via a gateway
 
 If you run a gateway like [LiteLLM](https://github.com/BerriAI/litellm) in front of multiple providers, register them all under `modelProviders.openai` and switch between them with `/model`:

packages/cli/src/config/settingsSchema.ts

@@ -1724,6 +1724,72 @@ const SETTINGS_SCHEMA = {
     },
   },
 
+  recap: {
+    type: 'object',
+    label: 'Recap',
+    category: 'Recap',
+    requiresRestart: false,
+    default: {},
+    description:
+      'After a long agent turn, append a short "where we left off" card to the transcript.',
+    showInDialog: false,
+    properties: {
+      enabled: {
+        type: 'boolean',
+        label: 'Recap Enabled',
+        category: 'Recap',
+        requiresRestart: false,
+        default: true,
+        description:
+          'When enabled, a 1-3 sentence recap is appended after agent turns that exceed thresholdSeconds or thresholdToolCalls. Toggle with /recap enable|disable.',
+        showInDialog: true,
+      },
+      thresholdSeconds: {
+        type: 'number',
+        label: 'Recap Duration Threshold (seconds)',
+        category: 'Recap',
+        requiresRestart: false,
+        default: 300,
+        description:
+          'Minimum agent-turn wall-clock duration (seconds) before a recap fires.',
+        showInDialog: true,
+      },
+      thresholdToolCalls: {
+        type: 'number',
+        label: 'Recap Tool-Call Threshold',
+        category: 'Recap',
+        requiresRestart: false,
+        default: 15,
+        description:
+          'Minimum tool-call count in a single turn before a recap fires.',
+        showInDialog: true,
+      },
+    },
+  },
+
+  insight: {
+    type: 'object',
+    label: 'Insight',
+    category: 'Insight',
+    requiresRestart: false,
+    default: {},
+    description:
+      'Personalized programming-insight reports generated from your chat history.',
+    showInDialog: false,
+    properties: {
+      enabled: {
+        type: 'boolean',
+        label: 'Insight Enabled',
+        category: 'Insight',
+        requiresRestart: false,
+        default: true,
+        description:
+          'When enabled, /insight will generate a personalized HTML report from your session history. Toggle with /insight enable|disable.',
+        showInDialog: true,
+      },
+    },
+  },
+
   experimental: {
     type: 'object',
     label: 'Experimental',

packages/cli/src/services/BuiltinCommandLoader.ts

@@ -51,6 +51,7 @@ import { setupCommand } from '../ui/commands/setupCommand.js';
 import { insightCommand } from '../ui/commands/insightCommand.js';
 import { teamCommand } from '../ui/commands/teamCommand.js';
 import { voiceCommand } from '../ui/commands/voiceCommand.js';
+import { recapCommand } from '../ui/commands/recapCommand.js';
 
 /**
  * Loads the core, hard-coded slash commands that are an integral part
@@ -112,6 +113,7 @@ export class BuiltinCommandLoader implements ICommandLoader {
       terminalSetupCommand,
       insightCommand,
       voiceCommand,
+      recapCommand,
     ];
 
     return allDefinitions.filter((cmd): cmd is SlashCommand => cmd !== null);

packages/cli/src/ui/AppContainer.tsx

@@ -70,6 +70,7 @@ import { clearScreen } from '../utils/stdioHelpers.js';
 import { useTextBuffer } from './components/shared/text-buffer.js';
 import { useLogger } from './hooks/useLogger.js';
 import { useGeminiStream } from './hooks/useGeminiStream.js';
+import { useRecap } from './hooks/useRecap.js';
 import { useVim } from './hooks/vim.js';
 import { isBtwCommand } from './utils/commandUtils.js';
 import { type LoadedSettings, SettingScope } from '../config/settings.js';
@@ -768,6 +769,18 @@ export const AppContainer = (props: AppContainerProps) => {
     pendingGeminiHistoryItems,
   });
 
+  // Recap card after long agent turns (※ where we left off)
+  useRecap({
+    config,
+    geminiClient,
+    streamingState,
+    history: historyManager.history,
+    addItem: historyManager.addItem,
+    enabled: settings.merged.recap?.enabled ?? true,
+    thresholdSeconds: settings.merged.recap?.thresholdSeconds ?? 300,
+    thresholdToolCalls: settings.merged.recap?.thresholdToolCalls ?? 15,
+  });
+
   // Callback for handling final submit (must be after addMessage from useMessageQueue)
   const handleFinalSubmit = useCallback(
     (submittedValue: string) => {

packages/cli/src/ui/commands/insightCommand.ts

@@ -4,18 +4,52 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { CommandContext, SlashCommand } from './types.js';
+import type {
+  CommandContext,
+  SlashCommand,
+  SlashCommandActionReturn,
+} from './types.js';
 import { CommandKind } from './types.js';
 import { MessageType } from '../types.js';
 import type { HistoryItemInsightProgress } from '../types.js';
 import { t } from '../../i18n/index.js';
 import { join } from 'path';
 import { StaticInsightGenerator } from '../../services/insight/generators/StaticInsightGenerator.js';
 import { createDebugLogger, Storage } from '@qwen-code/qwen-code-core';
+import { SettingScope } from '../../config/settings.js';
 import open from 'open';
 
 const logger = createDebugLogger('DataProcessor');
 
+function statusMessage(context: CommandContext): SlashCommandActionReturn {
+  const enabled = context.services.settings.merged.insight?.enabled ?? true;
+  return {
+    type: 'message',
+    messageType: 'info',
+    content: enabled
+      ? 'Insight: enabled. Run /insight to generate a report.'
+      : 'Insight: disabled. Run /insight enable to turn it back on.',
+  };
+}
+
+function setEnabled(
+  context: CommandContext,
+  value: boolean,
+): SlashCommandActionReturn {
+  context.services.settings.setValue(
+    SettingScope.User,
+    'insight.enabled',
+    value,
+  );
+  return {
+    type: 'message',
+    messageType: 'info',
+    content: value
+      ? 'Insight enabled. Run /insight to generate a report.'
+      : 'Insight disabled. Run /insight enable to turn it back on.',
+  };
+}
+
 export const insightCommand: SlashCommand = {
   name: 'insight',
   get description() {
@@ -24,7 +58,41 @@ export const insightCommand: SlashCommand = {
     );
   },
   kind: CommandKind.BUILT_IN,
+  subCommands: [
+    {
+      name: 'status',
+      description: 'Show insight enabled status',
+      kind: CommandKind.BUILT_IN,
+      action: statusMessage,
+    },
+    {
+      name: 'enable',
+      description: 'Enable /insight report generation',
+      kind: CommandKind.BUILT_IN,
+      action: (context: CommandContext): SlashCommandActionReturn =>
+        setEnabled(context, true),
+    },
+    {
+      name: 'disable',
+      description: 'Disable /insight report generation',
+      kind: CommandKind.BUILT_IN,
+      action: (context: CommandContext): SlashCommandActionReturn =>
+        setEnabled(context, false),
+    },
+  ],
   action: async (context: CommandContext) => {
+    if (context.services.settings.merged.insight?.enabled === false) {
+      context.ui.addItem(
+        {
+          type: MessageType.INFO,
+          text: t(
+            'Insight is disabled. Run /insight enable to turn it back on.',
+          ),
+        },
+        Date.now(),
+      );
+      return;
+    }
     try {
       context.ui.setDebugMessage(t('Generating insights...'));
 

packages/cli/src/ui/commands/recapCommand.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2025 protoLabs Studio
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  CommandContext,
+  SlashCommand,
+  SlashCommandActionReturn,
+} from './types.js';
+import { CommandKind } from './types.js';
+import { SettingScope } from '../../config/settings.js';
+
+const DEFAULT_THRESHOLD_SECONDS = 300;
+const DEFAULT_THRESHOLD_TOOL_CALLS = 15;
+
+function statusMessage(context: CommandContext): SlashCommandActionReturn {
+  const merged = context.services.settings.merged;
+  const enabled = merged.recap?.enabled ?? true;
+  const seconds = merged.recap?.thresholdSeconds ?? DEFAULT_THRESHOLD_SECONDS;
+  const toolCalls =
+    merged.recap?.thresholdToolCalls ?? DEFAULT_THRESHOLD_TOOL_CALLS;
+
+  return {
+    type: 'message',
+    messageType: 'info',
+    content: [
+      `Recap: ${enabled ? 'enabled' : 'disabled'}`,
+      `Duration threshold: ${seconds}s`,
+      `Tool-call threshold: ${toolCalls}`,
+      enabled
+        ? 'A "where we left off" card will be appended after long agent turns.'
+        : 'Run /recap enable to turn it back on.',
+    ].join('\n'),
+  };
+}
+
+function setEnabled(
+  context: CommandContext,
+  value: boolean,
+): SlashCommandActionReturn {
+  context.services.settings.setValue(SettingScope.User, 'recap.enabled', value);
+  return {
+    type: 'message',
+    messageType: 'info',
+    content: value
+      ? 'Recap enabled. Long-running turns will produce a "where we left off" card.'
+      : 'Recap disabled.',
+  };
+}
+
+export const recapCommand: SlashCommand = {
+  name: 'recap',
+  description:
+    'Toggle the long-turn recap card (※ where we left off). Run with no args for status.',
+  kind: CommandKind.BUILT_IN,
+  subCommands: [
+    {
+      name: 'status',
+      description: 'Show recap status and thresholds',
+      kind: CommandKind.BUILT_IN,
+      action: statusMessage,
+    },
+    {
+      name: 'enable',
+      description: 'Enable the long-turn recap card',
+      kind: CommandKind.BUILT_IN,
+      action: (context: CommandContext): SlashCommandActionReturn =>
+        setEnabled(context, true),
+    },
+    {
+      name: 'disable',
+      description: 'Disable the long-turn recap card',
+      kind: CommandKind.BUILT_IN,
+      action: (context: CommandContext): SlashCommandActionReturn =>
+        setEnabled(context, false),
+    },
+  ],
+  action: (context: CommandContext): SlashCommandActionReturn =>
+    statusMessage(context),
+};

packages/cli/src/ui/components/HistoryItemDisplay.tsx

@@ -43,6 +43,7 @@ import { ContextUsage } from './views/ContextUsage.js';
 import { ArenaAgentCard, ArenaSessionCard } from './arena/ArenaCards.js';
 import { InsightProgressMessage } from './messages/InsightProgressMessage.js';
 import { BtwMessage } from './messages/BtwMessage.js';
+import { RecapMessage } from './messages/RecapMessage.js';
 
 interface HistoryItemDisplayProps {
   item: HistoryItem;
@@ -230,6 +231,9 @@ const HistoryItemDisplayComponent: React.FC<HistoryItemDisplayProps> = ({
       {itemForDisplay.type === 'btw' && itemForDisplay.btw && (
         <BtwMessage btw={itemForDisplay.btw} />
       )}
+      {itemForDisplay.type === 'recap' && (
+        <RecapMessage text={itemForDisplay.text} />
+      )}
     </Box>
   );
 };