codex-coach 0.1.3 → 0.1.5

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-coach",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Local-first Codex usage coach that analyzes logs and suggests workflow improvements.",
   "author": {
     "name": "Codex Coach Contributors"

package/README.md

@@ -82,6 +82,7 @@ Suggest custom instruction changes
 - Project capsules: redacted per-project workflow summaries with suggested local instructions.
 - Prompt rewrites: safe templates for vague prompts without storing full prompt text.
 - Confidence-scored suggestions: low, medium, or high confidence improvement notes.
+- Token efficiency: cached vs uncached input, output, routing, and context-budget recommendations.
 - Beginner and expert report modes.
 - Skill opportunities: repeated workflow patterns that may deserve a reusable Codex skill.
 - Real-time prompt linting through `codex-coach lint-prompt`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-coach",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Local-first Codex usage coach and plugin",
   "license": "MIT",
   "author": "Codex Coach Contributors",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-coach"
-version = "0.1.3"
+version = "0.1.5"
 description = "Local-first Codex usage coach and plugin"
 readme = "README.md"
 requires-python = ">=3.10"

package/src/codex_coach/__init__.py

@@ -1,3 +1,3 @@
 """Local-first Codex usage coach."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.5"

package/src/codex_coach/cli.py

@@ -166,8 +166,11 @@ def _doctor(paths) -> int:
     print(f"command: {command} {'OK' if command.exists() else 'not installed'}")
     plugin = paths.home / "plugins" / "codex-coach" / ".codex-plugin" / "plugin.json"
     print(f"plugin: {plugin} {'OK' if plugin.exists() else 'not installed'}")
-    skill = paths.home / ".agents" / "skills" / "codex-coach" / "SKILL.md"
+    skill = paths.codex_home / "skills" / "codex-coach" / "SKILL.md"
+    legacy_skill = paths.home / ".agents" / "skills" / "codex-coach" / "SKILL.md"
     print(f"skill: {skill} {'OK' if skill.exists() else 'not installed'}")
+    if legacy_skill.exists():
+        print(f"legacy_skill: {legacy_skill} duplicate")
     return 0 if paths.codex_home.exists() else 1
 
 

package/src/codex_coach/install.py

@@ -19,7 +19,7 @@ def install_from_source(source_root: Path, paths: CoachPaths, *, schedule: str =
         _copy_app(source_root, paths.app_dir)
     _install_command(paths)
     plugin_path = _install_plugin(source_root, paths.home)
-    skill_paths = _install_user_skills(source_root, paths.home)
+    skill_paths = _install_user_skills(source_root, paths)
     marketplace = _update_marketplace(paths.home, plugin_path)
     scheduler = _write_scheduler(paths, schedule=schedule)
     return {
@@ -90,20 +90,28 @@ def _install_plugin(source_root: Path, home: Path) -> Path:
     return plugin_root
 
 
-def _install_user_skills(source_root: Path, home: Path) -> list[Path]:
+def _install_user_skills(source_root: Path, paths: CoachPaths) -> list[Path]:
     skill_source = source_root / "skills" / PLUGIN_NAME
-    targets = [
-        home / ".agents" / "skills" / PLUGIN_NAME,
-        home / ".codex" / "skills" / PLUGIN_NAME,
-    ]
-    installed: list[Path] = []
-    for target in targets:
-        if target.exists():
-            shutil.rmtree(target)
-        target.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copytree(skill_source, target)
-        installed.append(target)
-    return installed
+    target = paths.codex_home / "skills" / PLUGIN_NAME
+    if target.exists():
+        shutil.rmtree(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(skill_source, target)
+    _remove_legacy_duplicate_skill(paths.home, target)
+    return [target]
+
+
+def _remove_legacy_duplicate_skill(home: Path, canonical_target: Path) -> None:
+    legacy_target = home / ".agents" / "skills" / PLUGIN_NAME
+    if legacy_target.resolve() == canonical_target.resolve() or not legacy_target.exists():
+        return
+    skill_file = legacy_target / "SKILL.md"
+    try:
+        skill_text = skill_file.read_text(encoding="utf-8")
+    except OSError:
+        return
+    if f"name: {PLUGIN_NAME}" in skill_text:
+        shutil.rmtree(legacy_target)
 
 
 def _update_marketplace(home: Path, plugin_path: Path) -> Path:

package/src/codex_coach/parser.py

@@ -58,9 +58,14 @@ class ScanAccumulator:
     project_efforts: dict[str, Counter] = field(default_factory=lambda: defaultdict(Counter))
     project_verification_tools: dict[str, Counter] = field(default_factory=lambda: defaultdict(Counter))
     project_prompt_scores: dict[str, list[int]] = field(default_factory=lambda: defaultdict(list))
+    project_token_totals: dict[str, Counter] = field(default_factory=lambda: defaultdict(Counter))
     prompt_scores: list[dict[str, Any]] = field(default_factory=list)
     error_counts: Counter = field(default_factory=Counter)
     verification_tools: Counter = field(default_factory=Counter)
+    token_totals: Counter = field(default_factory=Counter)
+    max_model_context_window: int = 0
+    max_last_input_tokens: int = 0
+    max_last_uncached_input_tokens: int = 0
     compacted_sessions: set[str] = field(default_factory=set)
     current_file_session: dict[str, str] = field(default_factory=dict)
 
@@ -90,6 +95,7 @@ class ScanAccumulator:
                     self.project_efforts[cwd],
                     self.project_prompt_scores[cwd],
                     verification_tool_calls,
+                    self.project_token_totals[cwd],
                 )
             )
         projects.sort(key=lambda item: (item["user_messages"], item["tool_calls"], item["turns"]), reverse=True)
@@ -126,6 +132,13 @@ class ScanAccumulator:
             "tools": dict(self.tool_counts.most_common()),
             "verification_tools": dict(self.verification_tools.most_common()),
             "errors": dict(self.error_counts.most_common()),
+            "token_efficiency": {
+                "status": "observed" if self.token_totals["token_count_events"] else "not_available",
+                "usage": _token_summary(self.token_totals, turns=self.totals["turns"]),
+                "max_model_context_window": self.max_model_context_window,
+                "max_last_input_tokens": self.max_last_input_tokens,
+                "max_last_uncached_input_tokens": self.max_last_uncached_input_tokens,
+            },
             "prompt_quality": {
                 "average_score": avg_prompt,
                 "categories": dict(prompt_categories),
@@ -203,7 +216,7 @@ def _scan_file(path: Path, acc: ScanAccumulator, *, since_dt) -> None:
             _handle_response_item(payload, acc, current_cwd)
             continue
         if event_type == "event_msg":
-            _handle_event_msg(payload, acc)
+            _handle_event_msg(payload, acc, current_cwd)
             continue
         if event_type == "compacted":
             acc.totals["compactions"] += 1
@@ -305,7 +318,9 @@ def _handle_response_item(payload: dict[str, Any], acc: ScanAccumulator, cwd: st
         acc.totals["reasoning_items"] += 1
 
 
-def _handle_event_msg(payload: dict[str, Any], acc: ScanAccumulator) -> None:
+def _handle_event_msg(payload: dict[str, Any], acc: ScanAccumulator, cwd: str) -> None:
+    if payload.get("type") == "token_count":
+        _handle_token_count(payload, acc, cwd)
     message = _content_text(payload.get("message") or payload.get("text") or payload)
     _count_errors(message, acc)
 
@@ -317,6 +332,7 @@ def _project_capsule(
     efforts: Counter,
     prompt_scores: list[int],
     verification_tool_calls: int,
+    token_totals: Counter,
 ) -> dict[str, Any]:
     prompt_average = round(sum(prompt_scores) / len(prompt_scores), 2) if prompt_scores else 0.0
     workflow = _infer_workflow(tools, counts)
@@ -332,6 +348,7 @@ def _project_capsule(
         "prompt_quality_average": prompt_average,
         "top_tools": dict(tools.most_common(5)),
         "effort_mix": dict(efforts.most_common()),
+        "token_usage": _token_summary(token_totals, turns=counts["turns"]),
         "likely_workflow": workflow,
         "recommended_instruction": instruction,
         "skill_candidate": counts["turns"] >= 3 or counts["tool_calls"] >= 10,
@@ -382,6 +399,69 @@ def _content_text(value: Any) -> str:
     return str(value)
 
 
+def _handle_token_count(payload: dict[str, Any], acc: ScanAccumulator, cwd: str) -> None:
+    info = payload.get("info")
+    if not isinstance(info, dict):
+        return
+    usage = info.get("last_token_usage")
+    if not isinstance(usage, dict):
+        return
+
+    input_tokens = _int_token(usage.get("input_tokens"))
+    cached_input_tokens = _int_token(usage.get("cached_input_tokens"))
+    output_tokens = _int_token(usage.get("output_tokens"))
+    reasoning_output_tokens = _int_token(usage.get("reasoning_output_tokens"))
+    total_tokens = _int_token(usage.get("total_tokens"))
+    uncached_input_tokens = max(0, input_tokens - cached_input_tokens)
+
+    values = {
+        "token_count_events": 1,
+        "input_tokens": input_tokens,
+        "cached_input_tokens": cached_input_tokens,
+        "uncached_input_tokens": uncached_input_tokens,
+        "output_tokens": output_tokens,
+        "reasoning_output_tokens": reasoning_output_tokens,
+        "total_tokens": total_tokens,
+    }
+    acc.token_totals.update(values)
+    acc.project_token_totals[cwd].update(values)
+
+    acc.max_last_input_tokens = max(acc.max_last_input_tokens, input_tokens)
+    acc.max_last_uncached_input_tokens = max(acc.max_last_uncached_input_tokens, uncached_input_tokens)
+    context_window = _int_token(info.get("model_context_window"))
+    acc.max_model_context_window = max(acc.max_model_context_window, context_window)
+
+
+def _token_summary(tokens: Counter, *, turns: int) -> dict[str, Any]:
+    input_tokens = int(tokens["input_tokens"])
+    cached_input_tokens = int(tokens["cached_input_tokens"])
+    uncached_input_tokens = int(tokens["uncached_input_tokens"])
+    output_tokens = int(tokens["output_tokens"])
+    total_tokens = int(tokens["total_tokens"])
+    turn_count = max(1, int(turns or 0))
+    return {
+        "events": int(tokens["token_count_events"]),
+        "input_tokens": input_tokens,
+        "cached_input_tokens": cached_input_tokens,
+        "uncached_input_tokens": uncached_input_tokens,
+        "output_tokens": output_tokens,
+        "reasoning_output_tokens": int(tokens["reasoning_output_tokens"]),
+        "total_tokens": total_tokens,
+        "cache_ratio": round(cached_input_tokens / input_tokens, 3) if input_tokens else 0.0,
+        "uncached_ratio": round(uncached_input_tokens / input_tokens, 3) if input_tokens else 0.0,
+        "input_tokens_per_turn": round(input_tokens / turn_count, 1) if input_tokens else 0.0,
+        "uncached_input_tokens_per_turn": round(uncached_input_tokens / turn_count, 1) if uncached_input_tokens else 0.0,
+        "output_tokens_per_turn": round(output_tokens / turn_count, 1) if output_tokens else 0.0,
+    }
+
+
+def _int_token(value: Any) -> int:
+    try:
+        return max(0, int(value or 0))
+    except (TypeError, ValueError):
+        return 0
+
+
 def _looks_like_verification(tool_name: str, arguments: str) -> bool:
     text = f"{tool_name} {arguments}".lower()
     return any(marker in text for marker in VERIFY_RE)

package/src/codex_coach/reports.py

@@ -41,11 +41,16 @@ def render_markdown_report(
         f"- Compactions: {totals.get('compactions', 0)}",
         f"- Prompt quality average: {prompt_quality.get('average_score', 0)}/10",
         "",
+        "Plain English: this is a private local report about how Codex was used, where the sessions got expensive or repetitive, and what small instruction changes may improve the next run.",
+        "",
         "## Top Coaching Notes",
         "",
     ]
     lines.extend(_coaching_notes(suggestions, limit=5 if expert else 3))
+    lines.extend(_token_efficiency_lines(facts, expert=expert))
     lines.extend(["", "## Project Mix", ""])
+    lines.append("Plain English: these are the projects where Codex spent the most work in this window. High tool-call counts usually mean implementation, diagnosis, or verification-heavy sessions.")
+    lines.append("")
     projects = facts.get("projects", [])[:8]
     if projects:
         lines.append("| Project | Sessions | Turns | User Messages | Tool Calls | Verification |")
@@ -60,6 +65,8 @@ def render_markdown_report(
         lines.append("No project activity found.")
 
     lines.extend(["", "## Project Capsules", ""])
+    lines.append("Plain English: a project capsule is a tiny memory card for a repo. Add one to that repo's `AGENTS.md` when Codex keeps needing to rediscover the same workflow.")
+    lines.append("")
     capsules = facts.get("project_capsules", [])[:5]
     if capsules:
         for capsule in capsules:
@@ -70,6 +77,8 @@ def render_markdown_report(
     lines.extend(_instruction_playbook_lines(facts.get("instruction_audit", {}), expert=expert))
 
     lines.extend(["", "## Prompt Quality", ""])
+    lines.append("Plain English: short prompts are fine when the context is obvious. When Codex guesses wrong, add the target, symptom, and success state.")
+    lines.append("")
     categories = prompt_quality.get("categories", {})
     if categories:
         for name in ("excellent", "good", "needs_work"):
@@ -88,8 +97,10 @@ def render_markdown_report(
             )
 
     lines.extend(["", "## Suggested Improvements", ""])
+    lines.append("Review these before pasting anything. Use global custom instructions for personal habits that should apply everywhere; use a project `AGENTS.md` for repo-specific commands, stack rules, or verification steps.")
+    lines.append("")
     for suggestion in suggestions:
-        lines.append(f"- [{suggestion['confidence']}] {suggestion['title']}: {suggestion['body']}")
+        lines.extend(_suggestion_lines(suggestion))
 
     skill_opportunities = build_skill_opportunities(facts)
     if skill_opportunities:
@@ -141,6 +152,8 @@ def build_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
                 "title": "Right-size reasoning effort",
                 "confidence": _confidence(ratio, high=0.75, medium=0.6),
                 "body": "High reasoning dominates recent turns. Default simple status, search, and small edit tasks to medium; reserve high/xhigh for ambiguous debugging, architecture, security, or broad refactors.",
+                "paste_target": "Global custom instructions",
+                "suggested_text": "Use medium effort for routine status checks, targeted searches, formatting, small edits, and deterministic reports. Escalate to high or xhigh only for ambiguous debugging, architecture decisions, security review, broad refactors, or production-risk changes.",
             }
         )
 
@@ -154,6 +167,8 @@ def build_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
                 "title": "Verify before calling work done",
                 "confidence": "high" if ratio < 0.08 and tool_calls >= 20 else "medium",
                 "body": "Verification commands are a small share of tool use. Ask Codex to run the smallest meaningful test, build, lint, browser check, or runtime probe before final status.",
+                "paste_target": "Project AGENTS.md",
+                "suggested_text": "Before final status, run the smallest meaningful verification for the change: a focused test, build, lint/typecheck, browser check, or runtime probe. If verification cannot run, say exactly why and what risk remains.",
             }
         )
 
@@ -165,6 +180,8 @@ def build_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
                 "title": "Checkpoint long runs",
                 "confidence": "high" if compactions >= 3 else "medium",
                 "body": "Compactions appeared in the window. For long tasks, ask Codex to keep a small task ledger and validate durable files before resuming.",
+                "paste_target": "Global custom instructions or project AGENTS.md",
+                "suggested_text": "For long tasks, keep a short task ledger with completed, in-progress, and pending steps. After compaction or interruption, verify the current file state and last successful command before continuing.",
             }
         )
 
@@ -180,6 +197,8 @@ def build_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
                 "title": "Tighten ambiguous prompts",
                 "confidence": _confidence(ratio, high=0.15, medium=0.08),
                 "body": "A noticeable share of prompts are too short to identify the target. Include action, file/project, symptom, and success state when context is not obvious.",
+                "paste_target": "Global custom instructions",
+                "suggested_text": "When my prompt is vague, infer the likely task from the current repo and recent context. If the target or success state is still unclear, ask one concise question before making broad changes.",
             }
         )
 
@@ -191,6 +210,8 @@ def build_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
                 "title": "Use project capsules",
                 "confidence": "high" if len(projects) >= 6 else "medium",
                 "body": "Recent work spans several projects. Keep a short per-project AGENTS or context note so Codex does not rebuild project intent every time.",
+                "paste_target": "Each active project's AGENTS.md",
+                "suggested_text": "## Project Capsule\n- Purpose: <what this repo is for>\n- Stack: <main frameworks, runtime, package manager>\n- Entry points: <key files or commands>\n- Verify: <smallest reliable test/build/check>\n- Avoid: <repo-specific traps or risky commands>",
             }
         )
 
@@ -201,9 +222,13 @@ def build_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
                 "title": "Turn repeated workflows into skills",
                 "confidence": "medium",
                 "body": "At least one project shows repeated tool patterns. Consider a small user skill with the workflow steps, validation commands, and resume rules.",
+                "paste_target": "A Codex skill `SKILL.md` or project AGENTS.md",
+                "suggested_text": "Use this workflow when <trigger>. First read <specific files>. Then perform <steps>. Verify with <commands>. If interrupted, resume by checking <durable artifact or command output>.",
             }
         )
 
+    suggestions.extend(build_token_suggestions(facts))
+
     instruction_audit = facts.get("instruction_audit", {})
     instruction_findings = instruction_audit.get("findings", []) if isinstance(instruction_audit, dict) else []
     if instruction_findings:
@@ -214,6 +239,8 @@ def build_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
                 "title": "Review instruction playbook",
                 "confidence": "high" if high else "medium",
                 "body": "Instruction files have review findings. Check for stale mode locks, project-specific global rules, missing AGENTS.md coverage, or secrets before changing user instructions.",
+                "paste_target": "Instruction review checklist",
+                "suggested_text": "Keep global instructions limited to durable personal preferences. Move repo-specific stack, commands, UI style, and deployment rules into that repo's AGENTS.md. Never store tokens, passwords, or API keys in instruction files.",
             }
         )
 
@@ -224,11 +251,83 @@ def build_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
                 "title": "Keep the current loop",
                 "confidence": "medium",
                 "body": "No strong coaching warnings stood out. Keep using explicit success states and ask for verification on user-facing or production-sensitive work.",
+                "paste_target": "Global custom instructions",
+                "suggested_text": "For user-facing or production-sensitive changes, finish with a short verification note that names the command or check that passed and any remaining risk.",
             }
         )
     return suggestions
 
 
+def build_token_suggestions(facts: dict[str, Any]) -> list[dict[str, str]]:
+    token_efficiency = facts.get("token_efficiency", {})
+    if not isinstance(token_efficiency, dict) or token_efficiency.get("status") != "observed":
+        return []
+
+    usage = token_efficiency.get("usage", {})
+    if not isinstance(usage, dict):
+        return []
+
+    suggestions: list[dict[str, str]] = []
+    input_tokens = int(usage.get("input_tokens", 0) or 0)
+    uncached_tokens = int(usage.get("uncached_input_tokens", 0) or 0)
+    output_tokens = int(usage.get("output_tokens", 0) or 0)
+    cache_ratio = float(usage.get("cache_ratio", 0.0) or 0.0)
+    uncached_per_turn = float(usage.get("uncached_input_tokens_per_turn", 0.0) or 0.0)
+    turns = max(1, int((facts.get("totals") or {}).get("turns", 0) or 0))
+    efforts = facts.get("efforts", {})
+    high_effort = sum(int(efforts.get(name, 0) or 0) for name in ("high", "xhigh"))
+
+    if input_tokens >= 100_000 and cache_ratio >= 0.75:
+        suggestions.append(
+            {
+                "id": "use-compact-context-artifacts",
+                "title": "Use compact context artifacts",
+                "confidence": _confidence(cache_ratio, high=0.85, medium=0.75),
+                "body": "Most input is repeated cached context. Keep short project capsules, latest facts, and resume notes so routine coaching can start from compact artifacts instead of full history.",
+                "paste_target": "Global custom instructions",
+                "suggested_text": "Before re-reading a large repo or long history, first check existing summaries, reports, AGENTS.md, and recent task notes. Use those compact artifacts to choose the smallest next context to inspect.",
+            }
+        )
+
+    if uncached_tokens >= 50_000 or uncached_per_turn >= 12_000:
+        suggestions.append(
+            {
+                "id": "cap-uncached-context",
+                "title": "Cap uncached context",
+                "confidence": "high" if uncached_per_turn >= 20_000 else "medium",
+                "body": "Uncached input is the expensive part. Ask Codex to read one likely file first, summarize before widening, and prefer targeted searches over broad file dumps.",
+                "paste_target": "Global custom instructions",
+                "suggested_text": "Before broad exploration, identify the likely bottleneck and inspect the one most relevant file or targeted search result first. Widen only after explaining what is still unknown.",
+            }
+        )
+
+    if high_effort and high_effort / turns >= 0.25:
+        suggestions.append(
+            {
+                "id": "route-routine-work-to-mini",
+                "title": "Route routine work to mini or medium",
+                "confidence": "high" if high_effort / turns >= 0.5 else "medium",
+                "body": "High effort appears often enough to merit routing. Use mini/medium for scan, report, grep, formatting, and deterministic edits; escalate only for ambiguous debugging, architecture, security, and risky decisions.",
+                "paste_target": "Global custom instructions",
+                "suggested_text": "Prefer cheaper routine routing: use mini or medium reasoning for scanning, reports, greps, formatting, and deterministic small edits. Escalate only when the task needs judgment, tradeoff analysis, or high-risk debugging.",
+            }
+        )
+
+    if output_tokens >= 20_000 and input_tokens and output_tokens / input_tokens >= 0.08:
+        suggestions.append(
+            {
+                "id": "request-concise-outputs",
+                "title": "Request concise outputs",
+                "confidence": "medium",
+                "body": "Output tokens are a visible part of spend. Ask for summaries first and detailed evidence only when deciding or reviewing.",
+                "paste_target": "Global custom instructions",
+                "suggested_text": "Default to concise final answers: say what changed, how it was verified, and any risk. Include detailed logs or long evidence only when asked or when needed for a decision.",
+            }
+        )
+
+    return suggestions
+
+
 def build_skill_opportunities(facts: dict[str, Any]) -> list[dict[str, str]]:
     opportunities: list[dict[str, str]] = []
     for capsule in facts.get("project_capsules", []):
@@ -301,12 +400,124 @@ def _coaching_notes(suggestions: list[dict[str, str]], *, limit: int) -> list[st
     return [f"- [{item['confidence']}] {item['title']}: {item['body']}" for item in suggestions[:limit]]
 
 
+def _suggestion_lines(suggestion: dict[str, Any]) -> list[str]:
+    lines = [
+        f"### {suggestion['title']}",
+        "",
+        f"- Confidence: {suggestion['confidence']}",
+        f"- Why: {suggestion['body']}",
+    ]
+    paste_target = suggestion.get("paste_target")
+    suggested_text = suggestion.get("suggested_text")
+    if paste_target and suggested_text:
+        lines.extend(
+            [
+                f"- Paste into: {paste_target}",
+                "",
+                "```md",
+                str(suggested_text),
+                "```",
+            ]
+        )
+    lines.append("")
+    return lines
+
+
+def _token_efficiency_lines(facts: dict[str, Any], *, expert: bool) -> list[str]:
+    lines = ["", "## Token Efficiency", ""]
+    token_efficiency = facts.get("token_efficiency", {})
+    if not isinstance(token_efficiency, dict) or token_efficiency.get("status") != "observed":
+        lines.append("No token usage events were found in this window.")
+        return lines
+
+    usage = token_efficiency.get("usage", {})
+    if not isinstance(usage, dict):
+        lines.append("No token usage events were found in this window.")
+        return lines
+
+    input_tokens = int(usage.get("input_tokens", 0) or 0)
+    cached_tokens = int(usage.get("cached_input_tokens", 0) or 0)
+    uncached_tokens = int(usage.get("uncached_input_tokens", 0) or 0)
+    output_tokens = int(usage.get("output_tokens", 0) or 0)
+    reasoning_tokens = int(usage.get("reasoning_output_tokens", 0) or 0)
+    total_tokens = int(usage.get("total_tokens", 0) or 0)
+    cache_ratio = float(usage.get("cache_ratio", 0.0) or 0.0)
+    uncached_ratio = float(usage.get("uncached_ratio", 0.0) or 0.0)
+
+    lines.append("Plain English: cached input is repeated context Codex could reuse more cheaply. Uncached input is new context, and that is usually where the biggest savings are.")
+    lines.append("")
+    lines.append(
+        f"- Input: {_fmt_int(input_tokens)} "
+        f"({_fmt_int(cached_tokens)} cached, {_fmt_int(uncached_tokens)} uncached)"
+    )
+    lines.append(f"- Output: {_fmt_int(output_tokens)} ({_fmt_int(reasoning_tokens)} reasoning)")
+    lines.append(f"- Total: {_fmt_int(total_tokens)} across {_fmt_int(int(usage.get('events', 0) or 0))} token events")
+    lines.append(f"- Cache ratio: {cache_ratio:.1%}; uncached ratio: {uncached_ratio:.1%}")
+    lines.append(
+        f"- Per turn: {_fmt_float(usage.get('input_tokens_per_turn'))} input, "
+        f"{_fmt_float(usage.get('uncached_input_tokens_per_turn'))} uncached"
+    )
+
+    max_last_input = int(token_efficiency.get("max_last_input_tokens", 0) or 0)
+    max_last_uncached = int(token_efficiency.get("max_last_uncached_input_tokens", 0) or 0)
+    context_window = int(token_efficiency.get("max_model_context_window", 0) or 0)
+    if max_last_input:
+        context_note = f" of {_fmt_int(context_window)}" if context_window else ""
+        lines.append(
+            f"- Largest step: {_fmt_int(max_last_input)} input tokens{context_note}; "
+            f"{_fmt_int(max_last_uncached)} uncached"
+        )
+
+    token_suggestions = build_token_suggestions(facts)
+    if token_suggestions:
+        lines.extend(["", "Token-saving moves:"])
+        for item in token_suggestions[: 5 if expert else 3]:
+            lines.append(f"- [{item['confidence']}] {item['title']}: {item['body']}")
+            if item.get("suggested_text"):
+                lines.extend(
+                    [
+                        f"  Paste into: {item.get('paste_target', 'instructions')}",
+                        "",
+                        "```md",
+                        str(item["suggested_text"]),
+                        "```",
+                        "",
+                    ]
+                )
+    else:
+        lines.extend(
+            [
+                "",
+                "Token-saving moves:",
+                "- No strong token-efficiency warning stood out. Keep routing routine work to cheaper models and reserve high effort for judgment-heavy turns.",
+            ]
+        )
+
+    if expert:
+        capsules = [item for item in facts.get("project_capsules", []) if isinstance(item, dict)]
+        token_capsules = [item for item in capsules if (item.get("token_usage") or {}).get("input_tokens")]
+        if token_capsules:
+            token_capsules.sort(key=lambda item: int((item.get("token_usage") or {}).get("input_tokens", 0)), reverse=True)
+            lines.extend(["", "Top token projects:"])
+            for item in token_capsules[:5]:
+                token_usage = item.get("token_usage") or {}
+                lines.append(
+                    f"- `{item.get('project')}`: {_fmt_int(int(token_usage.get('input_tokens', 0) or 0))} input, "
+                    f"{_fmt_int(int(token_usage.get('uncached_input_tokens', 0) or 0))} uncached, "
+                    f"{token_usage.get('cache_ratio', 0):.1%} cached"
+                )
+
+    return lines
+
+
 def _instruction_playbook_lines(instruction_audit: dict[str, Any], *, expert: bool) -> list[str]:
     lines = ["", "## Instruction Playbook", ""]
     if not isinstance(instruction_audit, dict) or not instruction_audit:
         lines.append("No instruction audit was generated.")
         return lines
 
+    lines.append("Plain English: this checks whether your global custom instructions and project `AGENTS.md` files are helping Codex, getting stale, or leaking project-specific rules into every repo.")
+    lines.append("")
     lines.append(f"- Status: {instruction_audit.get('status', 'unknown')}")
     lines.append(f"- Files reviewed: {instruction_audit.get('files_reviewed', 0)}")
     lines.append(f"- Findings: {len(instruction_audit.get('findings', []))}")
@@ -325,9 +536,13 @@ def _instruction_playbook_lines(instruction_audit: dict[str, Any], *, expert: bo
 
     suggestions = [item for item in instruction_audit.get("suggestions", []) if isinstance(item, dict)]
     if suggestions:
-        lines.extend(["", "Suggested playbook changes:"])
+        lines.extend(["", "Suggested playbook changes with pasteable examples:"])
         for item in suggestions[: 8 if expert else 4]:
             lines.append(f"- [{item.get('confidence', 'medium')}] {item.get('title')}: {item.get('body')}")
+            lines.append(f"  Paste into: `{item.get('target', 'instruction file')}`")
+            suggested_text = str(item.get("suggested_text") or "").strip()
+            if suggested_text:
+                lines.extend(["", "```md", suggested_text, "```", ""])
 
     if expert:
         files = [item for item in instruction_audit.get("files", []) if isinstance(item, dict)]
@@ -343,6 +558,8 @@ def _instruction_playbook_lines(instruction_audit: dict[str, Any], *, expert: bo
 
 
 def _render_suggestion_patch(suggestion: dict[str, str]) -> str:
+    paste_target = suggestion.get("paste_target", "custom instructions or project AGENTS.md")
+    suggested_text = suggestion.get("suggested_text") or f"- {suggestion['body']}"
     return "\n".join(
         [
             f"# Suggested Codex Instruction Change: {suggestion['title']}",
@@ -357,8 +574,10 @@ def _render_suggestion_patch(suggestion: dict[str, str]) -> str:
             "",
             "## Suggested Text",
             "",
+            f"Paste into: {paste_target}",
+            "",
             "```md",
-            f"- {suggestion['body']}",
+            suggested_text,
             "```",
             "",
             "## Rollback",
@@ -389,6 +608,8 @@ def _render_instruction_suggestion_patch(suggestion: dict[str, Any]) -> str:
             "",
             "## Suggested Text",
             "",
+            f"Paste into: {suggestion.get('target', 'instruction file')}",
+            "",
             "```md",
             suggested_text,
             "```",
@@ -407,3 +628,14 @@ def _confidence(value: float, *, high: float, medium: float) -> str:
     if value >= medium:
         return "medium"
     return "low"
+
+
+def _fmt_int(value: int) -> str:
+    return f"{int(value):,}"
+
+
+def _fmt_float(value: Any) -> str:
+    try:
+        return f"{float(value):,.1f}"
+    except (TypeError, ValueError):
+        return "0.0"