codex-session-insights 0.2.0 → 0.2.2

package/README.md

@@ -60,6 +60,12 @@ Default run:
 npx codex-session-insights
 ```
 
+Lite local run for prompt and layout testing:
+
+```bash
+npx codex-session-insights --preset lite
+```
+
 Estimate first, then decide:
 
 ```bash
@@ -120,6 +126,7 @@ Current default analysis plan:
 
 Important behavior defaults:
 
+- `--preset lite` maps to `days=7`, `limit=20`, `facet-limit=8`, `preview=10`
 - `limit` means the target number of substantive threads to include in the report, not just the first 50 indexed threads
 - `facet-limit` means the max number of uncached per-thread facet analyses to run in a single report
 - Report language follows a best-effort system locale check
@@ -195,7 +202,9 @@ Useful local commands:
 npm install
 npm test
 npm run check
+npm run report:lite
 npm run generate:test-report
 ```
 
+`npm run report:lite` runs a smaller local analysis preset for testing prompt and layout changes without paying the full 200/50 default cost.
 `npm run generate:test-report` writes a deterministic sample report page to `test-artifacts/sample-report/`.

package/lib/cli.js

@@ -99,6 +99,7 @@ export async function runCli(argv) {
   })
   report.analysisMode = 'llm'
   report.provider = parsed.options.provider
+  report.analysisEstimate = estimate
   report.analysisUsage = llmResult.analysisUsage
 
   progress.startStage(parsed.options, getUiText(parsed.options.lang).writingFiles)
@@ -135,11 +136,18 @@ export async function runCli(argv) {
 
 function parseArgs(argv) {
   let command = null
+  const explicit = {
+    days: false,
+    limit: false,
+    preview: false,
+    facetLimit: false,
+  }
   const options = {
     codexHome: null,
     outDir: null,
     jsonPath: null,
     htmlPath: null,
+    preset: DEFAULT_SCOPE_PRESET,
     days: 30,
     limit: 200,
     preview: 50,
@@ -195,14 +203,21 @@ function parseArgs(argv) {
       continue
     }
     if (arg === '--days') {
+      explicit.days = true
       options.days = toPositiveInt(requireValue(argv, ++i, '--days'), '--days')
       continue
     }
+    if (arg === '--preset') {
+      options.preset = normalizeScopePreset(requireValue(argv, ++i, '--preset'))
+      continue
+    }
     if (arg === '--limit') {
+      explicit.limit = true
       options.limit = toPositiveInt(requireValue(argv, ++i, '--limit'), '--limit')
       continue
     }
     if (arg === '--preview') {
+      explicit.preview = true
       options.preview = toPositiveInt(requireValue(argv, ++i, '--preview'), '--preview')
       continue
     }
@@ -255,6 +270,7 @@ function parseArgs(argv) {
       continue
     }
     if (arg === '--facet-limit') {
+      explicit.facetLimit = true
       options.facetLimit = toPositiveInt(requireValue(argv, ++i, '--facet-limit'), '--facet-limit')
       continue
     }
@@ -298,6 +314,19 @@ function parseArgs(argv) {
     throw new Error(`Invalid provider "${options.provider}". Expected codex-cli or openai.`)
   }
 
+  options.preset = normalizeScopePreset(options.preset)
+  const explicitValues = {
+    days: options.days,
+    limit: options.limit,
+    preview: options.preview,
+    facetLimit: options.facetLimit,
+  }
+  Object.assign(options, applyScopePreset(options, options.preset))
+  if (explicit.days) options.days = explicitValues.days
+  if (explicit.limit) options.limit = explicitValues.limit
+  if (explicit.preview) options.preview = explicitValues.preview
+  if (explicit.facetLimit) options.facetLimit = explicitValues.facetLimit
+
   return { command, options, help }
 }
 
@@ -330,6 +359,7 @@ Options:
   --json-path <path>        Exact path for report.json
   --html-path <path>        Exact path for report.html
   --days <n>                Only include threads updated in the last N days (default: 30)
+  --preset <name>           Scope preset: lite, standard, or deep (default: standard)
   --limit <n>               Target number of substantive threads to include (default: 200)
   --preview <n>             Number of threads to embed in the HTML report (default: 50)
   --provider <name>         Model provider: codex-cli or openai (default: codex-cli)
@@ -681,11 +711,22 @@ function inferQualityPreset(options) {
 }
 
 function applyScopePreset(options, preset) {
-  if (preset === 'conservative') return { ...options, limit: 20, facetLimit: 8 }
+  if (preset === 'lite' || preset === 'conservative') {
+    return { ...options, days: 7, limit: 20, facetLimit: 8, preview: 10 }
+  }
   if (preset === 'deep') return { ...options, limit: 400, facetLimit: 50 }
   return { ...options, limit: 200, facetLimit: 50 }
 }
 
+function normalizeScopePreset(value) {
+  const preset = String(value || '').trim().toLowerCase()
+  if (preset === 'lite') return 'lite'
+  if (preset === 'conservative') return 'conservative'
+  if (preset === 'deep') return 'deep'
+  if (preset === 'standard' || !preset) return 'standard'
+  throw new Error(`Invalid preset "${value}". Expected lite, standard, or deep.`)
+}
+
 function applyQualityPreset(options, preset) {
   if (preset === 'cheaper') {
     return {
@@ -997,6 +1038,8 @@ export const __test = {
   applyScopePreset,
   applyQualityPreset,
   buildEquivalentCommand,
+  parseArgs,
+  normalizeScopePreset,
   normalizeLang,
   detectSystemLanguage,
 }

package/lib/codex-data.js

@@ -8,8 +8,16 @@ import { promisify } from 'node:util'
 const execFileAsync = promisify(execFile)
 const MAX_TRANSCRIPT_CHARS = 30000
 const USER_TRANSCRIPT_LIMIT = 500
-const ASSISTANT_TRANSCRIPT_LIMIT = 180
+const ASSISTANT_TRANSCRIPT_LIMIT = 300
 const FAILURE_SUMMARY_LIMIT = 120
+const MAX_TOOL_LINES_PER_BURST = 2
+const LOW_SIGNAL_ASSISTANT_PATTERNS = [
+  /^i('| a)?m\s+(checking|looking|reviewing|reading|investigating)\b/i,
+  /^i('| wi)?ll\s+(check|look|review|inspect|read|investigate|start by)\b/i,
+  /^let me\b/i,
+  /^(checking|reviewing|reading|looking at|investigating)\b/i,
+  /^(next|now)\b/i,
+]
 const TASK_AGENT_TOOLS = new Set([
   'spawn_agent',
   'send_input',
@@ -422,7 +430,7 @@ export function summarizeThread(thread, events) {
     averageResponseTimeSeconds: average(responseTimesSeconds),
     activeHours,
     userMessageTimestamps: sortedUserTs.map(tsMs => new Date(tsMs).toISOString()),
-    transcriptForAnalysis: clampTranscript(transcriptLines.join('\n')),
+    transcriptForAnalysis: clampTranscript(compactTranscriptLines(transcriptLines).join('\n')),
     gitCommits,
     gitPushes,
     userInterruptions,
@@ -627,6 +635,38 @@ function clampTranscript(text) {
   return `${clean.slice(0, MAX_TRANSCRIPT_CHARS)}\n[Transcript truncated]`
 }
 
+function compactTranscriptLines(lines) {
+  const compacted = []
+  let pendingToolBurst = []
+
+  const flushToolBurst = () => {
+    if (!pendingToolBurst.length) return
+    compacted.push(...pendingToolBurst.slice(0, MAX_TOOL_LINES_PER_BURST))
+    const remaining = pendingToolBurst.length - MAX_TOOL_LINES_PER_BURST
+    if (remaining > 0) {
+      compacted.push(`[Tool activity truncated: ${remaining} more tool calls]`)
+    }
+    pendingToolBurst = []
+  }
+
+  for (const line of lines) {
+    if (isLowSignalAssistantLine(line)) continue
+
+    if (isToolLine(line)) {
+      pendingToolBurst.push(line)
+      continue
+    }
+
+    flushToolBurst()
+    if (!compacted.length || compacted[compacted.length - 1] !== line) {
+      compacted.push(line)
+    }
+  }
+
+  flushToolBurst()
+  return compacted
+}
+
 function appendTranscriptLine(lines, line, setLastLine, lastLine) {
   const clean = String(line ?? '').trim()
   if (!clean || clean === lastLine) return
@@ -634,6 +674,20 @@ function appendTranscriptLine(lines, line, setLastLine, lastLine) {
   setLastLine(clean)
 }
 
+function isToolLine(line) {
+  const text = String(line || '')
+  return text.startsWith('[Tool: ')
+}
+
+function isLowSignalAssistantLine(line) {
+  const text = String(line || '')
+  if (!text.startsWith('[Assistant] ')) return false
+  const body = text.slice('[Assistant] '.length).trim()
+  if (!body) return true
+  if (body.length > 60) return false
+  return LOW_SIGNAL_ASSISTANT_PATTERNS.some(pattern => pattern.test(body))
+}
+
 function sanitizeTranscriptText(value, limit) {
   const text = String(value ?? '')
     .replace(/<system_instruction>[\s\S]*?<\/system_instruction>/g, ' ')

package/lib/llm-insights.js

@@ -276,24 +276,27 @@ const SECTION_DEFS = [
     contextKind: 'project_areas',
     schemaName: 'codex_project_areas',
     schema: PROJECT_AREAS_SCHEMA,
-    prompt: `Analyze this Codex usage data and identify project areas.
+    prompt: `Analyze this Codex usage data and identify the user's main workstreams.
 
 RESPOND WITH ONLY A VALID JSON OBJECT:
 {
   "areas": [
-    {"name": "Area name", "session_count": 0, "description": "2-3 sentences about what was worked on and how Codex was used."}
+    {"name": "Area name", "session_count": 0, "description": "2-3 sentences describing the workstream, its recurring tasks, and why it matters."}
   ]
 }
 
-Include 4-5 areas. Skip Codex self-hosting/meta work unless it is a dominant project area.
+Include 3-4 areas. Skip Codex self-hosting/meta work unless it is a dominant project area.
 
 Guardrails:
 - Use concrete project or workstream names, not generic labels like "coding" or "development"
 - Base areas on repeated evidence across summaries, not one-off threads
 - Prefer project + task framing over tool-centric framing
-- Group related tasks into a coherent workstream instead of listing each task separately
-- Each description should sound like a mini report paragraph: what kinds of work clustered together, then how Codex contributed
-- Prefer descriptions that mention representative tasks or artifacts instead of vague labels`,
+- Group related tasks into a coherent long-running workstream instead of listing each task separately
+- Prefer fewer, broader areas that still feel accurate over a more complete but fragmented list
+- Do not turn recent sub-tasks, bugfixes, or cleanup passes into separate areas unless they clearly form their own repeated stream
+- Each description should read like a workstream summary, not a changelog
+- Mention representative tasks, artifacts, or decisions so the area feels concrete without enumerating every thread
+- Keep the focus on what the user was trying to accomplish; mention Codex only lightly when it clarifies the shape of the work`,
   },
   {
     name: 'interaction_style',
@@ -311,9 +314,12 @@ RESPOND WITH ONLY A VALID JSON OBJECT:
 
 Guardrails:
 - Focus on stable interaction patterns, not isolated moments
-- Talk about how the user scopes work, interrupts, redirects, or trusts execution
+- Talk about how the user scopes work, redirects goals, sets acceptance bars, or trusts execution
+- Prefer evidence from user requests, follow-up corrections, repeated constraints, and outcome patterns over implementation telemetry
 - Do not infer user preference from Codex's default tool mix or harness behavior; high exec/tool usage can reflect the agent's operating style rather than the user's instructions
 - Treat shell usage, file reads, and verification commands as weak evidence unless the user explicitly asked for that working style
+- Do not infer style from repository type, documentation volume, or language mix alone
+- Avoid turning a single repo's workflow shape into a personality claim about the user
 - If evidence is mixed, describe the tension instead of forcing one clean story`,
   },
   {
@@ -360,6 +366,7 @@ Include 3 friction categories with 2 examples each.
 Guardrails:
 - Separate model-side friction from user/workflow-side friction when useful
 - Examples must be concrete and tied to the supplied evidence
+- Treat overlap or concurrency metrics as weak supporting evidence unless the summaries or friction details also show real switching pain
 - Do not invent root causes that are not visible in the data`,
   },
   {
@@ -401,6 +408,10 @@ Guardrails:
 - Suggest only actions that clearly connect to repeated evidence
 - Avoid generic advice like "give more context" unless it is overwhelmingly justified
 - Prefer changes with strong leverage: repo memory, repeatable workflows, automation, or parallelism
+- Do not recommend first-time adoption of AGENTS.md, Skills, codex exec, Sub-agents, or MCP Servers when the capability_adoption evidence shows the user already uses them in a moderate or strong way
+- When a capability is already adopted, suggest a deeper refinement or a tighter operating pattern instead of basic adoption
+- Distinguish "you should start using this" from "you should formalize or deepen how you already use this"
+- Use AGENTS.md as the canonical repo instruction filename in examples; do not mention CLAUDE.md
 - Write AGENTS.md additions as directly pasteable instruction lines, not commentary about instructions
 - Make feature examples immediately usable; avoid placeholders like "insert your repo path here" unless unavoidable
 - Make usage pattern suggestions sound like concrete next actions the user can try today, not abstract best practices`,
@@ -610,18 +621,31 @@ export async function estimateLlmAnalysisCost({ threadSummaries, options = {} })
   let estimatedFacetOutputTokens = 0
   let estimatedSummaryInputTokens = 0
   let estimatedSummaryOutputTokens = 0
+  const facetSystemPrompt = buildFacetSystemPrompt(options.lang)
 
   for (const job of uncachedFacetJobs) {
     const transcript = String(job.thread.transcriptForAnalysis || '').trim()
     const transcriptChars = transcript.length
     if (!transcriptChars) {
-      estimatedFacetInputTokens += 600
+      estimatedFacetInputTokens += estimateModelInputTokens({
+        provider: options.provider || DEFAULT_PROVIDER,
+        systemPrompt: facetSystemPrompt,
+        userPrompt: buildFacetExtractionPrompt(job.thread, `${job.thread.title || '(untitled)'}\n${job.thread.firstUserMessage || ''}`.trim(), options.lang),
+        schema: FACET_SCHEMA,
+        structured: true,
+      })
       estimatedFacetOutputTokens += 350
       continue
     }
 
     if (transcriptChars <= LONG_TRANSCRIPT_THRESHOLD) {
-      estimatedFacetInputTokens += estimateTokensFromChars(transcriptChars) + 1200
+      estimatedFacetInputTokens += estimateModelInputTokens({
+        provider: options.provider || DEFAULT_PROVIDER,
+        systemPrompt: facetSystemPrompt,
+        userPrompt: buildFacetExtractionPrompt(job.thread, transcript, options.lang),
+        schema: FACET_SCHEMA,
+        structured: true,
+      })
       estimatedFacetOutputTokens += 350
       continue
     }
@@ -629,20 +653,44 @@ export async function estimateLlmAnalysisCost({ threadSummaries, options = {} })
     const chunks = chunkText(transcript, TRANSCRIPT_CHUNK_SIZE)
     chunkSummaryCalls += chunks.length
     for (const chunk of chunks) {
-      estimatedSummaryInputTokens += estimateTokensFromChars(chunk.length) + 220
+      estimatedSummaryInputTokens += estimateModelInputTokens({
+        provider: options.provider || DEFAULT_PROVIDER,
+        systemPrompt: `${FACET_TRANSCRIPT_SUMMARY_DIRECTIVE}\n\nPreserve user goal, outcome, friction, command/tool issues, and what the assistant actually achieved.`,
+        userPrompt: `Chunk 1 of ${chunks.length}\n\n${chunk}`,
+        structured: false,
+      })
       estimatedSummaryOutputTokens += 260
     }
     const combinedSummaryChars = chunks.length * 1100
     if (combinedSummaryChars > LONG_TRANSCRIPT_THRESHOLD) {
       combineSummaryCalls += 1
-      estimatedSummaryInputTokens += estimateTokensFromChars(combinedSummaryChars) + 180
+      estimatedSummaryInputTokens += estimateModelInputTokens({
+        provider: options.provider || DEFAULT_PROVIDER,
+        systemPrompt:
+          'Combine these coding-session chunk summaries into one compact transcript summary. Keep only material signal for later facet extraction. Do not carry boilerplate, stack traces, or command details.',
+        userPrompt: makePlaceholderText(combinedSummaryChars, 'Chunk summaries'),
+        structured: false,
+      })
       estimatedSummaryOutputTokens += 320
     }
-    estimatedFacetInputTokens += 2400
+    estimatedFacetInputTokens += estimateModelInputTokens({
+      provider: options.provider || DEFAULT_PROVIDER,
+      systemPrompt: facetSystemPrompt,
+      userPrompt: buildFacetExtractionPrompt(
+        job.thread,
+        makePlaceholderText(
+          combinedSummaryChars > LONG_TRANSCRIPT_THRESHOLD ? 1200 : combinedSummaryChars,
+          '[Long transcript summarized before facet extraction]',
+        ),
+        options.lang,
+      ),
+      schema: FACET_SCHEMA,
+      structured: true,
+    })
     estimatedFacetOutputTokens += 350
   }
 
-  const estimatedSectionInputs = estimateSectionInputs(candidateThreads, facetJobs)
+  const estimatedSectionInputs = estimateSectionInputs(candidateThreads, facetJobs, options)
   const fastSectionCalls = SECTION_DEFS.filter(section => section.modelTier === 'fast').length
   const fullSectionCalls = SECTION_DEFS.filter(section => section.modelTier !== 'fast').length
   const estimatedFastSectionInputTokens = SECTION_DEFS.filter(section => section.modelTier === 'fast')
@@ -814,61 +862,14 @@ async function getFacetForThread(thread, { cacheDir, model, provider, providerOp
     provider,
     providerOptions,
   })
-  const prompt = `Analyze this Codex coding session and extract structured facets.
-
-CRITICAL GUIDELINES:
-1. goal_categories should count only what the user explicitly asked for.
-2. user_satisfaction_counts should rely on explicit user signals or strong transcript evidence.
-3. friction_counts should be specific: misunderstood_request, wrong_approach, buggy_code, user_rejected_action, excessive_changes, tool_failed, slow_or_verbose, user_unclear, external_issue.
-4. If the session is mostly warmup, rehearsal, or cache-filling, use warmup_minimal as the only goal category.
-5. If evidence is insufficient after transcript compression, use conservative values such as unclear_from_transcript rather than guessing.
-6. Do not infer the user's goal from assistant or tool activity alone.
-7. Do not count assistant-led exploration or extra implementation work unless the user clearly asked for it.
-
-Allowed values:
-- outcome: fully_achieved | mostly_achieved | partially_achieved | not_achieved | unclear_from_transcript
-- assistant_helpfulness: unhelpful | slightly_helpful | moderately_helpful | very_helpful | essential
-- session_type: single_task | multi_task | iterative_refinement | exploration | quick_question
-- primary_success: none | fast_accurate_search | correct_code_edits | good_explanations | proactive_help | multi_file_changes | good_debugging
-
-Language:
-- Keep enum values and keys exactly as requested.
-- Write free-text fields in ${describeLanguage(langFromProviderOptions(providerOptions))}.
-
-Transcript:
-${transcript}
-
-Summary stats:
-${JSON.stringify(
-    {
-      title: thread.title,
-      cwd: thread.cwd,
-      durationMinutes: thread.durationMinutes,
-      userMessages: thread.userMessages,
-      assistantMessages: thread.assistantMessages,
-      totalToolCalls: thread.totalToolCalls,
-      totalCommandFailures: thread.totalCommandFailures,
-      toolCounts: thread.toolCounts,
-      toolFailures: thread.toolFailures,
-      userInterruptions: thread.userInterruptions,
-      usesTaskAgent: thread.usesTaskAgent,
-      usesMcp: thread.usesMcp,
-      usesWebSearch: thread.usesWebSearch,
-      usesWebFetch: thread.usesWebFetch,
-    },
-    null,
-    2,
-  )}
-
-RESPOND WITH ONLY A VALID JSON OBJECT matching the requested schema.`
+  const prompt = buildFacetExtractionPrompt(thread, transcript, langFromProviderOptions(providerOptions))
 
   const rawFacet = await callStructuredModel({
     provider,
     model,
     schemaName: 'codex_session_facet',
     schema: FACET_SCHEMA,
-    systemPrompt:
-      `You extract structured coding-session facets from compressed transcripts. Use only transcript evidence. Be conservative when evidence is weak. Do not infer intent from tool activity alone. ${getStructuredLanguageInstruction(langFromProviderOptions(providerOptions))}`.trim(),
+    systemPrompt: buildFacetSystemPrompt(langFromProviderOptions(providerOptions)),
     userPrompt: prompt,
       options: {
         ...providerOptions,
@@ -989,6 +990,8 @@ function buildInsightContext(report, threadSummaries, facets) {
     ),
   ).slice(0, MAX_USER_INSTRUCTIONS)
 
+  const capabilityAdoption = summarizeCapabilityAdoption(report, threadSummaries, facets)
+
   return {
     metadata: {
       generated_at: report.metadata.generatedAt,
@@ -1025,6 +1028,7 @@ function buildInsightContext(report, threadSummaries, facets) {
       friction,
       success,
     },
+    capability_adoption: capabilityAdoption,
     session_summaries: sortedFacets.slice(0, MAX_CONTEXT_FACETS).map(facet => ({
       thread_id: facet.threadId,
       title: truncateForContext(facet.title, 80),
@@ -1051,6 +1055,69 @@ function buildInsightContext(report, threadSummaries, facets) {
   }
 }
 
+function summarizeCapabilityAdoption(report, threadSummaries, facets) {
+  const textByThread = new Map()
+  for (const thread of threadSummaries) {
+    textByThread.set(
+      thread.id,
+      [thread.title, thread.firstUserMessage]
+        .map(value => String(value || ''))
+        .join('\n')
+        .toLowerCase(),
+    )
+  }
+
+  for (const facet of facets) {
+    const existing = textByThread.get(facet.threadId) || ''
+    const facetText = [
+      facet.underlying_goal,
+      facet.brief_summary,
+      ...(facet.user_instructions || []),
+    ]
+      .map(value => String(value || ''))
+      .join('\n')
+      .toLowerCase()
+    textByThread.set(facet.threadId, `${existing}\n${facetText}`.trim())
+  }
+
+  const detectMentionedThreads = regex => {
+    let count = 0
+    for (const text of textByThread.values()) {
+      if (regex.test(text)) count += 1
+    }
+    return count
+  }
+
+  const totalThreads = Math.max(1, Number(report.metadata.threadCount || threadSummaries.length || 0))
+  const signals = {
+    agents_md: detectMentionedThreads(/\bagents\.md\b/i),
+    skills: detectMentionedThreads(/\bskills?\b/i),
+    codex_exec: detectMentionedThreads(/\bcodex exec\b/i),
+    subagents: Number(report.summary.sessionsUsingTaskAgent || 0),
+    mcp_servers: Number(report.summary.sessionsUsingMcp || 0),
+    web_search: Number(report.summary.sessionsUsingWebSearch || 0),
+    web_fetch: Number(report.summary.sessionsUsingWebFetch || 0),
+  }
+
+  return Object.fromEntries(
+    Object.entries(signals).map(([key, count]) => [
+      key,
+      {
+        count,
+        status: classifyCapabilityAdoption(count, totalThreads),
+      },
+    ]),
+  )
+}
+
+function classifyCapabilityAdoption(count, totalThreads) {
+  const share = Number(count || 0) / Math.max(1, Number(totalThreads || 0))
+  if (count >= 10 || share >= 0.25) return 'strong'
+  if (count >= 4 || share >= 0.1) return 'moderate'
+  if (count > 0) return 'light'
+  return 'none'
+}
+
 function buildAtAGlancePrompt(context, insights) {
   return `You are writing an "At a Glance" summary for a Codex usage insights report.
 
@@ -1078,6 +1145,124 @@ ${compactJson(compactInsightDigest(insights))}
 RESPOND WITH ONLY A VALID JSON OBJECT matching the schema.`
 }
 
+function buildFacetSystemPrompt(lang) {
+  return `You extract structured coding-session facets from compressed transcripts. Use only transcript evidence. Be conservative when evidence is weak. Do not infer intent from tool activity alone. ${getStructuredLanguageInstruction(lang)}`.trim()
+}
+
+function buildFacetExtractionPrompt(thread, transcript, lang) {
+  return `Analyze this Codex coding session and extract structured facets.
+
+CRITICAL GUIDELINES:
+1. goal_categories should count only what the user explicitly asked for.
+2. user_satisfaction_counts should rely on explicit user signals or strong transcript evidence.
+3. friction_counts should be specific: misunderstood_request, wrong_approach, buggy_code, user_rejected_action, excessive_changes, tool_failed, slow_or_verbose, user_unclear, external_issue.
+4. If the session is mostly warmup, rehearsal, or cache-filling, use warmup_minimal as the only goal category.
+5. If evidence is insufficient after transcript compression, use conservative values such as unclear_from_transcript rather than guessing.
+6. Do not infer the user's goal from assistant or tool activity alone.
+7. Do not count assistant-led exploration or extra implementation work unless the user clearly asked for it.
+
+Allowed values:
+- outcome: fully_achieved | mostly_achieved | partially_achieved | not_achieved | unclear_from_transcript
+- assistant_helpfulness: unhelpful | slightly_helpful | moderately_helpful | very_helpful | essential
+- session_type: single_task | multi_task | iterative_refinement | exploration | quick_question
+- primary_success: none | fast_accurate_search | correct_code_edits | good_explanations | proactive_help | multi_file_changes | good_debugging
+
+Language:
+- Keep enum values and keys exactly as requested.
+- Write free-text fields in ${describeLanguage(lang)}.
+
+Transcript:
+${transcript}
+
+Summary stats:
+${JSON.stringify(
+    {
+      title: thread.title,
+      cwd: thread.cwd,
+      durationMinutes: thread.durationMinutes,
+      userMessages: thread.userMessages,
+      assistantMessages: thread.assistantMessages,
+      totalToolCalls: thread.totalToolCalls,
+      totalCommandFailures: thread.totalCommandFailures,
+      toolCounts: thread.toolCounts,
+      toolFailures: thread.toolFailures,
+      userInterruptions: thread.userInterruptions,
+      usesTaskAgent: thread.usesTaskAgent,
+      usesMcp: thread.usesMcp,
+      usesWebSearch: thread.usesWebSearch,
+      usesWebFetch: thread.usesWebFetch,
+    },
+    null,
+    2,
+  )}
+
+RESPOND WITH ONLY A VALID JSON OBJECT matching the requested schema.`
+}
+
+function buildEstimatedFacet(thread) {
+  return {
+    threadId: thread.id,
+    title: thread.title,
+    cwd: thread.cwd,
+    updatedAt: thread.updatedAt,
+    durationMinutes: thread.durationMinutes,
+    userMessages: thread.userMessages,
+    assistantMessages: thread.assistantMessages,
+    totalToolCalls: thread.totalToolCalls,
+    totalCommandFailures: thread.totalCommandFailures,
+    underlying_goal: truncateForContext(thread.firstUserMessage || thread.title, 160),
+    goal_categories: {},
+    outcome: thread.totalCommandFailures > 0 ? 'partially_achieved' : 'unclear_from_transcript',
+    user_satisfaction_counts: {},
+    assistant_helpfulness: 'moderately_helpful',
+    session_type: thread.userMessages > 2 ? 'iterative_refinement' : 'single_task',
+    friction_counts: thread.totalCommandFailures > 0 ? { tool_failed: 1 } : {},
+    friction_detail: 'none',
+    primary_success: 'none',
+    brief_summary: truncateForContext(thread.firstUserMessage || thread.title, 180),
+    user_instructions: [],
+  }
+}
+
+function buildEstimatedInsightsPlaceholder(context) {
+  return {
+    project_areas: {
+      areas: (context.session_summaries || []).slice(0, 3).map((item, index) => ({
+        name: item.project || item.title || `Workstream ${index + 1}`,
+        session_count: 1,
+        description: truncateForContext(item.summary || item.goal || '', 120),
+      })),
+    },
+    interaction_style: {
+      key_pattern: 'Tight scope before execution',
+      narrative: truncateForContext('You first align scope and constraints, then execute and verify against explicit acceptance bars.', 180),
+    },
+    what_works: {
+      impressive_workflows: [
+        { title: 'Scope first', description: 'You repeatedly tighten scope before execution.' },
+        { title: 'Verification loop', description: 'You use evidence to confirm changes before closing.' },
+      ],
+    },
+    friction_analysis: {
+      categories: [
+        { category: 'Direction drift', description: 'Some sessions need scope tightening.', examples: ['Scope had to be pulled back.'] },
+      ],
+    },
+    suggestions: {
+      features_to_try: [{ feature: 'AGENTS.md' }],
+      usage_patterns: [{ title: 'Split review and execution' }],
+      agents_md_additions: [{ addition: 'Read existing docs before editing.' }],
+    },
+    on_the_horizon: {
+      opportunities: [{ title: 'Longer workflows', how_to_try: 'Add staged execution.' }],
+    },
+    fun_ending: {
+      headline: 'Memorable moment',
+      detail: 'A compact placeholder for estimate sizing.',
+    },
+  }
+}
+
 /**
  * @param {InsightRunOptions} options
  * @param {string} provider
@@ -1096,71 +1281,36 @@ function buildProviderOptions(options, provider, onUsage) {
   }
 }
 
-function estimateSectionInputs(candidateThreads, facetJobs) {
-  const contextShape = {
-    metadata: {
-      thread_count: candidateThreads.length,
-    },
-    summary: {
-      total_user_messages: candidateThreads.reduce((sum, thread) => sum + Number(thread.userMessages || 0), 0),
-      total_tool_calls: candidateThreads.reduce((sum, thread) => sum + Number(thread.totalToolCalls || 0), 0),
-      total_failures: candidateThreads.reduce((sum, thread) => sum + Number(thread.totalCommandFailures || 0), 0),
-    },
-    charts: {
-      projects: candidateThreads.slice(0, 6).map(thread => compactProjectPath(thread.cwd)),
-      models: Array.from(new Set(candidateThreads.map(thread => thread.model).filter(Boolean))).slice(0, 4),
-      tools: [],
-    },
-    aggregate_facets: {
-      sessions_with_facets: facetJobs.length,
-    },
-    session_summaries: facetJobs.slice(0, MAX_CONTEXT_FACETS).map(job => {
-      if (job.cachedFacet) {
-        return {
-          title: truncateForContext(job.cachedFacet.title, 80),
-          project: compactProjectPath(job.cachedFacet.cwd),
-          goal: truncateForContext(job.cachedFacet.underlying_goal, 120),
-          outcome: job.cachedFacet.outcome,
-          primary_success: job.cachedFacet.primary_success,
-          summary: truncateForContext(job.cachedFacet.brief_summary, 160),
-          friction: compactCountObject(job.cachedFacet.friction_counts, 2),
-        }
-      }
-      return {
-        title: truncateForContext(job.thread.title, 80),
-        project: compactProjectPath(job.thread.cwd),
-        goal: truncateForContext(job.thread.firstUserMessage, 120),
-        outcome: 'unknown',
-        primary_success: 'unknown',
-        summary: truncateForContext(job.thread.firstUserMessage, 160),
-        friction: {},
-      }
-    }),
-    recent_threads: candidateThreads.slice(0, MAX_RECENT_THREADS).map(thread => ({
-      title: truncateForContext(thread.title, 80),
-      project: compactProjectPath(thread.cwd),
-      duration_minutes: thread.durationMinutes,
-      user_messages: thread.userMessages,
-      tool_calls: thread.totalToolCalls,
-      files_modified: thread.filesModified,
-    })),
-    friction_details: [],
-    user_instructions: [],
-  }
-  const sectionKinds = [
-    'project_areas',
-    'interaction_style',
-    'what_works',
-    'friction_analysis',
-    'suggestions',
-    'on_the_horizon',
-    'fun_ending',
-    'at_a_glance',
-  ]
+function estimateSectionInputs(candidateThreads, facetJobs, options = {}) {
+  const provider = options.provider || DEFAULT_PROVIDER
+  const lang = options.lang || 'en'
+  const estimatedFacets = facetJobs.map(job => job.cachedFacet || buildEstimatedFacet(job.thread))
+  const report = buildReport(candidateThreads, { facets: estimatedFacets })
+  const context = buildInsightContext(report, candidateThreads, estimatedFacets)
   const estimated = {}
-  for (const kind of sectionKinds) {
-    estimated[kind] = estimateTokensFromChars(compactJson(buildSectionContext(contextShape, kind)).length)
+
+  for (const section of SECTION_DEFS) {
+    const systemPrompt = `${SECTION_SYSTEM_PROMPT} ${getNarrativeLanguageInstruction(lang)}`.trim()
+    const sectionContext = buildSectionContext(context, section.contextKind)
+    const userPrompt = `${section.prompt}\n\n${getNarrativeLanguageInstruction(lang)}\n\nDATA:\n${compactJson(sectionContext)}`
+    estimated[section.contextKind] = estimateModelInputTokens({
+      provider,
+      systemPrompt,
+      userPrompt,
+      schema: section.schema,
+      structured: true,
+    })
   }
+
+  const placeholderInsights = buildEstimatedInsightsPlaceholder(context)
+  estimated.at_a_glance = estimateModelInputTokens({
+    provider,
+    systemPrompt: `${AT_A_GLANCE_SYSTEM_PROMPT} ${getNarrativeLanguageInstruction(lang)}`.trim(),
+    userPrompt: buildAtAGlancePrompt(buildSectionContext(context, 'at_a_glance'), placeholderInsights),
+    schema: AT_A_GLANCE_SCHEMA,
+    structured: true,
+  })
+
   return estimated
 }
 
@@ -1321,6 +1471,36 @@ function estimateTokensFromChars(chars) {
   return Math.ceil(Number(chars || 0) / 4)
 }
 
+function estimateModelInputTokens({ provider, systemPrompt, userPrompt, schema = null, structured }) {
+  const promptText =
+    provider === 'codex-cli'
+      ? structured
+        ? buildStructuredEstimatePrompt(systemPrompt, userPrompt, schema)
+        : buildPlainEstimatePrompt(systemPrompt, userPrompt)
+      : buildApiEstimatePrompt(systemPrompt, userPrompt, schema, structured)
+  return estimateTokensFromChars(promptText.length)
+}
+
+function buildPlainEstimatePrompt(systemPrompt, userPrompt) {
+  return `${String(systemPrompt || '').trim()}\n\n${String(userPrompt || '').trim()}`
+}
+
+function buildStructuredEstimatePrompt(systemPrompt, userPrompt, schema) {
+  return `${buildPlainEstimatePrompt(systemPrompt, userPrompt)}\n\nRESPOND WITH ONLY A VALID JSON OBJECT matching this schema:\n${JSON.stringify(schema, null, 2)}`
+}
+
+function buildApiEstimatePrompt(systemPrompt, userPrompt, schema, structured) {
+  if (!structured) return buildPlainEstimatePrompt(systemPrompt, userPrompt)
+  return `${buildPlainEstimatePrompt(systemPrompt, userPrompt)}\n\nJSON schema:\n${JSON.stringify(schema, null, 2)}`
+}
+
+function makePlaceholderText(length, prefix = '') {
+  const target = Math.max(0, Number(length || 0))
+  const seed = prefix ? `${prefix}\n` : ''
+  if (seed.length >= target) return seed.slice(0, target)
+  return `${seed}${'x'.repeat(Math.max(0, target - seed.length))}`
+}
+
 function getNarrativeLanguageInstruction(lang) {
   if (lang === 'zh-CN') {
     return 'Write all free-text narrative fields in Simplified Chinese.'

package/lib/report.js

@@ -1,3 +1,4 @@
+import os from 'node:os'
 import path from 'node:path'
 import { promises as fs } from 'node:fs'
 
@@ -6,6 +7,9 @@ export function buildReport(threadSummaries, options = {}) {
   const modelCounts = {}
   const toolCounts = {}
   const commandKindCounts = {}
+  const capabilityCounts = {}
+  const outcomeCounts = {}
+  const sessionTypeCounts = {}
   const toolFailureCounts = {}
   const activeHourCounts = {}
   const responseTimes = []
@@ -81,8 +85,20 @@ export function buildReport(threadSummaries, options = {}) {
     if (thread.usesMcp) sessionsUsingMcp += 1
     if (thread.usesWebSearch) sessionsUsingWebSearch += 1
     if (thread.usesWebFetch) sessionsUsingWebFetch += 1
+    if (thread.filesModified > 0) increment(capabilityCounts, 'Repo edits')
+    if (thread.gitCommits > 0 || thread.gitPushes > 0) increment(capabilityCounts, 'Git activity')
   }
 
+  for (const facet of options.facets || []) {
+    if (facet.outcome) increment(outcomeCounts, facet.outcome)
+    if (facet.session_type) increment(sessionTypeCounts, facet.session_type)
+  }
+
+  if (sessionsUsingTaskAgent > 0) increment(capabilityCounts, 'Sub-agents', sessionsUsingTaskAgent)
+  if (sessionsUsingMcp > 0) increment(capabilityCounts, 'MCP servers', sessionsUsingMcp)
+  if (sessionsUsingWebSearch > 0) increment(capabilityCounts, 'Web search', sessionsUsingWebSearch)
+  if (sessionsUsingWebFetch > 0) increment(capabilityCounts, 'Web fetch', sessionsUsingWebFetch)
+
   const sortedThreads = [...threadSummaries].sort(
     (a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt),
   )
@@ -130,6 +146,9 @@ export function buildReport(threadSummaries, options = {}) {
       models: topEntries(modelCounts, 10),
       tools: topEntries(toolCounts, 12),
       commandKinds: topEntries(commandKindCounts, 12),
+      capabilities: topEntries(capabilityCounts, 8),
+      outcomes: topEntries(outcomeCounts, 8),
+      sessionTypes: topEntries(sessionTypeCounts, 8),
       toolFailures: topEntries(toolFailureCounts, 8),
       toolErrorCategories: topEntries(toolErrorCategoryCounts, 8),
       activeHours: buildHourSeries(activeHourCounts),
@@ -159,6 +178,7 @@ export async function writeReportFiles(report, options) {
 
 export function renderTerminalSummary(report) {
   const text = getReportText(report.metadata.language)
+  const estimateComparison = buildEstimateComparison(report)
   const lines = []
   lines.push(text.reportTitle)
   lines.push(
@@ -171,18 +191,23 @@ export function renderTerminalSummary(report) {
     lines.push(
       `  ${text.inputLabel}=${formatMillionTokens(report.analysisUsage.inputTokens)} | ${text.cachedLabel}=${formatMillionTokens(report.analysisUsage.cachedInputTokens)} | ${text.outputLabel}=${formatMillionTokens(report.analysisUsage.outputTokens)}`,
     )
+    if (estimateComparison) {
+      lines.push(
+        `  ${text.estimateVsActualLabel}: ${formatMillionTokens(estimateComparison.estimatedTotalTokens)} -> ${formatMillionTokens(estimateComparison.actualTotalTokens)} ${text.actualFreshSuffix} (${formatSignedMillionTokens(estimateComparison.deltaTokens)}, ${formatSignedPercent(estimateComparison.deltaPercent)})`,
+      )
+    }
   }
   if (report.metadata.dateRange.start && report.metadata.dateRange.end) {
     lines.push(`${report.metadata.dateRange.start} -> ${report.metadata.dateRange.end}`)
   }
   lines.push('')
-  lines.push(`${text.topTools}:`)
-  for (const item of report.charts.tools.slice(0, 5)) {
-    lines.push(`  ${item.label}: ${item.value}`)
-  }
-  lines.push('')
   lines.push(`${text.topProjects}:`)
   for (const item of report.charts.projects.slice(0, 5)) {
+    lines.push(`  ${formatProjectLabel(item.label)}: ${item.value}`)
+  }
+  lines.push('')
+  lines.push(`${text.modelMix}:`)
+  for (const item of report.charts.models.slice(0, 5)) {
     lines.push(`  ${item.label}: ${item.value}`)
   }
   return lines.join('\n')
@@ -193,9 +218,15 @@ function renderHtmlReport(report) {
   const insights = report.insights
   if (insights && !insights.__lang) insights.__lang = report.metadata.language
   const analysisUsage = report.analysisUsage || null
-  const topTools = renderBarList(report.charts.tools)
-  const topProjects = renderBarList(report.charts.projects)
-  const commandKinds = renderBarList(report.charts.commandKinds)
+  const topProjects = renderBarList(report.charts.projects, { formatLabel: formatProjectLabel })
+  const modelMix = renderBarList(report.charts.models)
+  const sessionTypes = renderBarList(report.charts.sessionTypes, {
+    formatLabel: value => formatSessionTypeLabel(value, report.metadata.language),
+  })
+  const outcomes = renderBarList(report.charts.outcomes, {
+    formatLabel: value => formatOutcomeLabel(value, report.metadata.language),
+  })
+  const capabilitySignals = renderBarList(report.charts.capabilities)
   const toolFailures = renderBarList(report.charts.toolFailures)
   const toolErrorCategories = renderBarList(report.charts.toolErrorCategories)
   const activeHours = renderHourHistogram(report.charts.activeHours)
@@ -639,7 +670,7 @@ function renderHtmlReport(report) {
       <section class="hero">
         <span class="eyebrow">${escapeHtml(text.eyebrow)}</span>
         <h1>${escapeHtml(text.reportTitle)}</h1>
-        <p class="meta">${escapeHtml(text.generatedLabel)} ${escapeHtml(report.metadata.generatedAt)} ${escapeHtml(text.generatedFrom)} ${report.metadata.threadCount} ${escapeHtml(text.substantiveThreads)} ${escapeHtml(text.inCodexHome)} ${escapeHtml(report.metadata.codexHome)}.</p>
+        <p class="meta">${escapeHtml(text.generatedLabel)} ${escapeHtml(report.metadata.generatedAt)} ${escapeHtml(text.generatedFrom)} ${report.metadata.threadCount} ${escapeHtml(text.substantiveThreads)} ${escapeHtml(text.inCodexHome)} ${escapeHtml(formatCodexHome(report.metadata.codexHome))}.</p>
         <div class="summary-grid">
           ${renderStat(text.userMessages, formatNumber(report.summary.totalUserMessages))}
           ${renderStat(text.toolCalls, formatNumber(report.summary.totalToolCalls))}
@@ -672,17 +703,25 @@ function renderHtmlReport(report) {
           ${renderOnTheHorizon(insights)}
         </div>
         <aside class="side-column">
-          <section class="chart-panel">
-            <h2>${escapeHtml(text.topTools)}</h2>
-            ${topTools}
-          </section>
           <section class="chart-panel">
             <h2>${escapeHtml(text.topProjects)}</h2>
             ${topProjects}
           </section>
           <section class="chart-panel">
-            <h2>${escapeHtml(text.commandKinds)}</h2>
-            ${commandKinds}
+            <h2>${escapeHtml(text.modelMix)}</h2>
+            ${modelMix}
+          </section>
+          <section class="chart-panel">
+            <h2>${escapeHtml(text.sessionTypes)}</h2>
+            ${sessionTypes}
+          </section>
+          <section class="chart-panel">
+            <h2>${escapeHtml(text.outcomes)}</h2>
+            ${outcomes}
+          </section>
+          <section class="chart-panel">
+            <h2>${escapeHtml(text.capabilitySignals)}</h2>
+            ${capabilitySignals}
           </section>
           <section class="chart-panel">
             <h2>${escapeHtml(text.failureHotspots)}</h2>
@@ -764,7 +803,7 @@ function renderProjectAreas(insights) {
               <div class="project-area">
                 <div class="area-header">
                   <span class="area-name">${escapeHtml(area.name)}</span>
-                  <span class="area-count">~${formatNumber(area.session_count)} ${escapeHtml(text.sessionsLabel)}</span>
+                  <span class="area-count">${escapeHtml(text.workstreamBadge)}</span>
                 </div>
                 <div class="area-desc">${escapeHtml(area.description)}</div>
               </div>
@@ -846,9 +885,9 @@ function renderSuggestions(insights) {
   const suggestions = insights.suggestions
   if (!suggestions) return ''
   const text = getReportText(insights.__lang)
-  const agentItems = suggestions.agents_md_additions || []
-  const featureItems = suggestions.features_to_try || []
-  const patternItems = suggestions.usage_patterns || []
+  const agentItems = (suggestions.agents_md_additions || []).map(normalizeSuggestionTextItem)
+  const featureItems = (suggestions.features_to_try || []).map(normalizeSuggestionTextItem)
+  const patternItems = (suggestions.usage_patterns || []).map(normalizeSuggestionTextItem)
 
   return `
     <section class="panel">
@@ -966,6 +1005,7 @@ function renderReportMeta(report, context = {}) {
   const text = getReportText(report.metadata.language)
   const usage = report.analysisUsage
   const hasUsage = Boolean(usage?.totalTokens)
+  const estimateComparison = buildEstimateComparison(report)
   const analysisByStage = context.analysisByStage || ''
   const analysisByModel = context.analysisByModel || ''
 
@@ -981,6 +1021,7 @@ function renderReportMeta(report, context = {}) {
         ${hasUsage ? renderStat(text.analysisTokens, formatMillionTokens(usage.totalTokens)) : ''}
         ${hasUsage ? renderStat(text.modelCalls, formatNumber(usage.calls)) : ''}
         ${hasUsage ? renderStat(text.cachedInput, formatMillionTokens(usage.cachedInputTokens)) : ''}
+        ${estimateComparison ? renderStat(text.estimateDelta, `${formatSignedMillionTokens(estimateComparison.deltaTokens)} (${formatSignedPercent(estimateComparison.deltaPercent)})`) : ''}
         ${renderStat(text.historicalSessionTokens, formatNumber(report.summary.totalTokens))}
       </div>
       ${
@@ -1006,6 +1047,14 @@ function renderReportMeta(report, context = {}) {
           })}
           <p class="meta">${escapeHtml(text.freshInput)}: ${formatMillionTokens(freshInputTokens)}. ${escapeHtml(text.analysisCostFootnote)}</p>
         </div>
+        ${
+          estimateComparison
+            ? `<div class="usage-breakdown">
+          <h3>${escapeHtml(text.estimateVsActualHeading)}</h3>
+          ${renderEstimateComparisonCard(estimateComparison, text)}
+        </div>`
+            : ''
+        }
       </div>`
           : ''
       }
@@ -1050,19 +1099,43 @@ function renderUsageCard(item) {
   `
 }
 
+function renderEstimateComparisonCard(comparison, text) {
+  return `
+    <div class="usage-card">
+      <div class="topline">
+        <h3>${escapeHtml(text.estimateVsActualLabel)}</h3>
+        <span class="pill">${escapeHtml(comparison.verdictLabel)}</span>
+      </div>
+      <div class="meta-row">
+        <span>${escapeHtml(text.estimatedLabel)}: ${formatMillionTokens(comparison.estimatedTotalTokens)}</span>
+        <span>${escapeHtml(text.actualFreshLabel)}: ${formatMillionTokens(comparison.actualTotalTokens)}</span>
+        <span>${escapeHtml(text.estimateDelta)}: ${formatSignedMillionTokens(comparison.deltaTokens)} (${formatSignedPercent(comparison.deltaPercent)})</span>
+      </div>
+      <div class="token-row">
+        <div class="token-box"><strong>${escapeHtml(text.estimatedLabel)}</strong><br>${formatMillionTokens(comparison.estimatedTotalTokens)}</div>
+        <div class="token-box"><strong>${escapeHtml(text.actualFreshLabel)}</strong><br>${formatMillionTokens(comparison.actualTotalTokens)}</div>
+        <div class="token-box"><strong>${escapeHtml(text.estimateRangeLabel)}</strong><br>${formatMillionTokens(comparison.lowEstimate)} -> ${formatMillionTokens(comparison.highEstimate)}</div>
+        <div class="token-box"><strong>${escapeHtml(text.estimateDelta)}</strong><br>${formatSignedMillionTokens(comparison.deltaTokens)}</div>
+        <div class="token-box"><strong>${escapeHtml(text.estimateError)}</strong><br>${formatSignedPercent(comparison.deltaPercent)}</div>
+      </div>
+    </div>
+  `
+}
+
 function renderStat(label, value) {
   return `<div class="stat"><div class="value">${escapeHtml(String(value))}</div><div>${escapeHtml(label)}</div></div>`
 }
 
-function renderBarList(items) {
+function renderBarList(items, options = {}) {
   if (!items.length) return '<p class="meta">No data available.</p>'
+  const formatLabel = options.formatLabel || (value => value)
   const maxValue = Math.max(...items.map(item => item.value), 1)
   return `<div class="bar-list">${items
     .map(
       item => `
         <div class="bar-row">
           <div class="bar-label">
-            <span>${escapeHtml(item.label)}</span>
+            <span>${escapeHtml(formatLabel(item.label))}</span>
             <strong>${formatNumber(item.value)}</strong>
           </div>
           <div class="bar-track"><div class="bar-fill" style="width:${Math.max(6, (item.value / maxValue) * 100)}%"></div></div>
@@ -1117,6 +1190,20 @@ function renderCopyRow(value, text) {
   `
 }
 
+function normalizeSuggestionTextItem(item) {
+  if (!item || typeof item !== 'object') return item
+  return Object.fromEntries(
+    Object.entries(item).map(([key, value]) => [key, normalizeSuggestionText(value)]),
+  )
+}
+
+function normalizeSuggestionText(value) {
+  if (typeof value !== 'string') return value
+  return value
+    .replaceAll('CLAUDE.md / AGENTS.md', 'AGENTS.md')
+    .replaceAll('CLAUDE.md', 'AGENTS.md')
+}
+
 function formatAgentInstruction(item) {
   const placement = String(item?.prompt_scaffold || '').trim()
   const addition = String(item?.addition || '').trim()
@@ -1133,6 +1220,74 @@ function topEntries(map, limit) {
     .map(([label, value]) => ({ label, value }))
 }
 
+function formatCodexHome(value) {
+  return formatDisplayPath(value, { tailSegments: 2, preferHomeAlias: true, ellipsis: false })
+}
+
+function formatProjectLabel(value) {
+  return formatDisplayPath(value, { tailSegments: 2, preferHomeAlias: false, ellipsis: true })
+}
+
+function formatSessionTypeLabel(value, lang) {
+  const key = String(value || '')
+  const zh = {
+    iterative_refinement: '反复收敛',
+    exploration: '探索调研',
+    single_task: '单任务推进',
+    multi_task: '多任务并行',
+    quick_question: '快速提问',
+  }
+  const en = {
+    iterative_refinement: 'Iterative refinement',
+    exploration: 'Exploration',
+    single_task: 'Single-task execution',
+    multi_task: 'Multi-task coordination',
+    quick_question: 'Quick question',
+  }
+  return lang === 'zh-CN' ? zh[key] || key : en[key] || key
+}
+
+function formatOutcomeLabel(value, lang) {
+  const key = String(value || '')
+  const zh = {
+    fully_achieved: '完全达成',
+    mostly_achieved: '基本达成',
+    partially_achieved: '部分达成',
+    not_achieved: '未达成',
+    unclear_from_transcript: '从记录中无法判断',
+  }
+  const en = {
+    fully_achieved: 'Fully achieved',
+    mostly_achieved: 'Mostly achieved',
+    partially_achieved: 'Partially achieved',
+    not_achieved: 'Not achieved',
+    unclear_from_transcript: 'Unclear from transcript',
+  }
+  return lang === 'zh-CN' ? zh[key] || key : en[key] || key
+}
+
+function formatDisplayPath(value, options = {}) {
+  const text = String(value || '').trim()
+  if (!text) return '(unknown)'
+
+  const normalized = text.replace(/\\/g, '/')
+  const home = os.homedir().replace(/\\/g, '/')
+  if (options.preferHomeAlias !== false && normalized === home) return '~'
+  if (options.preferHomeAlias !== false && normalized.startsWith(`${home}/`)) {
+    return `~/${normalized.slice(home.length + 1)}`
+  }
+
+  const parts = normalized.split('/').filter(Boolean)
+  const tailSegments = Math.max(1, Number(options.tailSegments || 2))
+  if (parts.length <= tailSegments) {
+    return normalized.startsWith('/') ? `/${parts.join('/')}` : parts.join('/')
+  }
+
+  const tail = parts.slice(-tailSegments).join('/')
+  if (options.ellipsis === false) return tail
+  return `…/${tail}`
+}
+
 function buildHourSeries(hourMap) {
   return Array.from({ length: 24 }, (_, hour) => ({
     hour,
@@ -1165,6 +1320,12 @@ function formatMillionTokens(value) {
   return `${round(number / 1_000)}K tokens`
 }
 
+function formatSignedMillionTokens(value) {
+  const number = Number(value || 0)
+  const prefix = number > 0 ? '+' : number < 0 ? '-' : ''
+  return `${prefix}${formatMillionTokens(Math.abs(number))}`
+}
+
 function formatPercent(value, total) {
   const numerator = Number(value || 0)
   const denominator = Number(total || 0)
@@ -1172,6 +1333,12 @@ function formatPercent(value, total) {
   return `${round((numerator / denominator) * 100)}%`
 }
 
+function formatSignedPercent(value) {
+  const number = Number(value || 0)
+  const prefix = number > 0 ? '+' : number < 0 ? '-' : ''
+  return `${prefix}${round(Math.abs(number))}%`
+}
+
 function average(values) {
   if (!values.length) return 0
   return round(values.reduce((sum, value) => sum + value, 0) / values.length)
@@ -1226,6 +1393,41 @@ function escapeAttribute(value) {
   return escapeHtml(String(value)).replaceAll("'", '&#39;').replaceAll('\n', '&#10;')
 }
 
+function buildEstimateComparison(report) {
+  const estimate = report.analysisEstimate
+  const usage = report.analysisUsage
+  if (!estimate?.estimatedTotalTokens || !usage?.totalTokens) return null
+
+  const estimated = Number(estimate.estimatedTotalTokens || 0)
+  const actualFresh =
+    Math.max(0, Number(usage.inputTokens || 0) - Number(usage.cachedInputTokens || 0)) +
+    Number(usage.outputTokens || 0)
+  const delta = actualFresh - estimated
+  const deltaPercent = estimated > 0 ? (delta / estimated) * 100 : 0
+
+  return {
+    estimatedTotalTokens: estimated,
+    actualTotalTokens: actualFresh,
+    lowEstimate: Number(estimate.estimatedRange?.low || estimated),
+    highEstimate: Number(estimate.estimatedRange?.high || estimated),
+    deltaTokens: delta,
+    deltaPercent,
+    verdictLabel: classifyEstimateDelta(deltaPercent, report.metadata.language),
+  }
+}
+
+function classifyEstimateDelta(deltaPercent, lang) {
+  const abs = Math.abs(Number(deltaPercent || 0))
+  if (lang === 'zh-CN') {
+    if (abs <= 10) return '估算接近'
+    if (deltaPercent > 0) return '实际偏高'
+    return '实际偏低'
+  }
+  if (abs <= 10) return 'Close estimate'
+  if (deltaPercent > 0) return 'Actual higher'
+  return 'Actual lower'
+}
+
 function getReportText(lang) {
   if (lang === 'zh-CN') {
     return {
@@ -1244,9 +1446,11 @@ function getReportText(lang) {
       filesModified: '修改文件',
       toolErrors: '工具错误',
       avgResponse: '平均响应',
-      topTools: 'Top Tools',
-      topProjects: 'Top Projects',
-      commandKinds: '命令类型',
+      topProjects: '项目分布',
+      modelMix: '模型分布',
+      sessionTypes: '会话类型',
+      outcomes: '结果分布',
+      capabilitySignals: '能力信号',
       failureHotspots: '失败热点',
       errorCategories: '错误分类',
       timeOfDay: '活跃时段',
@@ -1256,6 +1460,7 @@ function getReportText(lang) {
       quickWins: '可以立刻尝试的优化',
       ambitiousWorkflows: '值得尝试的更强工作流',
       sessionsLabel: '次会话',
+      workstreamBadge: '代表性工作流',
       impressiveThingsLink: '做得好的地方',
       whereThingsGoWrongLink: '容易出问题的地方',
       whatYouWorkOn: '你主要在做什么',
@@ -1286,6 +1491,15 @@ function getReportText(lang) {
       dateRange: '时间范围',
       modelCalls: '模型调用',
       cachedInput: '缓存输入',
+      estimatedLabel: '预估',
+      actualLabel: '实际',
+      actualFreshLabel: '实际（不含缓存）',
+      actualFreshSuffix: '（不含缓存）',
+      estimateRangeLabel: '预估区间',
+      estimateVsActualHeading: '预估与实际',
+      estimateVsActualLabel: '预估 vs 实际',
+      estimateDelta: '偏差',
+      estimateError: '偏差比例',
       historicalSessionTokens: '历史会话 Tokens',
       analysisCostByStage: '按阶段拆分的分析成本',
       analysisCostByModel: '按模型拆分的分析成本',
@@ -1321,9 +1535,11 @@ function getReportText(lang) {
     filesModified: 'Files Modified',
     toolErrors: 'Tool Errors',
     avgResponse: 'Avg Response',
-    topTools: 'Top Tools',
     topProjects: 'Top Projects',
-    commandKinds: 'Command Kinds',
+    modelMix: 'Model Mix',
+    sessionTypes: 'Session Types',
+    outcomes: 'Outcomes',
+    capabilitySignals: 'Capability Signals',
     failureHotspots: 'Failure Hotspots',
     errorCategories: 'Error Categories',
     timeOfDay: 'Time of Day',
@@ -1333,6 +1549,7 @@ function getReportText(lang) {
     quickWins: 'Quick wins to try',
     ambitiousWorkflows: 'Ambitious workflows',
     sessionsLabel: 'sessions',
+    workstreamBadge: 'Representative workstream',
     impressiveThingsLink: 'Impressive Things You Did',
     whereThingsGoWrongLink: 'Where Things Go Wrong',
     whatYouWorkOn: 'What You Work On',
@@ -1363,6 +1580,15 @@ function getReportText(lang) {
     dateRange: 'Date Range',
     modelCalls: 'Model Calls',
     cachedInput: 'Cached Input',
+    estimatedLabel: 'Estimated',
+    actualLabel: 'Actual',
+    actualFreshLabel: 'Actual (fresh)',
+    actualFreshSuffix: '(fresh)',
+    estimateRangeLabel: 'Estimate range',
+    estimateVsActualHeading: 'Estimate vs Actual',
+    estimateVsActualLabel: 'Estimate vs Actual',
+    estimateDelta: 'Delta',
+    estimateError: 'Error',
     historicalSessionTokens: 'Historical Session Tokens',
     analysisCostByStage: 'Analysis Cost by Stage',
     analysisCostByModel: 'Analysis Cost by Model',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-session-insights",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Generate a report analyzing your Codex sessions.",
   "type": "module",
   "bin": {
@@ -25,6 +25,7 @@
   },
   "scripts": {
     "report": "node ./bin/codex-insights.js report",
+    "report:lite": "node ./bin/codex-insights.js --preset lite --yes",
     "generate:test-report": "node ./scripts/generate-test-report.mjs",
     "test": "node --test",
     "check": "node --check ./bin/codex-insights.js && node --check ./lib/cli.js && node --check ./lib/codex-data.js && node --check ./lib/report.js && node --check ./lib/llm-insights.js && node --check ./lib/model-provider.js && npm run typecheck",