trace-to-skill 0.1.83 → 0.1.85

package/docs/USE_CASES.md

@@ -24,6 +24,7 @@ npx trace-to-skill demo mcp-streamable-http
 npx trace-to-skill demo hooks-runtime
 npx trace-to-skill demo terminal-output-integrity
 npx trace-to-skill demo subagent-lifecycle
+npx trace-to-skill demo usage-bucket-confusion
 npx trace-to-skill sensitive-audit .
 npx trace-to-skill sensitive-audit . --format ignore --ignore-target codexignore --output .codexignore.generated
 npx trace-to-skill lsp-audit .
@@ -33,7 +34,7 @@ What it proves:
 
 - packaged fixtures can produce a real Codex issue report immediately
 - maintainers can inspect the output shape before sharing any private log
-- demos cover remote compact failures, context fork bloat, subagent prompt leakage, Windows helper path failures, patch overwrite safety, approval friction, latency, Thinking hangs, clipboard/attachment regressions, deeplink/OAuth launch regressions, connector auth-cache regressions, MCP discovery/config-scope mismatches, Streamable HTTP MCP parse/handshake failures, hooks runtime failures, terminal output/scrollback integrity, subagent lifecycle drift, token burn, sensitive files, and prompt injection
+- demos cover remote compact failures, context fork bloat, subagent prompt leakage, usage bucket confusion, Windows helper path failures, patch overwrite safety, approval friction, latency, Thinking hangs, clipboard/attachment regressions, deeplink/OAuth launch regressions, connector auth-cache regressions, MCP discovery/config-scope mismatches, Streamable HTTP MCP parse/handshake failures, hooks runtime failures, terminal output/scrollback integrity, subagent lifecycle drift, token burn, sensitive files, and prompt injection
 - `sensitive-audit` scans filenames and paths before an agent run, without reading file contents, so teams can build `.agentignore`, `.aiexclude`, `.codexignore`, `.gitignore`, or sandbox permission profiles from a concrete repo report
 - `lsp-audit` scans repo language signals and PATH availability so teams know which language servers are ready before asking Codex for symbol-aware edits
 
@@ -58,7 +59,7 @@ What it proves:
 Recommended CI surface:
 
 ```yaml
-- uses: grnbtqdbyx-create/trace-to-skill@v0.1.83
+- uses: grnbtqdbyx-create/trace-to-skill@v0.1.85
   with:
     mode: all
     doctor-threshold: "85"
@@ -68,7 +69,24 @@ Recommended CI surface:
     github-token: ${{ github.token }}
 ```
 
-## 3. AGENTS.md And MCP Hygiene
+## 3. GitHub Issue Demand Mining
+
+Use this when you want to see what Codex users are actually complaining about on GitHub before choosing the next fixture, report template, or diagnostic helper.
+
+```bash
+gh issue list --repo openai/codex --state open --limit 100 --json number,title,body,url,labels,comments,createdAt,updatedAt > codex-issues.json
+npx trace-to-skill issue-map codex-issues.json --output codex-issue-map.md
+npx trace-to-skill issue-map codex-issues.json --format json
+```
+
+What it proves:
+
+- public issue clusters can be ranked without private telemetry
+- high-comment pain points are mapped to deterministic failure classes such as token burn, remote compact, MCP discovery, usage buckets, context drift, sandbox, and resource leaks
+- maintainers get example issue links and evidence-rule prompts for the next support artifact
+- OSS builders can show that new work is grounded in real GitHub demand instead of generic agent demos
+
+## 4. AGENTS.md And MCP Hygiene
 
 Use this before giving Codex broad repository access.
 
@@ -88,7 +106,7 @@ This checks:
 
 The goal is not to ban powerful tools. The goal is to make trust boundaries visible before an agent acts.
 
-## 4. Language-Server Readiness Before Agent Edits
+## 5. Language-Server Readiness Before Agent Edits
 
 Use this when a repo wants Codex to navigate definitions, references, diagnostics, or rename/refactor flows, but language-server setup differs across machines.
 
@@ -106,7 +124,7 @@ What it proves:
 
 It does not auto-install anything or grant new permissions; it is a readiness report.
 
-## 5. Sandbox And Permission Failure Triage
+## 6. Sandbox And Permission Failure Triage
 
 Use this when Codex cannot start tools, apply patches, or write to the workspace because sandbox setup or permissions fail.
 
@@ -127,7 +145,7 @@ For Codex App reports where Speed resets from Fast to Standard after restart, in
 
 `diagnostics-bundle` combines the config, plugin, and session summaries into a metadata-only support folder with a manifest and README. Use it when OpenAI asks for more evidence but raw `config.toml`, SQLite state, rollout JSONL, and local logs should not be posted publicly.
 
-## 6. Codex Auth And Connectivity Triage
+## 7. Codex Auth And Connectivity Triage
 
 Use this when Codex cannot log in, exchange an auth token, stream a response, or connect through a container, proxy, VPN, corporate CA, IPv6 network, or Cloudflare challenge.
 
@@ -137,7 +155,7 @@ npx trace-to-skill analyze ./runs --format json
 
 This catches signals such as `token_exchange_failed`, `auth.openai.com/oauth/token`, `codex_login::server`, `cf-mitigated: challenge`, missing `ca-certificates`, `update-ca-certificates`, `CODEX_CA_CERTIFICATE`, IPv6 fallback evidence, proxy/MITM TLS failures, and `stream disconnected before completion` on `chatgpt.com/backend-api/codex/responses`.
 
-## 7. Codex Remote Compact Failure Triage
+## 8. Codex Remote Compact Failure Triage
 
 Use this when `/compact` or auto-compaction fails during a long Codex session and the user cannot continue without recreating context.
 
@@ -147,7 +165,7 @@ npx trace-to-skill codex-report ./runs --output openai-codex-compact-issue.md
 
 This catches signals such as `Error running remote compact task`, `timeout waiting for child process to exit`, `stream disconnected before completion`, `responses/compact`, `tcp_user_timeout`, `stream_idle_timeout_ms`, provider-id timeout workarounds, Azure provider config drift, and long-running tasks broken by failed compaction.
 
-## 8. Codex Context Fork Bloat Evidence
+## 9. Codex Context Fork Bloat Evidence
 
 Use this when a conversation fork carries duplicate parent context, inflates token counts, or breaks prompt-cache lineage before new work happens.
 
@@ -161,7 +179,7 @@ This catches signals such as forked conversations carrying the full parent trans
 
 Include Codex app/CLI/extension version, surface, model, fork source thread id, forked thread id, fork action timestamp, fork boundary marker, `input_tokens` and `cached_input_tokens` before and after the fork, `prompt_cache_key` before and after, cache hit rate, duplicated parent-turn or tool-transcript examples with line ids, whether new files were read before the token jump, compaction state, subagent or `fork_context` history, minimal reproduction steps, and whether a fresh thread or non-fork continuation avoids the bloat.
 
-## 9. Codex Subagent Prompt Leakage Evidence
+## 10. Codex Subagent Prompt Leakage Evidence
 
 Use this when `spawn_agent` child tasks are not isolated, especially with `fork_turns: "none"` or same-turn parallel subagent spawning.
 
@@ -175,7 +193,7 @@ This catches signals such as delegated `spawn_agent` messages recorded as assist
 
 Include Codex Desktop/app/CLI version, MultiAgentV2 state, OS, model, parent thread id, child thread ids, exact `spawn_agent` arguments, `fork_turns`, role/profile, whether `multi_tool_use.parallel` or same-turn parallel spawning was used, redacted child rollout line order, first user/task message, assistant/commentary envelope lines, sibling prompt excerpts, `wait_agent` and `close_agent` results, unexpected child tool calls, and sequential single-child versus parallel-child controls.
 
-## 10. Codex Usage Evidence Packaging
+## 11. Codex Usage Evidence Packaging
 
 Use this when a Codex usage issue has scattered evidence across `/status`, dashboard notes, reset tables, token totals, prompt-cache rows, cached input, and local overhead clues.
 
@@ -195,7 +213,21 @@ The receipt separates:
 - orchestration-overhead signals that may burn usage without accepted work
 - suspected cause buckets to keep public reports comparable
 
-## 11. Codex Windows Helper Path Triage
+## 12. Codex Usage Bucket Scope Evidence
+
+Use this when Codex usage UI shows 5h and weekly percentages but does not explain the accounting scope.
+
+```bash
+npx trace-to-skill demo usage-bucket-confusion
+npx trace-to-skill analyze ./runs --format json
+npx trace-to-skill codex-report ./runs --output openai-codex-usage-bucket-confusion.md
+```
+
+This catches signals such as `Usage remaining`, `5h 97%`, `Weekly 95%`, reset dates without scope labels, percent remaining versus percent used ambiguity, rolling 7-day versus natural-week ambiguity, and uncertainty about whether app, CLI, cloud tasks, reviews, other devices, or other workspaces share the weekly pool.
+
+Include subscription plan, account/workspace, app/CLI version, surface, timestamp, screenshot or redacted popover text, 5h percentage, weekly percentage, reset time/date, whether values are used or remaining, whether weekly is rolling or calendar-based, whether weekly includes app/CLI/cloud/review usage, `/status` output, usage dashboard state, and whether other devices or workspaces show the same values.
+
+## 13. Codex Windows Helper Path Triage
 
 Use this when Codex Desktop on Windows discovers bundled tools or plugin helpers but cannot execute them from the integrated terminal, tool runner, Browser, Chrome, Computer Use, or node_repl path.
 
@@ -205,7 +237,7 @@ npx trace-to-skill codex-report ./runs --output openai-codex-windows-helper-issu
 
 This catches signals such as `Program 'rg.exe' failed to run`, `Access is denied`, `WindowsApps\OpenAI.Codex...\app\resources`, missing `%LOCALAPPDATA%\OpenAI\Codex\bin`, missing MSIX LocalCache helper bins, `CodexSandboxUsers` ACL/RX problems, `copyfile` failures from WindowsApps bundled plugin manifests, EFS/Application Protected attributes, `windows sandbox failed: spawn setup refresh`, `missing-helper-path`, and unavailable Browser/Chrome/Computer Use plugin helpers.
 
-## 12. Codex Mobile And Remote-Control Route Health
+## 14. Codex Mobile And Remote-Control Route Health
 
 Use this when Codex mobile, SSH remote, or desktop remote-control says it is connected but commands do not reach the expected host, workspace, or app-server.
 
@@ -215,7 +247,7 @@ npx trace-to-skill analyze ./runs --format json
 
 This catches signals such as `Waiting for desktop`, `Directory: Unavailable`, stale `server_name` enrollment, stale remote-control listener, `127.0.0.1:14567`, missing cached helper files such as `codex-windows-sandbox-setup.exe` or `codex-command-runner.exe`, empty backend environments, stale Android session lists, and temporary recovery after re-pairing or listener restart.
 
-## 13. Codex Terminal Output And Scrollback Integrity
+## 15. Codex Terminal Output And Scrollback Integrity
 
 Use this when Codex terminal output, streamed assistant text, or scrollback becomes untrustworthy even though raw logs, transcripts, or transaction views still contain the missing lines.
 
@@ -229,7 +261,7 @@ This catches signals such as Windows Terminal scrollback lines disappearing, str
 
 Include the Codex CLI/app/extension version, OS, shell, terminal emulator and version, WSL/SSH/tmux/Zellij state, model, whether streaming was active, exact scroll action, terminal dimensions and scrollback settings, first missing or duplicated line id, raw log/transcript proof, terminal capture, numbered-line harness output, control run, `/resume` or transcript recovery behavior, and whether another terminal or downgrade changes the result.
 
-## 14. Codex Subagent Lifecycle And State Reconciliation
+## 16. Codex Subagent Lifecycle And State Reconciliation
 
 Use this when subagents appear completed, closed, stale, or interrupted but Codex cannot reconcile UI state, live handles, persisted spawn edges, parent discoverability, and active spawn quota.
 
@@ -243,7 +275,7 @@ This catches signals such as completed subagents remaining visible in the Subage
 
 Include Codex app/CLI/extension version, OS, surface, model, subscription/workspace, root thread id, subagent ids/nicknames/roles, spawn/close/list commands, `close_agent` results, `list_agents` or `/agents` output, `thread_spawn_edges` status counts, `agents.max_threads` or registry quota evidence, recent-list/sidebar behavior, child-thread archive/top-level status, last-progress or halt reason, MCP server state, compaction/resume timing, redacted UI evidence, restart/reload behavior, and whether stale agents are UI-only or still block spawns.
 
-## 15. Codex MCP Runtime Triage
+## 17. Codex MCP Runtime Triage
 
 Use this when MCP tools are configured and visible, but Codex cannot actually call them at runtime.
 
@@ -254,7 +286,7 @@ npx trace-to-skill config-audit ~/.codex --format json
 
 This catches signals such as `user cancelled MCP tool call`, `request_user_input is not supported in exec mode`, `Approve app tool call?`, `tool_call_mcp_elicitation`, routed callable names like `mcp__node_repl__js` becoming `unsupported call`, deferred discovery dropping namespace or `serverName`, `tools/list` succeeding while Codex routing fails, and stdio transport lifecycle failures such as `Transport closed`, `stdin_end`, `stdin_close`, `transport_close`, or stderr backpressure.
 
-## 16. Codex Resume And Session State Triage
+## 18. Codex Resume And Session State Triage
 
 Use this when long Codex sessions become difficult to resume, Desktop history rendering gets sluggish, or local state migrations break goals/projects/history.
 
@@ -271,7 +303,7 @@ This catches signals such as `codex resume` picker hangs, `codex resume <id>` wo
 
 For mixed resume, crash, config, plugin, or history issues, `diagnostics-bundle` writes the session, config, and plugin reports together with a checklist of files not to attach publicly.
 
-## 17. Codex File Tree UI Evidence
+## 19. Codex File Tree UI Evidence
 
 Use this when Codex Desktop cannot reveal project files through the native file tree, folder icon, floating file panel, or built-in preview.
 
@@ -282,7 +314,7 @@ npx trace-to-skill codex-report ./runs --output openai-codex-issue.md
 
 This catches signals such as `View > Toggle File Tree` doing nothing, `Cmd+Shift+E` or `Ctrl+Shift+E` having no visible effect, the folder icon disappearing, the floating file panel showing stale or unclickable entries after add/rename/delete operations, and `.doc`, `.pdf`, or `.ppt` previews failing until restart.
 
-## 18. Codex Token Burn Attribution
+## 20. Codex Token Burn Attribution
 
 Use this when Codex usage drains faster than expected and the trace needs to separate useful model work from orchestration overhead.
 
@@ -295,7 +327,7 @@ This catches signals such as tokens `burning very fast`, usage dropping by visib
 
 For public reports, prefer `usage-evidence` first so the quota-window, local-token, and orchestration-overhead layers are visible separately.
 
-## 19. Usage Reset Drift Evidence
+## 21. Usage Reset Drift Evidence
 
 Use this when Codex reset timing changes unexpectedly or users lose the ability to plan paid usage.
 
@@ -306,7 +338,7 @@ npx trace-to-skill codex-report ./runs --output openai-codex-issue.md
 
 This catches signals such as weekly reset dates moving from one date to another, `reset_at` jumping after the first prompt, saved weekly usage being wiped or pushed into the next window, outage compensation resets changing the anchor, `/status` and dashboard disagreement, and requests for deterministic reset schedules or rollover of unused prior-window usage.
 
-## 20. Quota And Usage-Limit Evidence
+## 22. Quota And Usage-Limit Evidence
 
 Use this when Codex blocks a prompt with a usage-limit message but another surface still shows remaining quota.
 
@@ -316,7 +348,7 @@ npx trace-to-skill analyze ./runs --format json
 
 This catches traces where `/status` or the usage page shows remaining 5h or weekly quota, accounts appear to share limits unexpectedly, a Team account inherits a Plus account's limit state, or quota reset times jump after logout/login.
 
-## 21. Codex Resource Leak Evidence
+## 23. Codex Resource Leak Evidence
 
 Use this when Codex Desktop, the VS Code extension, renderer, app-server, GPU process, shell snapshot, or helper process keeps burning local resources after the useful work should be idle.
 
@@ -338,7 +370,7 @@ npx trace-to-skill process-audit ./process-notes.md --format json
 
 `process-audit` packages Task Manager, System Informer, `Get-CimInstance`, `ps`, `top`, or handwritten process measurement snippets into a smaller public report. It detects PowerShell/pwsh CIM polling such as `Get-CimInstance Win32_Process`, high-CPU Codex/helper/renderer samples, stale `process_manager/chat_processes.json` mentions, and runaway helper signals without inspecting live processes or asking users to post full raw process dumps.
 
-## 22. Codex Thinking Hang Evidence
+## 24. Codex Thinking Hang Evidence
 
 Use this when Codex accepts a prompt, finishes a local tool call, or keeps a Responses stream open but the UI/CLI remains on Thinking or Working with no visible assistant follow-up.
 
@@ -352,7 +384,7 @@ This catches signals such as `turn/start`, `task_started`, a completed local too
 
 Include the Codex version, OS, model and reasoning/speed settings, turn or thread id, prompt timestamp, last successful tool output, first `response_item` timestamp, `responses_http` or websocket transport evidence, `time.busy` / `time.idle`, MCP/subagent state, stop/interrupt behavior, and whether a new thread or minimal config recovers.
 
-## 23. Codex Clipboard And Pasted-Text Attachment Evidence
+## 25. Codex Clipboard And Pasted-Text Attachment Evidence
 
 Use this when copy/export, long pasted prompts, or generated `Pasted text.txt` attachments break Codex prompt, `/goal`, or support-report workflows.
 
@@ -366,7 +398,7 @@ This catches signals such as `Copy as Markdown` disappearing from the Copy menu,
 
 Include app version, OS, surface, exact copy menu items, source text size, paste action, visible editor text, generated attachment name/path/size, `pasted-text-attachments.json` or fileAttachments metadata, command path such as `/goal`, preview/edit/revert actions tried, clipboard payload format, and whether paste-as-text, opt-out, explicit file reference, or downgrade changes behavior.
 
-## 24. Codex Deeplink And External Launch Evidence
+## 26. Codex Deeplink And External Launch Evidence
 
 Use this when OAuth callbacks, notification clicks, browser extension activation, mobile pairing, or CLI app-open commands fail to route back into Codex.
 
@@ -380,7 +412,7 @@ This catches signals such as `codex://oauth_callback?code=...` opening an Electr
 
 Include app/CLI/extension version, OS/build, install source, package id/path, affected surface, exact redacted URI shape, browser and connector/plugin name, error dialog text, whether the app was already running, AppX/MSIX evidence such as AppUserModelID and DelegateExecute, HKCU/HKCR `codex` keys, command-line arguments, repair/reinstall/re-register attempts, and whether manual `codex://test` or `Start-Process` reproduces.
 
-## 25. Codex App Connector Auth Cache Evidence
+## 27. Codex App Connector Auth Cache Evidence
 
 Use this when Codex app connectors appear installed but keep stale auth or discovery metadata after a reauth-required response.
 
@@ -394,7 +426,7 @@ This catches signals such as `401: "Server returned 401: 'Reauthentication requi
 
 Include app/CLI version, OS, connector/plugin name and id, installed plugin root, exact tool name, redacted `codex_apps_tools` and `codex_app_directory` metadata, `link_*` id before/after reconnect, `isAccessible` state, restart/remove/re-add/cache-clear/sign-in attempts, ChatGPT app page state, and whether an external MCP workaround succeeds.
 
-## 26. Codex MCP Discovery And Config Scope Evidence
+## 28. Codex MCP Discovery And Config Scope Evidence
 
 Use this when MCP servers work in Codex CLI or one config scope but are missing in VS Code, Desktop, WSL, remote sessions, project-local config, or an older conversation.
 
@@ -408,7 +440,7 @@ This catches signals such as `MCP servers not detected in Codex VS Code extensio
 
 Include app/CLI/extension version, OS, IDE, remote/WSL/SSH state, workspace root, effective `CODEX_HOME`, all config files considered (`~/.codex/config.toml`, project `.codex/config.toml`, `.vscode/mcp.json`, `.mcp.json`), redacted MCP sections, trust/profile/default-permissions state, `codex mcp list`, `codex mcp get <server>`, CLI-versus-Desktop/VS Code comparison, loaded config path/log lines, whether moving the same server to user-global config fixes it, and whether the current session exposes `mcp__*` tools.
 
-## 27. Codex Streamable HTTP MCP Evidence
+## 29. Codex Streamable HTTP MCP Evidence
 
 Use this when a Streamable HTTP or SSE MCP server is reachable but Codex fails during JSON-RPC parsing, handshake, auth gating, stale session reuse, or reconnect.
 
@@ -422,7 +454,7 @@ This catches signals such as Penpot `JsonRpcMessage deserialize` or response-par
 
 Include Codex version, MCP server name, transport URL without secrets, initialize/tools/list/tools/call results, HTTP status, `Content-Type`, SSE event framing, JSON-RPC message shape, session id before and after reconnect or server restart, auth/OAuth expectations, User-Agent/header requirements, exact parse/deserialize error, whether curl or another MCP client succeeds, and whether restarting Codex or reinitializing the transport recovers.
 
-## 28. Codex Hooks Runtime Evidence
+## 30. Codex Hooks Runtime Evidence
 
 Use this when Codex hooks duplicate, stop firing, emit stale deprecation warnings, behave differently across CLI/Desktop/Code Mode/Windows, or become hard to inspect in settings.
 
@@ -436,7 +468,7 @@ This catches signals such as duplicate Hooks entries for one tool call, `PostToo
 
 Include Codex app/CLI/extension version, OS, surface, shell or Desktop route, `[features].hooks` and `hooks.json` snippets without secrets, hook event type, matcher, handler command/name, expected versus observed fire count, duplicate event ids, exact deprecation warning, trust state, live-edit/rate-limit/auto-restore timing, Code Mode `exec` versus normal CLI comparison, linked-worktree cwd, Hooks settings UI screenshot if relevant, and whether restart/reload/new session restores behavior.
 
-## 29. Patch Overwrite Guard
+## 31. Patch Overwrite Guard
 
 Use this before applying a generated patch when you want create/update/delete semantics checked against the actual workspace.
 
@@ -453,7 +485,7 @@ For a public demo report:
 npx trace-to-skill demo patch-overwrite
 ```
 
-## 30. Sensitive Path Preflight Before Agent Runs
+## 32. Sensitive Path Preflight Before Agent Runs
 
 Use this before giving an AI coding agent a repository.
 
@@ -468,7 +500,7 @@ This finds sensitive-looking paths such as `.env`, `.env.*`, `.npmrc`, `.pypirc`
 
 The output includes a stable JSON schema plus recommended exclude globs that can seed `.agentignore`, `.aiexclude`, `.codexignore`, `.gitignore`, local sandbox permission profiles, or team security review checklists. `--format ignore` renders a reviewable generated file candidate and still does not mutate the repo. It is a preflight report, not a sandbox boundary.
 
-## 31. Workspace Checkpoint Before Agent Runs
+## 33. Workspace Checkpoint Before Agent Runs
 
 Use this before giving Codex, Claude, Cursor, or another coding agent a dirty repository where untracked local work matters.
 
@@ -481,7 +513,7 @@ This writes a local checkpoint bundle with `status.txt`, staged and unstaged bin
 
 This is useful for OpenAI/Codex `/undo` and `/rewind` discussions where users need workspace protection beyond conversation rewind, especially when untracked files are outside normal commit history.
 
-## 32. OpenAI Codex Issue Report
+## 34. OpenAI Codex Issue Report
 
 Use this when you want to file or update an OpenAI/Codex issue with a concise, evidence-backed report instead of pasting a full transcript.
 
@@ -494,7 +526,7 @@ The report includes the likely Codex failure class, line-linked evidence, diagno
 
 For a cluster-to-command map of current Codex issue patterns, see [CODEX_ISSUE_MAP.md](CODEX_ISSUE_MAP.md).
 
-## 33. Sensitive File Access Evidence
+## 35. Sensitive File Access Evidence
 
 Use this when a trace suggests an agent read, attached, uploaded, diffed, or indexed credential-bearing files.
 
@@ -507,7 +539,7 @@ This catches signals such as `.env`, `.env.production`, `.npmrc`, `.pypirc`, `.n
 
 Before publishing evidence, run `trace-to-skill redact` and attach only redacted excerpts plus the file path/class.
 
-## 34. GitHub Context Guard
+## 36. GitHub Context Guard
 
 Use this before an agent reads untrusted GitHub text.
 
@@ -524,7 +556,7 @@ Use it when:
 - a bot asks Codex to triage untrusted user reports
 - logs or comments might contain instructions like "ignore previous instructions" or "print secrets"
 
-## 35. Failed Agent Run To Reviewable Rule
+## 37. Failed Agent Run To Reviewable Rule
 
 Use this when a coding agent made a repeated workflow mistake.
 
@@ -542,7 +574,7 @@ Recommended maintainer loop:
 4. Copy only evidence-backed rules into the real policy file.
 5. Run `eval` or `scorecard` in CI so the same failure does not silently return.
 
-## 36. Privacy-Preserving Adoption
+## 38. Privacy-Preserving Adoption
 
 Use this when you want public evidence without leaking private traces.
 

package/fixtures/codex-usage-bucket-confusion.md

@@ -0,0 +1,33 @@
+# Codex Usage Bucket Confusion
+
+## Summary
+
+Codex Desktop usage popover shows short-term and weekly buckets as compact percentages, but the scope and semantics are unclear.
+
+## Evidence
+
+- The in-app usage popover shows `Usage remaining`.
+- The 5h row shows `5h 97% 6:23 PM`.
+- The Weekly row shows `Weekly 95% Jun 7`.
+- The user believes this is the first 5-hour usage window of the week, so `5h: 97% remaining` and `Weekly: 95% remaining` look contradictory.
+- The popover does not say whether percentages are percent remaining or percent used.
+- The popover does not say whether the weekly bucket is a natural week, rolling 7-day window, or account-wide pool.
+- It is unclear whether weekly usage includes Codex Desktop, CLI, cloud tasks, reviews, other devices, or other workspaces.
+- Without scope labels, the usage popover looks like a metering bug or contradictory quota display.
+
+## Expected
+
+The UI should label the accounting scope explicitly:
+
+```text
+Current 5h window: 97% remaining
+Weekly pool: 95% remaining
+Includes all Codex usage across app, CLI, cloud tasks, reviews, and devices
+Resets Jun 7
+```
+
+If the weekly bucket is rolling rather than calendar-week based, the popover should say `Rolling 7-day window`.
+
+## Diagnostics To Attach
+
+Include subscription plan, account/workspace, app/CLI version, surface, timestamp, screenshot or redacted text of the popover, 5h percentage, weekly percentage, reset time/date, whether the percentages mean used or remaining, whether weekly is rolling or calendar-based, whether the weekly pool includes app/CLI/cloud/review usage, `/status` output, usage dashboard state, and whether other devices or workspaces show the same values.

package/fixtures/github-codex-issues-export.json

@@ -0,0 +1,71 @@
+[
+  {
+    "number": 14593,
+    "title": "Burning tokens very fast",
+    "body": "Codex is burning tokens very fast while idle. Weekly usage drops 70% in one day with repeated compaction loops, retries, background polling, and no accepted edits. /status disagrees with the dashboard and cached input tokens keep replaying.",
+    "url": "https://github.com/openai/codex/issues/14593",
+    "labels": [
+      { "name": "bug" },
+      { "name": "rate-limits" }
+    ],
+    "commentsCount": 593,
+    "reactions": { "totalCount": 41 },
+    "updatedAt": "2026-06-01T00:00:00Z"
+  },
+  {
+    "number": 14860,
+    "title": "Error running remote compact task",
+    "body": "The long Codex session fails during /compact. The client prints Error running remote compact task, responses/compact, stream disconnected before completion, and timeout waiting for child process to exit. A provider config workaround only changes the failure timing.",
+    "url": "https://github.com/openai/codex/issues/14860",
+    "labels": [
+      { "name": "bug" },
+      { "name": "context" }
+    ],
+    "commentsCount": 90,
+    "reactions": { "+1": 15 },
+    "updatedAt": "2026-05-31T22:00:00Z"
+  },
+  {
+    "number": 6465,
+    "title": "MCP servers not detected in Codex VS Code extension but working in Codex CLI",
+    "body": "MCP servers not detected in the VS Code extension or Desktop, but working in Codex CLI from ~/.codex/config.toml. tools/list is empty in one surface, project .codex/config.toml is ignored, and serverName metadata is missing.",
+    "url": "https://github.com/openai/codex/issues/6465",
+    "labels": [
+      { "name": "bug" },
+      { "name": "extension" },
+      { "name": "mcp" }
+    ],
+    "comments": [
+      { "body": "I can reproduce this across WSL and Desktop with the same config scope mismatch." }
+    ],
+    "commentsCount": 55,
+    "reactions": { "totalCount": 8 },
+    "updatedAt": "2026-05-30T20:00:00Z"
+  },
+  {
+    "number": 25471,
+    "title": "Codex usage popover shows confusing remaining percentages for 5h vs weekly buckets",
+    "body": "Usage remaining shows 5h 97% and Weekly 95% Jun 7. The popover does not say whether the percentages are percent remaining or percent used, whether weekly is rolling 7-day or calendar week, or whether app, CLI, cloud tasks, reviews, devices, and workspaces share the same pool.",
+    "url": "https://github.com/openai/codex/issues/25471",
+    "labels": [
+      { "name": "enhancement" },
+      { "name": "rate-limits" },
+      { "name": "app" }
+    ],
+    "commentsCount": 1,
+    "reactions": 2,
+    "updatedAt": "2026-06-01T01:00:00Z"
+  },
+  {
+    "number": 99999,
+    "title": "Add a fun launch animation",
+    "body": "This is a cosmetic request with no evidence of a failed agent run.",
+    "url": "https://github.com/openai/codex/issues/99999",
+    "labels": [
+      { "name": "enhancement" }
+    ],
+    "commentsCount": 0,
+    "reactions": 0,
+    "updatedAt": "2026-05-01T00:00:00Z"
+  }
+]

package/llms.txt

@@ -36,6 +36,7 @@ Runtime: Node.js 20+
 - Codex app connector stale auth/cache regressions such as `401 Reauthentication required`, unchanged `link_*`, `isAccessible: false`, and broken `codex_apps_tools` metadata
 - Codex context fork bloat and prompt-cache lineage failures where conversation forks duplicate parent transcript blocks, inflate `input_tokens`, change `prompt_cache_key`, drop cache hit rate, or leak `fork_context` subagent history into child context before new work happens
 - Codex subagent prompt leakage where `spawn_agent` with `fork_turns: "none"` delivers assistant/commentary prompt envelopes, same-turn parallel children see sibling prompts, or `wait_agent`/`close_agent` completes despite the wrong child task
+- Codex usage popover bucket confusion where `Usage remaining`, `5h`, weekly percentages, reset dates, percent remaining vs percent used, rolling 7-day vs calendar-week, or account/workspace/device scope are unclear
 - Codex token-burn, prompt-cache collapse, and usage-drain failures such as rapid drain experiments (`1% in 4 minutes`, `22 credits`, `70% weekly in a day`), `input_tokens` / `cached_input_tokens` / `prompt_cache_key` rows, websocket reconnect cache drops, background `write_stdin` polling, idle app usage, compaction tax, retry/tool loops, cached-token-heavy turns, fast-mode drift, subagent fan-out, and unclear usage attribution
 - Codex process evidence packaging for Windows PowerShell/pwsh CIM polling, high-CPU helpers, stale process-manager entries, and renderer runaways
 - Codex usage reset schedule drift such as weekly reset dates moving, `reset_at` jumping, saved usage disappearing, outage compensation resets changing the anchor, and `/status` disagreeing with enforcement
@@ -86,6 +87,7 @@ npx trace-to-skill demo deeplink-launch
 npx trace-to-skill demo connector-auth-cache
 npx trace-to-skill demo context-fork-bloat
 npx trace-to-skill demo subagent-prompt-leakage
+npx trace-to-skill demo usage-bucket-confusion
 npx trace-to-skill demo mcp-discovery-mismatch
 npx trace-to-skill demo mcp-streamable-http
 npx trace-to-skill demo hooks-runtime
@@ -100,6 +102,7 @@ npx trace-to-skill plugin-audit ~/.codex --app /Applications/Codex.app --format
 npx trace-to-skill diagnostics-bundle ~/.codex --output codex-diagnostics
 npx trace-to-skill usage-evidence ./usage-notes.md --output usage-evidence.md
 npx trace-to-skill process-audit ./process-notes.md --output process-audit.md
+npx trace-to-skill issue-map codex-issues.json --output codex-issue-map.md
 npx trace-to-skill checkpoint . --output .trace-to-skill/checkpoints/before-codex
 npx trace-to-skill redact ./runs --output redacted-runs
 npx trace-to-skill sensitive-audit . --format json
@@ -117,7 +120,7 @@ npx trace-to-skill init --comment --sarif
 ## GitHub Action
 
 ```yaml
-- uses: grnbtqdbyx-create/trace-to-skill@v0.1.83
+- uses: grnbtqdbyx-create/trace-to-skill@v0.1.85
   with:
     mode: all
     doctor-threshold: "85"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trace-to-skill",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "description": "Turn failed AI coding-agent runs into reusable AGENTS.md rules, SKILL.md files, and eval evidence.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -21,6 +21,7 @@
     "docs/ADOPTION_GUIDE.md",
     "docs/AGENTS_LINT.md",
     "docs/BENCHMARK.md",
+    "docs/CODEX_GITHUB_ISSUE_PAIN_MAP.md",
     "docs/CODEX_ISSUE_MAP.md",
     "docs/DEMO.md",
     "docs/DISCOVERY.md",
@@ -41,7 +42,7 @@
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist coverage",
     "test": "npm run build && node --test dist/tests/*.test.js",
-    "check": "npm run test && node dist/src/cli.js doctor . --format json > /tmp/trace-to-skill-doctor.json && node dist/src/cli.js lint-agents . --format json > /tmp/trace-to-skill-agents-lint.json && node dist/src/cli.js analyze fixtures --format json > /tmp/trace-to-skill-smoke.json && node dist/src/cli.js usage-evidence fixtures --format json > /tmp/trace-to-skill-usage-evidence.json && node dist/src/cli.js process-audit fixtures/safe-run.md --format json > /tmp/trace-to-skill-process-audit.json && node dist/src/cli.js checkpoint . --output /tmp/trace-to-skill-checkpoint --format json > /tmp/trace-to-skill-checkpoint.json && node dist/src/cli.js sensitive-audit . --format json > /tmp/trace-to-skill-sensitive-audit.json && node dist/src/cli.js lsp-audit . --format json > /tmp/trace-to-skill-lsp-audit.json && node dist/src/cli.js suggest fixtures --target agents-md > /tmp/trace-to-skill-suggest.md && node dist/src/cli.js demo --format json > /tmp/trace-to-skill-demo.json && node dist/src/cli.js benchmark --format json > /tmp/trace-to-skill-benchmark.json && node dist/src/cli.js scorecard . --format json > /tmp/trace-to-skill-scorecard.json && node dist/src/cli.js oss-brief . --format json > /tmp/trace-to-skill-oss-brief.json",
+    "check": "npm run test && node dist/src/cli.js doctor . --format json > /tmp/trace-to-skill-doctor.json && node dist/src/cli.js lint-agents . --format json > /tmp/trace-to-skill-agents-lint.json && node dist/src/cli.js analyze fixtures --format json > /tmp/trace-to-skill-smoke.json && node dist/src/cli.js usage-evidence fixtures --format json > /tmp/trace-to-skill-usage-evidence.json && node dist/src/cli.js issue-map fixtures/github-codex-issues-export.json --format json > /tmp/trace-to-skill-issue-map.json && node dist/src/cli.js process-audit fixtures/safe-run.md --format json > /tmp/trace-to-skill-process-audit.json && node dist/src/cli.js checkpoint . --output /tmp/trace-to-skill-checkpoint --format json > /tmp/trace-to-skill-checkpoint.json && node dist/src/cli.js sensitive-audit . --format json > /tmp/trace-to-skill-sensitive-audit.json && node dist/src/cli.js lsp-audit . --format json > /tmp/trace-to-skill-lsp-audit.json && node dist/src/cli.js suggest fixtures --target agents-md > /tmp/trace-to-skill-suggest.md && node dist/src/cli.js demo --format json > /tmp/trace-to-skill-demo.json && node dist/src/cli.js benchmark --format json > /tmp/trace-to-skill-benchmark.json && node dist/src/cli.js scorecard . --format json > /tmp/trace-to-skill-scorecard.json && node dist/src/cli.js oss-brief . --format json > /tmp/trace-to-skill-oss-brief.json",
     "prepack": "npm run build",
     "prepare": "npm run build"
   },
@@ -140,12 +141,19 @@
     "codex-session-index",
     "codex-project-history",
     "codex-issue-report",
+    "codex-issue-map",
+    "github-issue-map",
+    "openai-issue-mining",
+    "maintainer-pain-map",
     "openai-triage",
     "openai-oss",
     "oss-maintainers",
     "codex-demo",
     "codex-token-burn",
     "codex-usage",
+    "codex-usage-bucket",
+    "usage-popover",
+    "rate-limit-ui",
     "codex-reset",
     "codex-usage-reset",
     "codex-resource-leak",

package/schemas/analysis-result.schema.json

@@ -92,6 +92,7 @@
         "codex_plugin_runtime",
         "codex_file_tree_ui",
         "codex_session_state",
+        "codex_usage_bucket_confusion",
         "codex_token_burn",
         "codex_resource_leak",
         "codex_tool_call_integrity",