pi-fluency 0.1.3 → 0.2.1

package/README.md

@@ -6,6 +6,7 @@ Pi Fluency analyzes human-authored prompts, lets you review possible English mis
 
 - Reviews only interactive prompts you write
 - Groups repeated findings into concrete recurring patterns
+- Offers optional submit-time practice for recurring rules you select
 - Tracks accepted mistakes per 1,000 English words
 - Keeps one-off mistakes out of recurring-pattern counts
 - Works across Pi projects and sessions
@@ -42,22 +43,42 @@ Requires Pi 0.80.10 or newer.
 pi install npm:pi-fluency
 ```
 
-Run `/reload`, then `/fluency`. Choose an available analysis model and confirm provider disclosure. Analysis remains off until setup completes.
+Run `/reload`, then `/fluency`. Choose an available analysis model and confirm provider disclosure for background analytics. Analysis remains off until setup completes. Optional preflight practice stays off until first Space selection atomically records preflight consent, enables practice, and selects focused rule.
 
 Useful commands:
 
 | Command | Action |
 | --- | --- |
 | `/fluency` | Set up Pi Fluency or open Inbox |
-| `/fluency stats` | Open 30-day analytics |
+| `/fluency stats` | Open 30-day analytics and choose recurring rules |
+| `/fluency practice` | Open Stats |
+| `/fluency practice on` / `off` | Enable or bypass selected-rule practice |
+| `/fluency practice resume` | End current session and five-hour snoozes |
+| `/fluency practice reset` | Confirm, then clear practice selections and consent |
 | `/fluency pause` | Pause analysis and hide toolbar status |
 | `/fluency resume` | Resume analysis |
 | `/fluency model` | Change analysis model |
-| `/fluency status` | Show model, queue, and storage status |
-| `/fluency clear` | Confirm, then clear coaching and analytics history |
+| `/fluency status` | Show model, queue, storage, and practice status |
+| `/fluency clear` | Confirm, then clear coaching and analytics history; preserve practice selections |
 
 `Ctrl+Shift+L` opens Inbox after setup.
 
+## Practice selected rules
+
+Practice is an optional analytical aid, not comprehensive grammar checking, automatic correction, or English instruction. Stats shows recurring rules as inline `[ ]` or `[x]` rows. First rule starts focused; use Up/Down or `j`/`k` to move focus and keep focused row in view, then press Space to toggle it. First Space records preflight consent, enables practice, and selects focused rule atomically; no separate consent prompt opens. This consent means eligible sanitized prompt prose may reach configured Fluency model before main request proceeds, including a draft you later keep instead of sending.
+
+For idle, text-only interactive prompts, Pi Fluency checks selected rules at submit time. This sends full sanitized prose from eligible prompt to analysis provider and can add provider latency, bounded to one attempt with a maximum 30-second cap. Successful checks proceed immediately, and pressing Enter while checking bypasses the check. Editor keeps exact text Pi Fluency received while check runs. Clean result proceeds normally. Match opens checkpoint without rewriting text:
+
+- **Edit** or **Esc** blocks submission and leaves received text in editor.
+- **Send once** starts focused; press Enter to proceed once and keep practice active for later prompts.
+- **Snooze session** proceeds once and bypasses checks for current conversation session, including reload or resume of same session file.
+- **Snooze 5 hours** proceeds once and bypasses checks across Pi sessions until deadline.
+- While checking, Enter selects **Send unchecked**, cancels bounded check, and proceeds; **Esc** returns to Edit.
+
+Use `/fluency practice resume` to end either snooze. Technical errors, busy or timed-out analysis fail open and attempt to send unchecked. If editor cannot be cleared safely, Pi Fluency does not send and leaves draft visible. Adapter that ignores cancellation is quarantined process-locally: later prompts send unchecked without growing analysis queue until call settles or Pi process restarts.
+
+Successful preflight result is reused for normal analytics. Edit/Esc attempt adds no Pi Fluency history; later edited submission is checked again. Practice selections are separate from history, so `/fluency clear` preserves them. Ignoring selected rule pauses matching practice until rule is restored.
+
 ## What it measures
 
 Pi Fluency counts only findings you accept. Every analyzer-classified English prompt contributes to word totals, including prompts with no findings.
@@ -66,7 +87,7 @@ Pi Fluency counts only findings you accept. Every analyzer-classified English pr
 accepted mistake rate = accepted occurrences / English words × 1000
 ```
 
-Stats covers trailing 30 local calendar days. It shows accepted rate, review coverage, one-off total, recurring patterns, and trends. Pattern list is sorted by accepted occurrence count. Pattern becomes recurring after accepted findings appear in at least two distinct prompts across retained history; one-offs remain in overall accepted totals and rate but stay out of recurring-pattern list and toolbar count.
+Stats covers trailing 30 local calendar days. Its normalized chart always has 30 positions, labeled from `30 days ago` through `today`; `·` means no English words were recorded for that local day. It also shows accepted rate, review coverage, one-off total, recurring patterns, and trends. Pattern list is sorted by accepted occurrence count. Pattern becomes recurring after accepted findings appear in at least two distinct prompts across retained history; one-offs remain in overall accepted totals and rate but stay out of recurring-pattern list and toolbar count.
 
 Toolbar summarizes current activity and accepted-mistake trends:
 
@@ -89,6 +110,10 @@ Local analytics live under `~/.pi/agent/pi-fluency/`. History contains hashes, d
 
 Model findings can be incomplete or wrong. Accept only findings you agree with. Pi Fluency measures reviewed writing patterns; it does not assess fluency, guarantee improvement, or replace human instruction.
 
+Preflight does not run for image-bearing submissions, slash commands, code-only input, RPC or extension-injected input, or active-stream `steer` / `followUp` input. Those boundaries avoid attachment loss and agent-control delays; eligible prompts may still use background analytics. Practice checks only selected concrete rules, so no checkpoint means neither proof that text is correct nor comprehensive analysis.
+
+Input-handler order limits draft provenance. Extensions running before Pi Fluency can alter text Pi Fluency receives and can therefore alter text restored for Edit. Extensions running after Pi Fluency can alter or intercept text Pi Fluency allowed, so analyzed text is not guaranteed to equal final sent text. Place text-transforming or intercepting extensions compatibly; Pi Fluency cannot enforce original editor bytes or final send order.
+
 ## Project
 
 Product idea and product decisions are by Ihar Trafimovich. All code, tests, and documentation were written by AI.

package/extensions/pi-fluency/analytics.ts

@@ -1,8 +1,13 @@
+import { createHash } from "node:crypto";
 import { errantCategory } from "./taxonomy.js";
 import type {
   EnglishObservation,
   MistakeOccurrence,
   MistakePattern,
+  PracticeAnalysisContext,
+  PracticeMistakeCandidate,
+  PracticeTarget,
+  ResolvedPracticeTarget,
 } from "./types.js";
 import type { ErrantCategory } from "./taxonomy.js";
 
@@ -10,6 +15,8 @@ const ENGLISH_WORD = /[\p{L}\p{N}]+(?:['’][\p{L}\p{N}]+)*/gu;
 const SPARK_GLYPHS = "▁▂▃▄▅▆▇█";
 const DATE_KEY = /^\d{4}-\d{2}-\d{2}$/;
 const TREND_DAYS = 30;
+const MAX_KNOWN_PATTERNS = 500;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
 
 /** Count word-like runs after the analyzer has classified sanitized prose as English. */
 export function countEnglishWords(prose: string): number {
@@ -20,7 +27,11 @@ export type RuleTrend = "improving" | "worsening" | "stable" | "new";
 
 export interface RuleAnalytics {
   patternId: string;
+  /** Deterministic UI identity derived from explanation; never persist or render it. */
+  rowKey: string;
   explanation: string;
+  /** Complete current group membership for durable selection. Never render it. */
+  memberPatternKeys: string[];
   accepted: number;
   ratePerThousand: number | undefined;
   sparkline: string;
@@ -35,6 +46,7 @@ export interface FluencyAnalytics {
   currentRatePerThousand?: number;
   periodRatePerThousand?: number;
   toolbarSparkline: string;
+  dailyRateSparkline: string;
   englishWords: number;
   accepted: number;
   dismissed: number;
@@ -71,6 +83,19 @@ export function renderSparkline(values: Array<number | undefined>): string {
   }).join("");
 }
 
+function renderDailyRateSparkline(values: Array<number | undefined>): string {
+  const finite = values.filter((value): value is number =>
+    typeof value === "number" && Number.isFinite(value));
+  if (finite.length === 0) return values.map(() => "·").join("");
+  const maximum = Math.max(...finite);
+  return values.map((value) => {
+    if (value === undefined || !Number.isFinite(value)) return "·";
+    if (maximum <= 0) return SPARK_GLYPHS[0]!;
+    const index = Math.round(value / maximum * (SPARK_GLYPHS.length - 1));
+    return SPARK_GLYPHS[Math.max(0, Math.min(SPARK_GLYPHS.length - 1, index))]!;
+  }).join("");
+}
+
 export function classifyRuleTrend(
   current: number | undefined,
   previous: number | undefined,
@@ -116,6 +141,122 @@ interface RuleGroup {
   patternId: string;
   explanation: string;
   patternIds: Set<string>;
+  memberPatternKeys: Set<string>;
+}
+
+function assertValidTarget(target: PracticeTarget): void {
+  if (target.explanation.length === 0 || target.explanation.length > 500
+    || CONTROL_CHARACTER.test(target.explanation)
+    || target.memberPatternKeys.length === 0 || target.memberPatternKeys.length > 500
+    || target.memberPatternKeys.some((key) => key.length === 0 || key.length > 500 || CONTROL_CHARACTER.test(key))) {
+    throw new Error("Invalid practice target");
+  }
+}
+
+function copyTarget(target: PracticeTarget): PracticeTarget {
+  assertValidTarget(target);
+  return { explanation: target.explanation, memberPatternKeys: [...target.memberPatternKeys] };
+}
+
+/** Stable transient identity for a concrete rule row. Never persist or display this value. */
+export function practiceRuleRowKey(explanation: string): string {
+  if (explanation.length === 0 || explanation.length > 500 || CONTROL_CHARACTER.test(explanation)) {
+    throw new Error("Invalid practice target");
+  }
+  return `rule-${createHash("sha256").update(explanation).digest("hex").slice(0, 16)}`;
+}
+
+export interface ResolvePracticeTargetsInput {
+  targets: readonly PracticeTarget[];
+  patterns: readonly MistakePattern[];
+  ignoredPatternKeys: ReadonlySet<string>;
+  ignoredCategories: ReadonlySet<ErrantCategory>;
+}
+
+/** Project durable selections against current patterns without mutating either input. */
+export function resolvePracticeTargets(input: ResolvePracticeTargetsInput): ResolvedPracticeTarget[] {
+  return input.targets.map((target) => {
+    assertValidTarget(target);
+    const durableKeys = new Set(target.memberPatternKeys);
+    const current = input.patterns.filter((pattern) =>
+      durableKeys.has(pattern.patternKey) || pattern.explanation === target.explanation);
+    const currentByKey = new Map(current.map((pattern) => [pattern.patternKey, pattern]));
+    const memberPatternKeys = [...new Set([
+      ...target.memberPatternKeys,
+      ...current.map((pattern) => pattern.patternKey),
+    ])].sort((left, right) => left.localeCompare(right));
+    const coachingEnabled = memberPatternKeys.some((patternKey) => {
+      if (input.ignoredPatternKeys.has(patternKey)) return false;
+      const pattern = currentByKey.get(patternKey);
+      return pattern === undefined || !input.ignoredCategories.has(errantCategory(pattern.errorType));
+    });
+    return {
+      rowKey: practiceRuleRowKey(target.explanation),
+      explanation: target.explanation,
+      memberPatternKeys,
+      currentPatternKeys: [...new Set(current.map((pattern) => pattern.patternKey))]
+        .sort((left, right) => left.localeCompare(right)),
+      coachingEnabled,
+    };
+  });
+}
+
+/** Return matching selected target unless candidate is suppressed by Ignore policy. */
+export function selectedTargetForMistake(
+  candidate: PracticeMistakeCandidate,
+  targets: readonly PracticeTarget[],
+  ignoredPatternKeys: ReadonlySet<string>,
+  ignoredCategories: ReadonlySet<ErrantCategory>,
+): PracticeTarget | undefined {
+  for (const target of targets) assertValidTarget(target);
+  if (CONTROL_CHARACTER.test(candidate.explanation) || CONTROL_CHARACTER.test(candidate.patternKey)) {
+    throw new Error("Invalid practice candidate");
+  }
+  if (ignoredPatternKeys.has(candidate.patternKey)
+    || ignoredCategories.has(errantCategory(candidate.errorType))) return undefined;
+  const target = targets.find((item) =>
+    item.explanation === candidate.explanation || item.memberPatternKeys.includes(candidate.patternKey));
+  return target === undefined ? undefined : copyTarget(target);
+}
+
+function comparePatternRecency(left: MistakePattern, right: MistakePattern): number {
+  return right.lastSeenAt - left.lastSeenAt
+    || left.patternKey.localeCompare(right.patternKey)
+    || left.id.localeCompare(right.id);
+}
+
+/** Prioritize selected patterns while keeping complete target descriptors outside bounded context. */
+export function selectPracticeAnalysisContext(
+  targets: readonly PracticeTarget[],
+  patterns: readonly MistakePattern[],
+  maximumPatterns = MAX_KNOWN_PATTERNS,
+): PracticeAnalysisContext {
+  if (!Number.isSafeInteger(maximumPatterns) || maximumPatterns < 0) {
+    throw new Error("Invalid known pattern limit");
+  }
+  const targetDescriptors = targets.map(copyTarget);
+  const selected: MistakePattern[] = [];
+  const selectedIds = new Set<string>();
+  for (const target of targetDescriptors) {
+    const memberKeys = new Set(target.memberPatternKeys);
+    const matches = patterns
+      .filter((pattern) => memberKeys.has(pattern.patternKey) || pattern.explanation === target.explanation)
+      .sort(comparePatternRecency);
+    for (const pattern of matches) {
+      if (selectedIds.has(pattern.id)) continue;
+      selectedIds.add(pattern.id);
+      selected.push(pattern);
+    }
+  }
+  const remaining = patterns
+    .filter((pattern) => !selectedIds.has(pattern.id))
+    .sort(comparePatternRecency);
+  return {
+    targetDescriptors,
+    patterns: [...selected, ...remaining]
+      .slice(0, maximumPatterns)
+      .map((pattern) => ({ ...pattern })),
+  };
 }
 
 export function computeFluencyAnalytics(input: AnalyticsInput): FluencyAnalytics {
@@ -149,6 +290,11 @@ export function computeFluencyAnalytics(input: AnalyticsInput): FluencyAnalytics
     const window = totals(end, 7);
     return ratePerThousand(window.accepted, window.words);
   });
+  const dailyRates = Array.from({ length: TREND_DAYS }, (_, index) => {
+    const date = shiftDate(today, index - (TREND_DAYS - 1));
+    const day = totals(date, 1);
+    return ratePerThousand(day.accepted, day.words);
+  });
   const currentSeven = totals(today, 7);
   const currentThirty = totals(today, TREND_DAYS);
   const previousEnd = shiftDate(today, -TREND_DAYS);
@@ -168,12 +314,14 @@ export function computeFluencyAnalytics(input: AnalyticsInput): FluencyAnalytics
     const existing = groupsByExplanation.get(explanation);
     if (existing) {
       existing.patternIds.add(pattern.id);
+      existing.memberPatternKeys.add(pattern.patternKey);
       if (pattern.id.localeCompare(existing.patternId) < 0) existing.patternId = pattern.id;
     } else {
       groupsByExplanation.set(explanation, {
         patternId: pattern.id,
         explanation,
         patternIds: new Set([pattern.id]),
+        memberPatternKeys: new Set([pattern.patternKey]),
       });
     }
   }
@@ -217,7 +365,9 @@ export function computeFluencyAnalytics(input: AnalyticsInput): FluencyAnalytics
       : undefined;
     return [{
       patternId: group.patternId,
+      rowKey: practiceRuleRowKey(group.explanation),
       explanation: group.explanation,
+      memberPatternKeys: [...group.memberPatternKeys].sort((left, right) => left.localeCompare(right)),
       accepted,
       ratePerThousand: currentRate,
       sparkline: renderSparkline(sparklineValues),
@@ -245,6 +395,7 @@ export function computeFluencyAnalytics(input: AnalyticsInput): FluencyAnalytics
     ...(currentRatePerThousand === undefined ? {} : { currentRatePerThousand }),
     ...(periodRatePerThousand === undefined ? {} : { periodRatePerThousand }),
     toolbarSparkline: renderSparkline(trailingRates),
+    dailyRateSparkline: renderDailyRateSparkline(dailyRates),
     englishWords: currentThirty.words,
     accepted: currentThirty.accepted,
     dismissed: currentThirty.dismissed,

package/extensions/pi-fluency/analyzer.ts

@@ -6,6 +6,7 @@ import {
   type AnalysisResult,
   type CollectedPrompt,
   type MistakePattern,
+  type PracticeTarget,
   type RawAnalysisResult,
 } from "./types.js";
 import {
@@ -29,16 +30,39 @@ export interface Analyzer {
     prompt: CollectedPrompt,
     activePatterns: MistakePattern[],
     signal: AbortSignal,
+    selectedTargets?: readonly PracticeTarget[],
   ): Promise<AnalysisResult>;
 }
 
-export function buildAnalysisPrompt(prompt: CollectedPrompt, activePatterns: MistakePattern[]): string {
-  const knownPatterns = activePatterns
+function selectedPatternKeys(
+  activePatterns: readonly MistakePattern[],
+  selectedTargets: readonly PracticeTarget[],
+): Set<string> {
+  const selectedKeys = new Set(selectedTargets.flatMap((target) => target.memberPatternKeys));
+  const selectedExplanations = new Set(selectedTargets.map((target) => target.explanation));
+  return new Set(activePatterns
+    .filter((pattern) => selectedKeys.has(pattern.patternKey) || selectedExplanations.has(pattern.explanation))
+    .map((pattern) => pattern.patternKey));
+}
+
+export function buildAnalysisPrompt(
+  prompt: CollectedPrompt,
+  activePatterns: MistakePattern[],
+  selectedTargets: readonly PracticeTarget[] = [],
+): string {
+  const priorityKeys = selectedPatternKeys(activePatterns, selectedTargets);
+  const orderedPatterns = [
+    ...activePatterns.filter((pattern) => priorityKeys.has(pattern.patternKey)),
+    ...activePatterns.filter((pattern) => !priorityKeys.has(pattern.patternKey)),
+  ];
+  const knownPatterns = orderedPatterns
     .slice(0, MAX_KNOWN_PATTERNS)
     .map(({ patternKey, explanation, errorType }) => ({ patternKey, explanation, errorType }));
+  const includedKeys = new Set(knownPatterns.map((pattern) => pattern.patternKey));
   return JSON.stringify({
     prose: prompt.prose,
     knownPatterns,
+    priorityPatternKeys: [...priorityKeys].filter((key) => includedKeys.has(key)),
     allowedErrorTypes: ERRANT_ERROR_TYPES,
     allowedContextScopes: CONTEXT_SCOPES,
   });
@@ -108,6 +132,7 @@ Do not report style preferences, capitalization of product names, or informal-bu
 A demonstrated fix must match one supplied knownPatterns pattern and quote comparable correct evidence.
 Never infer a demonstrated fix merely because an earlier mistake is absent.
 Reuse an existing knownPatterns patternKey for the same rule; mint a new namespaced lowercase key only when no known rule matches.
+Check priorityPatternKeys carefully before other known patterns. This changes attention only; still return every genuine finding in the full prose.
 Keep every explanation under 240 characters. Return JSON only.`;
 
 export class ModelAnalyzer implements Analyzer {
@@ -121,6 +146,7 @@ export class ModelAnalyzer implements Analyzer {
     prompt: CollectedPrompt,
     activePatterns: MistakePattern[],
     signal: AbortSignal,
+    selectedTargets: readonly PracticeTarget[] = [],
   ): Promise<AnalysisResult> {
     let auth: Awaited<ReturnType<ModelRegistry["getApiKeyAndHeaders"]>>;
     try {
@@ -134,7 +160,7 @@ export class ModelAnalyzer implements Analyzer {
 
     const message: UserMessage = {
       role: "user",
-      content: buildAnalysisPrompt(prompt, activePatterns),
+      content: buildAnalysisPrompt(prompt, activePatterns, selectedTargets),
       timestamp: Date.now(),
     };
     const response = await complete(

package/extensions/pi-fluency/coaching-overlay.ts

@@ -0,0 +1,259 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import { sanitizeTerminalLabel } from "./sanitize.js";
+import type { AnalyzerMistake, PracticeTarget } from "./types.js";
+
+export type CoachingOverlayDecision =
+  | "edit"
+  | "send-unchecked"
+  | "send-once"
+  | "snooze-session"
+  | "snooze-five-hours"
+  | "clean"
+  | "technical-failure";
+
+export type CoachingCheckResult =
+  | { kind: "matches"; mistakes: AnalyzerMistake[]; targets: PracticeTarget[] }
+  | { kind: "clean" }
+  | { kind: "failure" };
+
+export type CoachingSnoozeDecision = "snooze-session" | "snooze-five-hours";
+export type CoachingSnoozeHandler = (decision: CoachingSnoozeDecision) => Promise<void>;
+
+interface CoachingOverlayOptions {
+  tui: { requestRender(): void; terminal: { rows: number } };
+  theme?: Theme;
+  keybindings?: { matches(data: string, binding: string): boolean };
+  finish: (decision: CoachingOverlayDecision) => void;
+  saveSnooze?: CoachingSnoozeHandler;
+}
+
+type Mode = "checking" | "matched" | "saving";
+const ACTIONS = ["Edit", "Send once", "Snooze session", "Snooze 5 hours"] as const;
+
+function safe(value: string, maximum = 500): string {
+  return sanitizeTerminalLabel(value, maximum) || "—";
+}
+
+/** Keyboard-first submit checkpoint. Contains validated analysis only, never received draft text. */
+export class CoachingOverlay implements Component {
+  private mode: Mode = "checking";
+  private mistakes: AnalyzerMistake[] = [];
+  private targets: PracticeTarget[] = [];
+  private selectedAction = 1;
+  private detailOffset = 0;
+  private visibleDetailCount = 1;
+  private disposed = false;
+
+  constructor(private readonly options: CoachingOverlayOptions) {}
+
+  setMatches(mistakes: AnalyzerMistake[], targets: PracticeTarget[]): void {
+    if (this.disposed) return;
+    this.mode = "matched";
+    this.mistakes = [...mistakes];
+    this.targets = targets.map((target) => ({ ...target, memberPatternKeys: [...target.memberPatternKeys] }));
+    this.options.tui.requestRender();
+  }
+
+  setSaving(saving: boolean): void {
+    if (this.disposed) return;
+    this.mode = saving ? "saving" : "matched";
+    this.options.tui.requestRender();
+  }
+
+  invalidate(): void { /* No cached layout. */ }
+  dispose(): void { this.disposed = true; }
+
+  private matches(data: string, binding: string): boolean {
+    return this.options.keybindings?.matches(data, binding) ?? false;
+  }
+
+  handleInput(data: string): void {
+    if (this.disposed || this.mode === "saving") return;
+    const cancel = data === Key.escape || this.matches(data, "tui.select.cancel");
+    if (this.mode === "checking") {
+      if (cancel) this.options.finish("edit");
+      else if (data === Key.enter || this.matches(data, "tui.select.confirm")) {
+        this.options.finish("send-unchecked");
+      }
+      return;
+    }
+    if (cancel) {
+      this.options.finish("edit");
+      return;
+    }
+    if (data === Key.enter || this.matches(data, "tui.select.confirm")) {
+      const action = (["edit", "send-once", "snooze-session", "snooze-five-hours"] as const)[this.selectedAction]!;
+      if (action === "snooze-session" || action === "snooze-five-hours") this.beginSnooze(action);
+      else this.options.finish(action);
+      return;
+    }
+    if (data.toLowerCase() === "e") {
+      this.options.finish("edit");
+      return;
+    }
+    if (data.toLowerCase() === "t") this.beginSnooze("snooze-session");
+    else if (data === "5") this.beginSnooze("snooze-five-hours");
+    else if (data === "j" || this.matches(data, "tui.select.down")) {
+      this.selectedAction = Math.min(ACTIONS.length - 1, this.selectedAction + 1);
+      this.options.tui.requestRender();
+    } else if (data === "k" || this.matches(data, "tui.select.up")) {
+      this.selectedAction = Math.max(0, this.selectedAction - 1);
+      this.options.tui.requestRender();
+    } else if (this.matches(data, "tui.select.pageDown")) {
+      this.detailOffset = Math.min(Math.max(0, this.orderedDetails().length - 1), this.detailOffset + this.visibleDetailCount);
+      this.options.tui.requestRender();
+    } else if (this.matches(data, "tui.select.pageUp")) {
+      this.detailOffset = Math.max(0, this.detailOffset - this.visibleDetailCount);
+      this.options.tui.requestRender();
+    }
+  }
+
+  private beginSnooze(action: CoachingSnoozeDecision): void {
+    // showCoachingOverlay reserves this terminal outcome before persistence starts.
+    this.options.finish(action);
+  }
+
+  private mistakeGroups(): Array<{ label: string; mistakes: AnalyzerMistake[] }> {
+    const assigned = new Set<number>();
+    const groups = this.targets.map((target) => {
+      const mistakes = this.mistakes.filter((mistake, index) => {
+        if (assigned.has(index)) return false;
+        const matches = target.memberPatternKeys.includes(mistake.patternKey)
+          || target.explanation === mistake.explanation;
+        if (matches) assigned.add(index);
+        return matches;
+      });
+      return { label: target.explanation, mistakes };
+    }).filter((group) => group.mistakes.length > 0);
+    for (const [index, mistake] of this.mistakes.entries()) {
+      if (!assigned.has(index)) groups.push({ label: mistake.explanation, mistakes: [mistake] });
+    }
+    return groups;
+  }
+
+  private orderedDetails(): Array<{ label: string; mistake: AnalyzerMistake }> {
+    return this.mistakeGroups().flatMap((group) =>
+      group.mistakes.map((mistake) => ({ label: group.label, mistake })));
+  }
+
+  render(width: number): string[] {
+    const contentWidth = Math.max(1, Math.min(width - 2, 88));
+    const border = (text: string): string => this.options.theme?.fg("border", text) ?? text;
+    const lines: string[] = [];
+    if (this.mode === "checking") {
+      lines.push(" Checking selected fluency rules…", "", " Enter Send unchecked   esc Edit");
+    } else {
+      const details = this.orderedDetails();
+      const actionLines = this.mode === "saving"
+        ? [" Saving snooze…"]
+        : [...ACTIONS.map((action, index) => ` ${index === this.selectedAction ? "›" : " "} ${action}`),
+          " Enter confirm   esc Edit"];
+      // Border, heading, action separator, and actions stay visible even on short terminals.
+      const detailBudget = Math.max(3, this.options.tui.terminal.rows - actionLines.length - 5);
+      const detailLines: string[] = [];
+      let shown = 0;
+      let priorLabel: string | undefined;
+      const shownLabels = new Set<string>();
+      for (const detail of details.slice(this.detailOffset)) {
+        if (!shownLabels.has(detail.label) && shownLabels.size >= 3) break;
+        const block: string[] = [];
+        if (detail.label !== priorLabel) {
+          block.push(" ────────────────────────────────────────", ` Rule: ${safe(detail.label)}`);
+        }
+        for (const [label, value] of [
+          ["Original", detail.mistake.sourceExcerpt],
+          ["Suggestion", detail.mistake.correctedExcerpt],
+          ["Why", detail.mistake.explanation],
+        ] as const) {
+          const wrapped = wrapTextWithAnsi(`${label}: ${safe(value)}`, Math.max(10, contentWidth - 2));
+          block.push(...wrapped.map((line) => ` ${line}`));
+        }
+        if (shown > 0 && detailLines.length + block.length > detailBudget) break;
+        detailLines.push(...block.slice(0, Math.max(0, detailBudget - detailLines.length)));
+        shown += 1;
+        shownLabels.add(detail.label);
+        priorLabel = detail.label;
+        if (detailLines.length >= detailBudget) break;
+      }
+      this.visibleDetailCount = Math.max(1, shown);
+      const hidden = Math.max(0, details.length - this.detailOffset - shown);
+      lines.push(` Practice check · ${this.mistakes.length} ${this.mistakes.length === 1 ? "match" : "matches"}${hidden > 0 ? ` · +${hidden} more` : ""}`);
+      lines.push(...detailLines);
+      if (this.detailOffset > 0 || hidden > 0) {
+        lines.push(` PageUp/PageDown details · ${this.detailOffset + 1}-${this.detailOffset + shown} of ${details.length} matches`);
+      }
+      lines.push(" ────────────────────────────────────────", ...actionLines);
+    }
+    const top = border(`╭${"─".repeat(contentWidth)}╮`);
+    const bottom = border(`╰${"─".repeat(contentWidth)}╯`);
+    return [top, ...lines.map((line) => {
+      const content = truncateToWidth(line, contentWidth, "");
+      return `${border("│")}${content}${" ".repeat(Math.max(0, contentWidth - visibleWidth(content)))}${border("│")}`;
+    }), bottom];
+  }
+}
+
+export async function showCoachingOverlay(
+  ctx: ExtensionContext,
+  check: Promise<CoachingCheckResult>,
+  signal?: AbortSignal,
+  saveSnooze?: CoachingSnoozeHandler,
+): Promise<CoachingOverlayDecision> {
+  if (ctx.mode !== "tui") return "technical-failure";
+  let overlay: CoachingOverlay | undefined;
+  let close: (() => void) | undefined;
+  let settled = false;
+  let resolveDecision!: (decision: CoachingOverlayDecision) => void;
+  const decision = new Promise<CoachingOverlayDecision>((resolve) => { resolveDecision = resolve; });
+  const finish = (value: CoachingOverlayDecision): void => {
+    if (settled) return;
+    settled = true;
+    if ((value === "snooze-session" || value === "snooze-five-hours") && saveSnooze) {
+      // Reserve snooze as terminal winner before persistence. Abort/shutdown now lose without side effects.
+      overlay?.setSaving(true);
+      void Promise.resolve().then(() => saveSnooze(value)).catch(() => undefined).finally(() => {
+        overlay?.dispose();
+        close?.();
+        resolveDecision(value);
+      });
+      return;
+    }
+    overlay?.dispose();
+    close?.();
+    resolveDecision(value);
+  };
+  const abort = (): void => finish("send-unchecked");
+  signal?.addEventListener("abort", abort, { once: true });
+  try {
+    const custom = Promise.resolve(ctx.ui.custom<void>((tui, theme, keybindings, done) => {
+      close = done;
+      overlay = new CoachingOverlay({ tui, theme, keybindings, finish, ...(saveSnooze ? { saveSnooze } : {}) });
+      void check.then(
+        (result) => {
+          if (result.kind === "matches") overlay?.setMatches(result.mistakes, result.targets);
+          else finish(result.kind === "clean" ? "clean" : "technical-failure");
+        },
+        () => finish("technical-failure"),
+      );
+      if (signal?.aborted) abort();
+      return overlay;
+    }, {
+      overlay: true,
+      overlayOptions: { anchor: "center", width: "75%", minWidth: 56, maxHeight: "85%" },
+    })).catch(() => finish("technical-failure"));
+    await Promise.race([decision, custom]);
+    return await decision;
+  } finally {
+    signal?.removeEventListener("abort", abort);
+    overlay?.dispose();
+    close?.();
+  }
+}