daymade/claude-code-skills

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 165 

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 100 | Identify Codex work after a terminal disappears, including ToDesk/headless terminals | [Terminal-session recovery](references/terminal-session-recovery.md): bind host/cwd, query the index, then verify records and terminal attribution separately |
+ 111 | The latest conversation about a topic, including a newer continuation | **Latest topic across continuations** below: recall locates relevant projects, index-only inventory finds recency candidates, and original records decide relatedness |
+ 179 
+ 180 ### Latest topic across continuations
+ 181 
+ 182 First bind the requested recency:
+ 183 
+ 184 - For the **latest conversation about a topic**, use the route below.
+ 185 - For the **newest message matching supplied words**, use indexed content search and
+ 186   compare verified original-record timestamps within the stated coverage. This is
+ 187   not the latest related Session, and relevance rank is not time order.
+ 188 - For **two supplied Sessions**, read only those exact IDs and compare their relevant
+ 189   original-record timestamps; do not invoke global inventory.
+ 190 
+ 191 For the latest conversation about a topic:
+ 192 
+ 193 1. Run `read-claude-code-history/scripts/history_index.py status`, then `recall`
+ 194    with `--provider codex --exclude-session <CURRENT_ID>` to find earlier related
+ 195    Sessions. Resolve their cwd through `find_codex_session.py <ID>`; an encoded
+ 196    project label is not a verified filesystem path. Treat relevance top-K only as
+ 197    topic/project leads, never as a latest answer. Record provider scope and freshness.
+ 198 2. For each relevant cwd, inspect the existing main-session inventory:
+ 199 
+ 200    ```text
+ 201    <skill-dir>/scripts/list_local_history.py \
+ 202      --source codex --index-only --cwd <workspace> --include-archived \
+ 203      --from-date <EARLIEST_TOPIC_DATE> --limit 50 --format json
+ 204    ```
+ 205 
+ 206    Omit an unknown date bound. Date filters use created/updated overlap, so an older

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 72 
+ 73 For observability choices, name the business decision the missing measurement
+ 74 would change before trying another collector. Distinguish application payload,
+ 75 host/interface traffic and provider billing by direction, time window and coverage;
+ 76 a healthy collector or a more exact counter does not establish cost attribution.
+ 77 If existing signals already support the next authorized business action, integrate
+ 78 and verify that path before extending the comparison. Keep required but unmet
+ 79 coverage open; do not silently replace the user's requirement with the easier
+ 80 measurement, or promote optional all-process/wire-byte precision into a new
+ 81 requirement. Reopen selection when a concrete coverage gap changes that decision,
+ 82 not merely because another candidate can expose more metrics.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 5   Use when Codex shows ~258K context, you want 500K or 1M tokens, auto-compaction fires too often,
- 6   or model_context_window/model_auto_compact_token_limit needs repair. Not for changing the selected
- 7   model or other Codex settings.
- 8 argument-hint: "[doctor|apply|verify]"
+ 5   Use to inspect local context settings, lower or set the auto-compaction threshold, expand
+ 6   ~258K context to 500K or 1M, or repair model_context_window/model_auto_compact_token_limit.
+ 7   Not for changing the selected model or other Codex settings.
+ 8 argument-hint: "[show|set-compact --tokens N|doctor|apply|verify]"
- 13 Expand future Codex sessions without pretending every model supports one million
- 14 tokens. The bundled script reads Codex's current model catalog, caps the request at
- 15 the selected model's declared maximum, and applies the user's established 60%
- 16 auto-compaction policy.
+ 13 Inspect local settings or change only automatic compaction. For full context
+ 14 expansion, read Codex's current model catalog, cap the request at the model's
+ 15 declared maximum, and apply the bundled expansion preset.
- 22 | Inspect the current limit, explain 258K, or preview the recommendation | Run `doctor` |
+ 21 | Read the current base-config window or compaction threshold | Run `show`; no Codex process or model catalog needed |
+ 22 | Lower/set only automatic compaction | Run `show`, then `set-compact --tokens N` |
+ 23 | Explain 258K, diagnose model limits, or preview full expansion | Run `doctor` |
- 26 Do not ask the user for raw token numbers. The model catalog is the authority and
- 27 the script derives the attainable values.
+ 27 Honor a user-specified threshold exactly. If the user only asks for a small
+ 28 reduction, choose and state a modest reversible reduction from the observed value.
+ 29 For expansion, derive attainable values from the live catalog instead of asking
+ 30 the user for model limits. Running `apply` selects the full expansion preset and
+ 31 replaces a custom threshold; do it only when full setup is requested.
+ 32 
+ 33 For local reads/edits, start with the bundled commands. Do not dump config.toml,
+ 34 load unrelated machine manuals, or run network/model diagnostics. Consult official
+ 35 OpenAI documentation when parameter semantics or compatibility are unresolved;
+ 36 it cannot establish this machine's current value. Respect host output restrictions;
+ 37 if numeric output is denied, use its supported field-condition probe and keep an
+ 38 unread value unknown. Do not reconstruct denied values through repeated comparisons.
+ 39 
+ 40 ## Prerequisites
+ 41 
+ 42 Use Python 3.11+ for the script's `tomllib` dependency and uv for the documented
+ 43 launcher. `show` needs no Codex executable. `set-compact` requires a Codex CLI
+ 44 supporting `features list`; full expansion additionally requires `doctor --json`,
+ 45 `debug models` and strict-config diagnostics. Missing expansion support does not
+ 46 prevent a local read. Do not substitute another config root or guessed model data
+ 47 when a required command is unavailable.
+ 50 
+ 51 Run the bundled [configuration script](scripts/codex_context_window.py).
- 41 On macOS/Linux, set that exact directory and run:
+ 63 On macOS/Linux, set that exact directory:
- 45 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" doctor
- 46 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" apply
- 47 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" verify
- 54 uv run --no-project python "$SkillDir/scripts/codex_context_window.py" doctor
- 55 uv run --no-project python "$SkillDir/scripts/codex_context_window.py" apply
- 56 uv run --no-project python "$SkillDir/scripts/codex_context_window.py" verify
+ 74 
+ 75 Execute only the branch selected under **Route the request**. In the commands
+ 76 below, PowerShell users substitute `$SkillDir` for `$SKILL_DIR`.
+ 77 
+ 78 ### `show` and `set-compact`
+ 79 
+ 80 Use the same resolved script path on either platform:
+ 81 
+ 82 ```bash
+ 83 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" show --json
+ 84 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" set-compact --tokens 400000 --json
+ 85 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" show --json
+ 86 ```
+ 87 
+ 88 Choose `--tokens` from the current request, not this example. `show` emits only
+ 89 the numeric settings, the config path and evidence status; a missing value is null,
+ 90 not a guessed default.
+ 91 It does not inspect profile or command-line overrides.
+ 92 
+ 93 `set-compact` preserves the context-window setting, profiles, comments and existing
+ 94 formatting; inserting a missing key may add a separating newline. It rejects
+ 95 nonpositive/out-of-range tokens and thresholds
+ 96 above an explicitly configured window. When the window is absent, leave it absent;
+ 97 model-derived runtime caps remain unverified. Before a changed write, back up the
+ 98 original and check for concurrent edits. Write atomically, run the local
+ 99 `codex features list` configuration-load check with captured output, and read back
+ 100 the target. Restore the original on validation failure unless a concurrent edit
+ 101 makes that unsafe. A no-op creates no backup. Do not echo diagnostic bodies that
+ 102 may contain unrelated configuration. Use `show` afterward as independent readback.
- 61 Run first. It is read-only and reports:
+ 106 Run first for full expansion or model-cap diagnosis:
+ 107 
+ 108 ```bash
+ 109 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" doctor --json
+ 110 ```
+ 111 
+ 112 It is read-only and reports:
- 65 - requested raw window (up to 1,000,000), usable window, and 60% compaction point;
+ 116 - recommended raw window, usable window, and preset compaction point;
- 69 If Codex cannot return a live model catalog, stop. Do not substitute remembered
- 70 model limits, API marketing numbers, or a bundled default.
+ 120 If Codex cannot return a live model catalog, stop the expansion path. Do not
+ 121 substitute remembered model limits, API marketing numbers, or a bundled default.
+ 122 Local `show`/`set-compact` remain independent of catalog availability.
- 74 Run only after `doctor` succeeds. The script:
+ 126 Run only after `doctor` succeeds:
+ 127 
+ 128 ```bash
+ 129 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" apply --json
+ 130 ```
+ 131 
+ 132 The script:
- 92 recommendation. Report the mismatch; do not call it configured.
+ 150 expansion preset. A deliberate custom threshold can differ from that preset; this
+ 151 is not proof that the saved threshold is invalid. Use `show` for its current base value.
+ 152 
+ 153 ```bash
+ 154 uv run --no-project python "$SKILL_DIR/scripts/codex_context_window.py" verify --json
+ 155 ```
- 96 Copy exact values from script output. Include:
+ 159 For a threshold-only change, report previous → saved tokens, backup path when
+ 160 changed, local configuration-load result and independent readback. Keep
+ 161 `session_adoption: unverified` until the actual consumer supplies evidence. Ask
+ 162 the user to start a new CLI thread or restart/open a new Desktop thread that reads
+ 163 this base config; do not claim the running thread changed. Profile and `-c`
+ 164 overrides can still supersede it.
+ 165 
+ 166 For expansion, copy exact values from script output. Include:

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 26 - Before login, account switching or token recovery, read [the OAuth guide](references/oauth-guide.md) and follow its [recovery recipe](references/oauth-guide.md#remote-account-switch-and-expired-login-recovery). Use fresh empty stores for independent grants, retain explicitly authorized single-owner transfers, and verify actual access and existing-process adoption separately.
+ 26 - Before login, account switching or token recovery, read [the OAuth guide](references/oauth-guide.md). For a running native owner, [compare its account with the saved login first](references/oauth-guide.md#existing-native-owner-recovery); choose saved-login adoption, token recovery or new authorization from the observed state. Retain [independent-grant recovery](references/oauth-guide.md#remote-account-switch-and-expired-login-recovery), explicit single-owner transfers and separate access, process-adoption and business-continuation checks.
+ 66 
+ 67 ### Executable identity baseline (opt-in)
+ 68 
+ 69 Before an expensive build, resume or recovery claim that depends on *which*
+ 70 codex entry is in play, freeze the identity once and compare it at claim time;
+ 71 never refresh a baseline to make a comparison pass.
+ 72 
+ 73 ```bash
+ 74 # Freeze once, before the work (add --watch-file for owner-selected configs):
+ 75 python3 scripts/entry_identity.py snapshot --output <task-owned-baseline.json>
+ 76 # Compare before the expensive claim:
+ 77 python3 scripts/entry_identity.py check --baseline <task-owned-baseline.json>
+ 78 ```
+ 79 
+ 80 The check separates the owning-shell dispatch entry (what `/bin/zsh -lic`
+ 81 resolves `codex` to: external, function, alias) from the wrapper-selected
+ 82 external executable (the `CODEX_BIN` > PATH > app-bundle order above). Exit
+ 83 codes: `0` unchanged, `1` drift, `2` unknown, `3` usage or baseline error.
+ 84 `unchanged` is identity-only evidence — it never proves wrapper downstream
+ 85 runtime, authentication, quota or model health. When the dispatch entry is a
+ 86 function or alias, its consumer stays opaque (the definition is hashed, never
+ 87 executed). Verify its downstream executable through the launcher's owner;
+ 88 setting `CODEX_BIN` selects the wrapper and does not prove where a function runs.
+ 89 Read [entry-identity.md](references/entry-identity.md) for
+ 90 fields, failure shapes and a startup-report example.
+ 161 Before an authorized shared-daemon restart or package replacement, read
+ 162 [shared daemon maintenance](references/shared-daemon-maintenance.md). Preserve
+ 163 affected work, retain an independent operation receipt, and verify continuation
+ 164 under the original session IDs; a new daemon is not proof that tasks resumed.
+ 165 

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 5   Converts DOCX/PDF/PPTX and saved HTML/HTM to high-quality Markdown with automatic post-processing. Fixes pandoc grid tables, simple tables, image paths, CJK bold spacing, attribute noise, and code blocks; for PDFs also strips OCR garbage blocks, repeated headers/footers/watermarks, and absolute image paths from pymupdf4llm output. Benchmarked best-in-class (7.6/10) against Docling, MarkItDown, Pandoc raw, and Mammoth. Trigger on "convert document", "docx to markdown", "parse word", "doc to markdown", "解析word", "转换文档", "HTML to Markdown".
+ 5   Converts DOCX/PDF/PPTX and saved HTML/HTM to high-quality Markdown with automatic post-processing. Fixes pandoc grid tables, simple tables, image paths, CJK bold spacing, attribute noise, and code blocks; for PDFs also strips OCR garbage blocks, repeated headers/footers/watermarks, and absolute image paths from pymupdf4llm output. Trigger on "convert document", "docx to markdown", "parse word", "doc to markdown", "解析word", "转换文档", "HTML to Markdown".
- 12 **Architecture**: Pandoc (best-in-class extraction) + 8 post-processing fixes (our value-add).
+ 12 **Architecture**: Format-specific converters with automatic post-processing.
- 17 # DOCX → Markdown (one command, zero manual fixes)
- 18 uv run --with pymupdf4llm --with markitdown scripts/convert.py document.docx -o output.md --assets-dir ./media
+ 17 # DOCX → Markdown
+ 18 uv run --with pymupdf --with pymupdf4llm --with "markitdown[pdf]" scripts/convert.py document.docx -o output.md --assets-dir ./media
- 21 uv run --with pymupdf4llm --with markitdown scripts/convert.py document.pdf -o output.md
+ 21 uv run --with pymupdf --with pymupdf4llm --with "markitdown[pdf]" scripts/convert.py document.pdf -o output.md
- 30 ## Dual Mode
- 31 
- 32 | Mode | Speed | Quality | Use Case |
+ 30 ## Conversion Modes
+ 31 
+ 32 | Mode | Speed | Selection | Use Case |
- 34 | **Quick** (default) | Fast | Good | Drafts, simple documents |
- 35 | **Heavy** | Slower | Best | Final documents, complex layouts |
+ 34 | **Quick** (default) | Fast | Single converter | Drafts, simple documents |
+ 35 | **Heavy** | Slower | Compares converter candidates | Complex layouts needing source review |
- 39 | Format | Quick Mode | Heavy Mode |
- 40 |--------|-----------|------------|
- 41 | PDF | pymupdf4llm | pymupdf4llm + markitdown |
- 42 | DOCX | pandoc + post-processing | pandoc + markitdown |
- 43 | PPTX | markitdown | markitdown + pandoc |
- 44 | XLSX | markitdown | markitdown |
- 45 | HTML/HTM | pandoc + source-href retention check | unsupported; use the HTML quick path |
+ 39 Read [`select_tools`](scripts/convert.py) for format preferences and availability
+ 40 filtering. HTML/HTM follows the [saved HTML procedure](references/html-conversion.md).
+ 41 For Heavy Mode selection and failure handling, read
+ 42 [its procedure](references/heavy-mode-guide.md#selection-behavior).
+ 43 
+ 44 ## PDF Manuals And Question Banks
+ 45 
+ 46 Before delivering a PDF conversion or changing its structure, follow the
+ 47 [PDF acceptance procedure](references/pdf-acceptance.md). It owns source comparison,
+ 48 structural review, actual-reader checks and original-file handoff.
- 63 When converting DOCX via pandoc, 8 cleanups are applied automatically:
+ 66 When converting DOCX via pandoc, these cleanups are applied automatically:
- 71 | CJK bold spacing (`**粗体**中文`) | Add space around `**` for CJK bold spans | `TestCjkBoldSpacing` (15 cases) |
+ 74 | CJK bold spacing (`**粗体**中文`) | Add space around `**` for CJK bold spans | `TestCjkBoldSpacing` |
- 76 ## PDF Post-Processing (automatic, 2026-08-30 起)
- 77 
- 78 When converting PDF via pymupdf4llm, 3 cleanups are applied automatically (skip with `--no-postprocess`):
+ 79 ## PDF Post-Processing (automatic)
+ 80 
+ 81 When converting PDF via pymupdf4llm, these cleanups are applied automatically (skip with `--no-postprocess`):
- 83 | Repeated header/footer/watermark lines (same normalized line on ≥60% of pages, incl. diagonal watermarks) | Detected via pymupdf cross-page scan, removed from markdown; bold-wrapped and merged-with-page-number variants also caught | `TestRepeatingLines` |
+ 86 | Repeated header/footer/watermark lines (including diagonal watermarks) | Detected via pymupdf cross-page scan, removed from markdown; bold-wrapped and merged-with-page-number variants also caught | `TestRepeatingLines` |
- 86 Heavy mode additionally prints a loud `⚠<U+FE0F> HEAVY MODE DEGRADED` warning on stderr when one engine fails and the merge would otherwise silently degrade to single-engine output.
- 87 
- 88 **Known limits (learned from a 62-page Chinese research-report conversion, 2026-08-30):**
+ 89 For engine availability and failure handling, read [Heavy Mode selection](references/heavy-mode-guide.md#selection-behavior).
+ 90 
+ 91 **Known limits:**
- 103 After:  打开 **飞书** ，就可以  → universally renders correctly
+ 106 After:  打开 **飞书** ，就可以  → inspect bold rendering in the target reader
- 108 Heavy Mode runs multiple tools in parallel and selects the best segments:
- 109 
- 110 1. **Parallel Execution**: Run all applicable tools simultaneously
- 111 2. **Segment Analysis**: Parse each output into segments (tables, headings, images, paragraphs)
- 112 3. **Quality Scoring**: Score each segment based on completeness and structure
- 113 4. **Intelligent Merge**: Select best version of each segment across tools
- 114 
- 115 ### Merge Criteria
- 116 
- 117 | Segment Type | Selection Criteria |
- 118 |--------------|-------------------|
- 119 | Tables | More rows/columns, proper header separator |
- 120 | Images | Alt text present, local paths preferred |
- 121 | Headings | Proper hierarchy, appropriate length |
- 122 | Lists | More items, nested structure preserved |
- 123 | Paragraphs | Content completeness |
+ 111 Before choosing Heavy Mode, read its [selection and degradation behavior](references/heavy-mode-guide.md#selection-behavior).
+ 112 For explicit segment-level merging, use [Merge Outputs Manually](#merge-outputs-manually).
- 141 ```bash
- 142 # Validate conversion quality
- 143 uv run --with pymupdf scripts/validate_output.py document.pdf output.md
- 144 
- 145 # Generate HTML report
- 146 uv run --with pymupdf scripts/validate_output.py document.pdf output.md --report report.html
- 147 ```
- 148 
- 149 ### Quality Metrics
- 150 
- 151 | Metric | Pass | Warn | Fail |
- 152 |--------|------|------|------|
- 153 | Text Retention | >95% | 85-95% | <85% |
- 154 | Table Retention | 100% | 90-99% | <90% |
- 155 | Image Retention | 100% | 80-99% | <80% |
+ 130 For the validator's command, prerequisites, result fields and exit handling, read
+ 131 [Mechanical comparison](references/pdf-acceptance.md#mechanical-comparison).
+ 132 The CLI accepts PDF or DOCX source files; the remainder of that procedure covers
+ 133 PDF structural and recipient acceptance.
+ 134 
+ 135 From this Skill's source checkout, run the validator's bidirectional controls with
+ 136 `python3 -m unittest discover -s tests -v` (Pandoc required). Default packages
+ 137 exclude this development test directory; a zero-test run is not validation.
- 178 ```bash
- 179 # Install all tools
- 180 pip install pymupdf4llm
- 181 uv tool install "markitdown[pdf]"
- 182 brew install pandoc
- 183 ```
+ 160 Follow [converter installation](references/tool-comparison.md#installation), then
+ 161 rerun the selected conversion command. Check imports in the same Python runtime
+ 162 as the converter; a distribution name alone does not prove an engine is available.
- 186 - Harmless font parsing warnings, output is still correct
+ 165 - A font warning alone does not establish output quality; follow [PDF acceptance](references/pdf-acceptance.md).
- 189 - Use Heavy Mode for better image preservation
+ 168 - Follow [PDF acceptance](references/pdf-acceptance.md) to reconcile missing images and references.
- 193 - Use Heavy Mode - it selects the most complete table version
- 194 - Or validate with `scripts/validate_output.py`
+ 172 - Compare the table with the original and reconstruct missing cells if needed.
+ 173 - Read [Heavy Mode selection](references/heavy-mode-guide.md#selection-behavior) before trying another candidate; the validator diagnoses coverage and does not repair tables.
- 202 | `test_convert.py` | 31 tests covering all post-processing functions |
+ 181 | `test_convert.py` | Converter and post-processing regression tests |
- 210 - `references/benchmark-2026-03-22.md` - 5-tool benchmark (Docling/MarkItDown/Pandoc/Mammoth/ours)
+ 189 - `references/benchmark-2026-03-22.md` - Historical converter benchmark
+ 194 - `references/pdf-acceptance.md` - PDF text/structure checks, synthetic boundary controls, reader and original-file handoff

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 40 | Extract Word/WPS DOCX comments or tracked changes; compare a returned DOCX with its explicit sent baseline, including files with no review traces | `../read-docx-review/SKILL.md` |
+ 40 | Extract Word/WPS DOCX comments or tracked changes; compare explicitly selected DOCX versions, using the verified sent baseline for counterpart feedback, including files with no review traces | `../read-docx-review/SKILL.md` |

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 51 Rule of thumb: the CLI's `--content-json` understands exactly three block types
+ 51 Rule of thumb: the CLI's `--content-json` understands these block types:
- 65 # 2. Generate (first run restores DocumentFormat.OpenXml + Markdig, ~20s)
+ 65 # 2. Generate (first run restores the project dependencies)
- 78 # 5. Assess the existing authorized Word route, then perform native checks when usable
- 79 # Installed alone is not usable; follow Step 3a for denied/unavailable routes
- 80 open -a "Microsoft Word" your-doc.docx   # check the title bar for "兼容性模式", check every page
+ 78 # 5. Follow verification_protocol.md Step 3a before invoking the native Word route.
+ 79 # Perform its native checks when usable; otherwise retain the named acceptance gap.
- 90 Never justify the whole document. Three layers, three alignments:
+ 89 Never justify the whole document. Apply alignment by content role:
- 102 `InlineRuns`. (Line numbers are deliberately not given here — they drift every time the file
- 103 grows; see `scripts/README.md`'s function-name lookup table instead.) Full write-up: ISSUE-004.
+ 101 `InlineRuns`. Use `scripts/README.md`'s function-name lookup table. Full write-up: ISSUE-004.
- 111 Two SDK traps come with it (wrong class name, wrong element order) — ISSUE-005, ISSUE-006.
+ 109 SDK traps include the wrong class name and wrong element order — ISSUE-005, ISSUE-006.
- 120 machine picks. Shipped defaults: Latin `Times New Roman`; East Asian 宋体 for body, 黑体 for
- 121 headings. Chinese **bold runs switch family to 黑体** — 宋体 has no true bold weight and
- 122 renderer-synthesized bold smears multi-stroke characters (ISSUE-014). Sizes are OpenXML
- 123 half-points — body 21 (10.5pt, the common Chinese manuscript size), H1 36 (18pt), clause
- 124 heading 28 (14pt). Body paragraphs also get a 2-character first-line indent (`420` twips at
- 125 10.5pt — change it in lockstep with the body size). ISSUE-007.
+ 118 machine picks. Read the current fonts, half-point sizes and body indent in
+ 119 [`scripts/Program.cs`](scripts/Program.cs), at its constants and `RunProps`/`Para` callers.
+ 120 Keep body size and its character-based first-line indent in sync. Chinese bold-family
+ 121 handling is defined in `RunProps`; the rendering failure and verification are in ISSUE-014.
- 129 A4 is 11906 × 16838 twips with 1440 twip margins; page number goes in a centered footer
- 130 `PAGE` field. Tables need all six borders (`top`/`bottom`/`left`/`right`/`insideH`/`insideV`,
- 131 in that ECMA-376 order — ISSUE-013) and a `tblGrid` (ISSUE-012) — set fewer borders and cells
- 132 look unruled in print; omit `tblGrid` and the file fails strict validation even though
- 133 LibreOffice hides it. Implemented in `BuildTable` and the `SectionProperties`/`FooterPart`
- 134 setup in `Main` — see `scripts/README.md`'s lookup table.
+ 125 Use [`scripts/Program.cs`](scripts/Program.cs) for the current page, margin and footer
+ 126 profile. Tables need complete borders and a `tblGrid`: missing borders leave cells unruled
+ 127 in print; a missing grid fails strict validation even when LibreOffice hides it.
+ 128 Preserve the schema order documented at `BuildTable`; ISSUE-013 explains the failure.
+ 129 Find the page/footer setup at `SectionProperties`/`FooterPart` in `Main`.
- 144 `pdftoppm -png` → `Read` every page image → check the five failure modes
- 145 (info blocks not stretched / each list restarting at 1 / table borders present / signature
- 146 block intact / no orphaned pagination) → **assess and use the existing authorized, observable
+ 139 `pdftoppm -png` → `Read` every page image → check the failure modes in the verification
+ 140 protocol → **assess and use the existing authorized, observable
- 163 **Before overwriting a delivered .docx**, check for a sibling `~$<name>.docx` — that is Word's
- 164 owner lock, meaning the recipient has the old version open. Overwriting works, but they will
- 165 keep seeing the stale document until they close and reopen it. Tell them. ISSUE-011.
+ 157 **Before replacing a generated .docx**, follow
+ 158 [the holder and output-identity check](references/verification_protocol.md#before-replacing-a-generated-docx).
+ 159 Preserve signed/template/returned originals. A lock is a signal, not proof of a live holder
+ 160 or safe release; keep unknown holder/release states pending and verify the new output
+ 161 independently of the lock. ISSUE-011 records the stale-open-copy failure.
- 169 `scripts/Program.cs` is ~260 lines of straightforward OpenXML. Edit it directly for fonts,
+ 165 Edit `scripts/Program.cs` directly for fonts,

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 8   导出的审阅稿；收到带修订模式改动的回稿要看对方改了什么；已有明确已发基线，要核对无批注、
- 9   无修订回稿的全文改动。核心保证：修订感知——python-docx
+ 8   导出的审阅稿；收到带修订模式改动的回稿要看对方改了什么；已有明确基线，要核对无批注、
+ 9   无修订稿的全文改动。修订感知——python-docx
- 11   不漏。只读，不改对方文件。边界：生成/排版 docx → docx-creator 或 minimax-docx；PDF 批注不在范围。
+ 11   读取已支持的批注、段落增删与文本视图；范围见正文。只读，不改对方文件。
+ 12   边界：生成/排版 docx → docx-creator 或 minimax-docx；PDF 批注不在范围。
- 66 要看某条批注前后更多上下文段落（对账表锚定列截断到 60 字，`--json` 里是全文）：
+ 67 要看某条批注前后更多上下文段落（Markdown 锚定列为缩略文本，`--json` 里是全文）：
- 81 两个方向的漏读都在真实出版审阅稿上踩过。本 skill 的 csx 引擎基于 Word 工程团队
- 82 官方维护的 OpenXML SDK，ins/del/move 是一等公民。机制细节、段落索引语义（body 直接子段，
+ 82 两个方向的漏读都在真实出版审阅稿上踩过。本 skill 的 csx 引擎基于 OpenXML SDK，旧读取
+ 83 接口报告所支持的段落增删及文本视图，不保证覆盖所有修订类型。机制细节、段落索引语义（body 直接子段，
- 87 `list_revisions()` / `extract_views()` / `paragraph_text()`，全部无状态直读 docx，按
- 88 (路径+mtime) 做内存缓存。写自定义分析时 import 它，别绕过它手解 XML。
+ 88 `list_revisions()` / `extract_views()` / `paragraph_text()`；调用与缓存行为由该文件定义。
+ 89 写自定义分析时 import 它，别绕过它手解 XML。
- 90 ## 已发基线与回稿的全文对比（含零审阅痕迹）
+ 91 ## 明确基线与对照稿的全文对比（含零审阅痕迹）
- 92 先固定准确已发基线和回稿，保留原件。读取
+ 93 先固定准确基线和对照稿，保留原件。核对对方回稿时，基线必须有实际发送证据；用户明确
+ 94 指定的双版本控制、生成件与人工编辑件也可比较，但不能据此称基线“已发送”。读取
- 96 uv run python scripts/compare_docx.py <已发基线.docx> <回稿.docx>
- 97 uv run python scripts/compare_docx.py <已发基线.docx> <回稿.docx> --json
+ 98 uv run python scripts/compare_docx.py <基线.docx> <对照稿.docx>
+ 99 uv run python scripts/compare_docx.py <基线.docx> <对照稿.docx> --json
- 99 uv run python scripts/compare_docx.py <已发基线.docx> <回稿.docx> --unchanged '付款条件'
+ 101 uv run python scripts/compare_docx.py <基线.docx> <对照稿.docx> --unchanged '付款条件'
- 115 - `DOTNET_ROLL_FORWARD=Major` 已由 client 内置设置（本机 .NET 版本高于 csx 目标版本时自动兼容）。
- 116 - `~/.dotnet/tools` 不在 PATH 时 client 会自动补，无需手动 export。
- 117 - NuGet 包（DocumentFormat.OpenXml 3.2.0，csx 内 `#r` 声明）首跑自动 restore，需要网络，
- 118   首次运行慢约 10-30 秒属正常；之后走本地包缓存。
+ 117 - 环境默认值、工具 PATH 补充与内存缓存由
+ 118   [`docx_bridge_client.py`](scripts/bridge_lib/docx_bridge_client.py) 定义。
+ 119 - NuGet 依赖由 [`scripts/csharp/tasks/`](scripts/csharp/tasks/) 内各 `.csx` 的 `#r` 声明定义。
+ 120   首次 restore 或缺缓存时需要网络；失败读取真实错误，不用固定耗时判断是否正常。
- 126 | `csx script failed … dotnet-script: command not found` | dotnet-script 未装 | 上面依赖节两条安装命令 |
- 127 | 首次运行卡 10-30 秒 | NuGet 首次 restore | 正常，等它；离线环境会失败，需联网首跑一次 |
+ 128 | `csx script failed … dotnet-script: command not found` | dotnet-script 未装 | 按依赖节准备工具 |
+ 129 | 首次运行等待或失败 | 可能需要 NuGet restore | 检查实际输出和现有缓存；缺包的离线环境需在授权范围内完成 restore，不以等待时长判定正常 |

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 129 | 5. A content-bearing path is explicitly approved | `uv run scripts/analyze_large_files.py --threshold 100MB --path "<approved-path>"` | Do not substitute `~`, Downloads, Documents, or the data-volume root when no path was approved |
+ 129 | 5. A content-bearing path is explicitly approved | `uv run scripts/analyze_large_files.py --threshold 100 --path "<approved-path>"` | Do not substitute `~`, Downloads, Documents, or the data-volume root when no path was approved |
- 307 - `scripts/analyze_large_files.py` — large-file discovery inside an approved path.
+ 307 - `scripts/analyze_large_files.py` — large-file discovery inside an approved path; exit 1 marks an incomplete scan (find errors, timeout, unreadable files), never a clean result. "No single file above the threshold" does not make the path small: many below-threshold files can make one directory the dominant cost, so read directory aggregates independently of top single files. Preserving content on a NAS is not the same as local residency. Use an installed, authorized NAS transfer owner (`nas-use` where available); it is not bundled here. Without one, retain the assets and report migration as unverified instead of improvising a copy.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 63 Before dispatching cases from a source corpus, follow
+ 64 [source-case input preparation](references/eval_pipeline_schemas.md#source-case-input-preparation).
+ 65 
+ 126   For resumable writes to human-edited state, include its
+ 127   [interrupted-write controls](references/stateful-script-verification.md#interrupted-writes-and-later-human-changes).
+ 231 For repository publication, enter [release readiness](references/release-readiness.md)
+ 232 before requesting the first review. Select the destination's publication contract,
+ 233 integrate the required base and declare any opt-in rebind dependency scope there;
+ 234 do not discover those prerequisites only when attesting the completed review.
+ 235 

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 29 - NAS retention: when the selected archive already uses an authorized NAS backend, follow the [NAS storage contract](references/archive-storage-contract.md#nas-retained-external-media), including original source identity and full retained-file integrity.
+ 33 
+ 34 Keep source access instructions with the authorized destination's material entry,
+ 35 following the destination handoff; return them with a password-protected source
+ 36 link. Generate aggregate statistics on demand under the storage contract.
- 63 ⚠<U+FE0F> **`base` (Bitable) is not actually operationalized in Path A yet** — the extractor only records the token (`DISPATCH["url-base"]`: *"Bitable API (outside this skill) — record token"*) and Step 2 below has no row for it. Listed here for completeness of what a Feishu URL can be, not as a claim that Path A extracts Bitable content end-to-end.
+ 68 **Resolve wiki nodes before choosing a handler.** Use the actual `obj_type` and its installed CLI guide; for example, `bitable` uses `lark-base`. A `3380002 Unsupported document type` response from `docs +fetch` identifies a handler mismatch, not a permission denial. If the required guide is unavailable, retain the token and type in the worklist as unextracted.
+ 100   Then dispatch on the **actual `obj_type`** — never assume docx: `docx` → step 3 below; `sheet`/`sheets` → step 4 in the reference; `bitable` → the installed `lark-base` guide; `file`/`slides` → the installed `lark-drive`/slides guide. `docs +fetch` on a non-docx `obj_type` fails with `3380002 Unsupported document type '…'. Only docx is supported.` — that error is evidence the wrong handler was selected, not that the source is unreadable.
- 126 [credential-like text hidden]
+ 132 [credential-like text hidden]
- 191 - **Every fetched document — a lone doc as much as a collection**: every hit from the residual rich-media-tag check (Path A step 5, run recursively over the whole working directory) maps to a handled artifact — every `mention-doc`/`cite doc-id=`/`sheet`/cross-tenant reference was **followed** to a fetched leaf file, and every `whiteboard` reference was **exported and read** (not followed — a whiteboard is inline visual content, never a link to recurse into). Raw binaries then map to a stable platform/OSS locator plus optional verified local cache; structured/searchable derivatives map to versioned files. This is not a collections-only check: a standalone document can contain an unresolved `whiteboard` with zero other documents involved. Each document's own `.html` legitimately keeps showing its tags forever (it's an immutable raw capture, never rewritten — as long as each document got its own filename per step 3) — don't chase the grep itself to a literal zero.
+ 197 - **Every fetched document — a lone doc as much as a collection**: every hit from the residual rich-media-tag check (Path A step 5, run recursively over the whole working directory) maps to a handled artifact — every `mention-doc`/`cite doc-id=`/`sheet`/cross-tenant reference was **followed** to a fetched leaf file **or explicitly recorded as outside the user's authorized capture scope** (roots/depth/resource set; a beyond-scope reference stays a locator in the worklist, marked not-captured), and every `whiteboard` reference was **exported and read** (not followed — a whiteboard is inline visual content, never a link to recurse into). Raw binaries then map to a stable platform/NAS/OSS locator plus optional verified local cache; structured/searchable derivatives map to versioned files. This is not a collections-only check: a standalone document can contain an unresolved `whiteboard` with zero other documents involved. Each document's own `.html` legitimately keeps showing its tags forever (it's an immutable raw capture, never rewritten — as long as each document got its own filename per step 3) — don't chase the grep itself to a literal zero.
- 222 - `scripts/check_archive_storage.py` — fail-closed validator for the source/Git/OSS storage split; blocks raw binaries declared as Git artifacts.
+ 228 - `scripts/check_archive_storage.py` — fail-closed validator for the source/Git/NAS/OSS storage split; blocks raw binaries declared as Git artifacts.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 444 - transient notification lifecycle with observation armed before the trigger;
+ 444 - transient notification or game-feedback lifecycle using
+ 445   [Transient UI](references/journey-and-page-contracts.md#transient-ui), with
+ 446   observation armed before the trigger;

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 18 ## Ghostty interaction channel
+ 19 
+ 20 For computer-use observation or interaction with Ghostty, use **Kimi computer use**
+ 21 (`kimi-cu` / `mcp__kimi_cu__*`). **Never use Codex computer use** (`mcp__cua_repl`)
+ 22 for Ghostty, including screenshots, clicks, typing and tab/window management.
+ 23 Prefer Kimi for ad hoc interaction. The existing `osascript` / System Events batch
+ 24 restore helpers remain allowed under the foreground and reconciliation rules below.
+ 25 Snapshot, planning and read-only checks may continue through their existing scripts.
+ 26 If Kimi is unavailable, report that gap rather than substituting Codex computer use;
+ 27 use an existing script only when it supports the task and is already authorized.
+ 28 Never use either channel to bypass a host denial.
+ 29 
- 20 work even when launched as a background shell job. Before restore, use a concrete
- 21 Ghostty handoff or existing explicit idle-desktop permission; check current activity
- 22 and coordinate exclusive agent ownership. Under that standing grant, notify and
- 23 execute without asking again. Idle input alone is not ownership. If busy/unknown,
- 24 continue preparation and read-only checks; stop input on human takeover and never
- 25 restore your old focus. Host denials remain binding.
+ 32 work even when launched as a background shell job. Apply the current user's
+ 33 foreground authorization. When it already covers this app and action, notify and
+ 34 proceed without requesting another handoff or requiring a lease or idle proof.
+ 35 Coordinate observed competing use. On human takeover, actual agent competition or
+ 36 externally overwritten state, stop input and yield; do not restore your old focus.
+ 37 If foreground use is not authorized, continue preparation and read-only checks
+ 38 until the missing bounded authorization is supplied. Host denials remain binding.
+ 41 
+ 42 For missing Codex terminals without confirmed Ghostty ownership, load the installed
+ 43 `read-codex-history` Skill and follow its
+ 44 [terminal-session recovery recipe](https://github.com/daymade/claude-code-skills/blob/main/daymade-claude-code/read-codex-history/references/terminal-session-recovery.md).
+ 52 | Snapshot looks too large, or "which sessions were active after <time>?" | Follow [time-window selection](references/session_liveness.md#select-recovery-candidates-by-a-time-window) before choosing a restore set |
- 36 | Minions `native_runtime` session or managed account-adoption error | Do not use the manual switch route; use the owning Account Manager's native session flow |
- 37 | Unmanaged/legacy Codex quota running out; manually switching account, keeping all Codex work | Read codex-account-switch.md; `switch-prepare [--only <unmanaged-uuid>...]` → manual exit/login → `switch-restore` |
- 38 | After a switch, want the same sessions back ("换号后恢复原会话"); opening blocked or delegated | Same SOP's original-set route: deliver the fixed manifest's exact per-SID commands with per-item status; a blank tab is not a recovery |
+ 54 | Minions `native_runtime` session or managed account-adoption error | Follow [account-owner selection](references/codex-account-switch.md#choose-the-account-owner-first) |
+ 55 | Unmanaged/legacy Codex quota running out; manually switching account, keeping all Codex work | Start with [account-owner selection](references/codex-account-switch.md#choose-the-account-owner-first) |
+ 56 | After a switch, want the same sessions back ("换号后恢复原会话"); opening blocked or delegated | Follow [the original-set recovery route](references/codex-account-switch.md#reopen-the-original-recorded-set-not-a-blank-session) |
- 42 Preserve unmanaged/legacy Ghostty Codex sessions before the user manually switches
- 43 ChatGPT accounts, then reopen the original session IDs in one batch. Exclude Claude
- 44 Code and Minions `native_runtime` sessions; those managed rows use the owning Account
- 45 Manager, not this route's manual logout/login or batch restore.
- 46 Read [codex-account-switch.md](references/codex-account-switch.md) before this route.
- 47 Use `scripts/ghostty_session.py switch-prepare` and `switch-restore`; the bundled
- 48 `scripts/ghostty_switch.py` owns fixed-manifest selection, account/process checks,
- 49 duplicate-safe retries and separate authentication reporting.
- 50 If login already changed before capture, use the explicit `switch-restore
- 51 --after-login` branch. For a controlled exit sequence including the executing
- 52 session, use `switch-plan --current-session <full-uuid>` first; it defers that
- 53 session until an independent executor exists. Save its recovery inputs outside the
- 54 exiting terminal with `switch-handoff`, then recheck them with
- 55 `switch-handoff-check`; these commands preserve the host-adapter gap rather than
- 56 authorize an exit. The reference specifies the exact commands and durable
- 57 literal-control receipt.
- 58 
- 59 ```bash
- 60 python3 <skill-dir>/scripts/ghostty_session.py switch-prepare
- 61 # Mixed managed/unmanaged inventory: capture only the eligible unmanaged/legacy UUIDs.
- 62 python3 <skill-dir>/scripts/ghostty_session.py switch-prepare --only <unmanaged-uuid> [...]
- 63 # User: finish work, exit the saved Codex TUIs and manually switch account.
- 64 python3 <skill-dir>/scripts/ghostty_session.py switch-restore
- 65 ```
- 66 
- 67 Default to tabs in one window; use `--layout windows` only when independent windows are requested.
- 68 Keep the printed fixed manifest through the handoff. Treat unresolved capture,
- 69 unverified original processes and missing sessions as incomplete. Recovery means
- 70 reopening the fixed manifest's original IDs; when reopening is blocked or
- 71 delegated (kept old processes, user-managed locks, denied UI automation), follow
- 72 [the original-set route](references/codex-account-switch.md#reopen-the-original-recorded-set-not-a-blank-session)
- 73 and deliver the complete exact per-session commands with per-item status — a
- 74 blank tab is never a recovery. Mode selection,
- 75 account preconditions and partial-restore readiness belong to
- 76 [the switch SOP](references/codex-account-switch.md). Never send process-termination
- 77 signals or switch credentials through this route; normal local exit controls use
- 78 that SOP's authorized-host protocol. Apply the foreground
- 79 conditions above before actual opening; ask only when that handoff is missing. `--dry-run` and `--check`
- 80 remain read-only. Distinguish reopened IDs from new-account requests that worked:
- 81 the script reports authentication as `not_checked` and sends no test prompt.
+ 60 Start with [account-owner selection](references/codex-account-switch.md#choose-the-account-owner-first).
+ 61 For the selected independent-TUI workflow, follow
+ 62 [save before switching](references/codex-account-switch.md#save-before-switching)
+ 63 and [restore or resume the batch](references/codex-account-switch.md#restore-and-resume-an-interrupted-batch).
+ 64 For blocked or delegated reopening, follow
+ 65 [the original-set route](references/codex-account-switch.md#reopen-the-original-recorded-set-not-a-blank-session).
+ 66 Keep command examples, handoff, authorization and acceptance in that SOP.
+ 67 Implementation: [ghostty_switch.py](scripts/ghostty_switch.py).
+ 70 
+ 71 Before reopening sessions, follow
+ 72 [current-set reconciliation](references/restore_mechanics.md#reconcile-the-current-wanted-set).
+ 73 Keep the same explicit manifest and selection through preview, restore and check.
- 89 # After restart (from any directory; needs Accessibility permission for keystrokes):
- 90 python3 <skill-dir>/scripts/ghostty_session.py restore        # manual: active only; automatic: full recorded set
- 91 python3 <skill-dir>/scripts/ghostty_session.py restore --all  # include waiting/quota/dead/stale/unknown records
+ 79 # After selecting the wanted set, preview it before any foreground input:
+ 80 python3 <skill-dir>/scripts/ghostty_session.py restore --snapshot <manifest.json> --all --dry-run
+ 81 # Carry the selected --only/--exclude options into this preview, then omit --dry-run to execute.
+ 84 Without `--all`, manual manifests select active sessions only; automatic manifests
+ 85 select their recorded set. Use `--all` to include waiting/quota/dead/stale/unknown rows.
+ 86 
- 95 The report accounts for every live TUI: captured sessions plus an `unresolved`
- 96 section for fresh tabs that have no transcript yet — a session count lower than
- 97 the tab count is explained there, not silently lost.
+ 88 Manual snapshots record Ghostty process descendants only. They persist resumable
+ 89 AI `sessions`, `unresolved` TUIs, `other_terminals` with cwd/process evidence, and
+ 90 the observed `terminal_inventory`. Other terminal emulators are excluded.
+ 91 Treat a TTY as a terminal surface, not a tab: splits and window membership are
+ 92 unknown. If the user supplies a tab count, record it with `snapshot --expected-tabs <N>`;
+ 93 do not use matching session/TTY totals as proof of current-window coverage.
+ 94 State the unmapped window/tab boundary before the update. An empty observation
+ 95 refuses to replace the previous backup. Non-AI commands and unresolved argv are
+ 96 evidence, not instructions to execute automatically.
+ 102 Repeat current-set reconciliation after a manual handoff or any change in selection.
+ 103 After process reconciliation, follow [history-readiness acceptance](references/restore_mechanics.md#verify-history-readiness-after-process-reconciliation)
+ 104 before claiming that the selected conversations are ready to read.
- 107 or operating `scripts/ghostty_watch.py`. It saves only changed restore state and
- 108 keeps all prior versions. Unchanged
- 109 rounds write no snapshot or routine log. Automatic manifests cover Ghostty
- 110 process descendants without transcript reads; their liveness is explicitly unknown
- 111 and `restore` selects the whole recorded set. UUID-less TUIs remain unresolved in
- 112 automatic manifests — the watcher's bounded scan deliberately reads no transcripts;
- 113 manual snapshot/check/restore resolve them (see the anchor bullet below).
- 114 Partial observations preserve prior missing IDs conservatively. The watcher never

This preview is limited. See the complete change on GitHub.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 37 - **Resolve authority from the current request and applicable standing user instructions.**
+ 38    Authority for any action under this Skill is the current request read together with the standing
+ 39    user instructions that apply to this task (for example, a standing instruction that a task ends
+ 40    with checks, commit, publication, readback, and retiring that task's own temporary
+ 41    branches/worktrees). Later user restrictions still control. Splitting the work into phases alone
+ 42    does not revoke authority the task already carries: when the task already includes retiring its exact temporary resources, complete Mode E
+ 43    within that same task — a new task or fresh confirmation solely for entering retirement is a
+ 44    re-ask, not a gate. Mode E's evidence, preservation, and readback gates still apply in full.
+ 45    A merge alone still does not authorize extra targets, and targets the task's authority does not
+ 46    name stay report-only until separately authorized.
- 147    counts for the *nearest* content check is not enough: in one audit, three successive
+ 157    counts for the *nearest* content check is not enough: in one audit, successive
- 151    files by 5×**), and a file-level existence check (a file present on base can still be missing
+ 161    files**), and a file-level existence check (a file present on base can still be missing
- 339 (in memory, no checkout) and only reports content containment when that merge changes nothing — so a
+ 349 (without checkout) and only reports content containment when that merge changes nothing — so a
- 354 repo of branches, the read-only fan-out pattern — one agent per batch, each told to *falsify*
+ 364 repo of branches, the verification fan-out pattern — one agent per batch, each told to *falsify*
- 374   (§ Shared checkout and concurrent sessions: one writer — also governs the two "parallel session"
- 375   bullets below, and now also covers finding an unidentified writer by process evidence rather
+ 384   (§ Shared checkout and concurrent sessions: one writer — also governs the "parallel session"
+ 385   bullets below and covers finding an unidentified writer by process evidence rather
+ 391 - **Failed fast-forward or partially synchronized checkout:** follow
+ 392   [Guarded checkout recovery](references/prevention_practices.md#guarded-checkout-recovery).
- 395   lease for automation under this generic Skill. Retire refs or checkouts only through separately
- 396   authorized Mode E evidence. (§ Known automated writers are not session-owned WIP.)
+ 407   lease for automation under this generic Skill. Retire refs or checkouts only through Mode E
+ 408   evidence, with authority resolved per the authority definition in the Outcome contract above.
+ 409   (§ Known automated writers are not session-owned WIP.)
- 421   back. Branch deletion remains a separately authorized Mode E action.
+ 434   back. Branch deletion remains a Mode E action, with authority resolved per the authority
+ 435   definition in the Outcome contract above; a merge or handoff does not itself authorize it.
- 456   and why the two obvious "did their work survive?" probes return the wrong answer, in **A foreign
+ 470   and why the "did their work survive?" probes return the wrong answer, in **A foreign
- 511   `D ` lines in `git status`. Two obligations follow. **Whoever advanced the branch past the index
+ 525   `D ` lines in `git status`. **Whoever advanced the branch past the index
- 529 Start from the Outcome contract. For an exhaustive audit or unknown target, run checkout discovery;
+ 543 Start from the [Outcome contract](#outcome-contract--keep-the-safety-net-subordinate-to-the-users-job), including its authority definition.
+ 544 For an exhaustive audit or unknown target, run checkout discovery;
- 535 and targeted exports instead:
+ 550 and targeted exports instead. Preserve the original authorized outcome when a batch finishes:
+ 551 unreviewed refs and unlanded keeper changes remain unfinished even after its worktrees or backup
+ 552 have been handled.
- 543    `scripts/git_classify_refs.sh` runs this exact rung across every branch in one offline pass.
+ 560    `scripts/git_classify_refs.sh` runs this exact rung in one offline pass. For a selected or
+ 561    delegated batch, use its `--expected-common-dir` and `--target-manifest` binding from
+ 562    [the frozen-snapshot recipe](references/merge_verification.md#1-freeze-the-outcome-and-the-first-ref-snapshot).
+ 563    Read the actual coverage and unresolved rows, not just exit 0: this is a classification report,
+ 564    not proof that keeper content reached main or that authorized cleanup finished.
- 615   current-session deletion authority. As the final pre-remove gate, re-run the empty status and
+ 636   deletion authority per the authority definition in the Outcome contract above. As the final
+ 637   pre-remove gate, re-run the empty status and
- 625   primary/current checkout; retire its branch only as a separate,
- 626   separately authorized action. Follow
+ 647   primary/current checkout; retire its branch only as a separate action under the authority
+ 648   definition in the Outcome contract above. Follow
- 735 | `scripts/git_verify_branch_merged.sh <branch> [base] [--no-fetch] [--base REF] [--merge-commit SHA]` | Give a content-level MERGED/UNMERGED verdict for one branch. `--merge-commit` adds a rung that proves containment at a historical merge commit when base later changed the same lines and the CURRENT base can no longer prove it; the verdict also names the current-base shape (conflict = routine, clean-but-changes = regression candidate). `--no-fetch`/`--base` support offline and flag-driven batch use | Remote-tracking refs only (skipped entirely with `--no-fetch`) |
- 736 | `scripts/git_classify_refs.sh --base SHA [--pr-map JSON] [--all-namespaces]` | Batch version of the above: classify every local/remote-tracking branch against one frozen base in a single offline pass (ancestor / content-contained / needs-review, with file-count-changed); `--pr-map` overlays the `--merge-commit` rung from a hosting platform's PR export | Nothing (read-only, no fetch — pin the base with `git rev-parse` first) |
+ 757 | `scripts/git_verify_branch_merged.sh <branch> [base] [--no-fetch] [--base REF] [--merge-commit SHA]` | Give a content-level MERGED/UNMERGED verdict for one branch. `--merge-commit` adds a rung that proves containment at a historical merge commit when base later changed the same lines and the CURRENT base can no longer prove it; the verdict also names the current-base shape (conflict = routine, clean-but-changes = regression candidate). `--no-fetch`/`--base` support offline and flag-driven batch use | Remote-tracking refs unless `--no-fetch`; trial merges can write unreferenced Git objects in either mode |
+ 758 | `scripts/git_classify_refs.sh --base SHA [--pr-map JSON] [--all-namespaces]` | Batch content classification; bind a selected set with `--expected-common-dir PATH --target-manifest TSV` to reject another clone or missing/moved tips and report full OIDs plus coverage. Classification success does not establish convergence. `--pr-map` retains the historical-merge rung. | Trial merges can write unreferenced Git objects; no fetch or changes to refs, index or working files; no ownership or deletion authority |
- 746 Only `git_find_all_checkouts.sh` is repository-read-only and safe beside read-only agents; it never
- 747 fetches, so it also works offline and behind a proxy. Any helper that fetches, writes backup state,
- 748 or adds refs runs only after existing coordination transfers exclusive writer ownership. None of
+ 768 Any helper that fetches, writes backup state,
+ 769 adds refs, or creates trial-merge objects runs only after existing coordination transfers exclusive writer ownership. None of

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 4   Operates GitHub via gh CLI and REST/GraphQL — PRs, issues, Actions, repos, collaborators, org
+ 4   Operates GitHub via gh CLI and REST/GraphQL — PRs, issues, Actions, self-hosted Runner inventory/capacity, repos, collaborators, org
+ 115 For PR merges, use the checked `pr merge` entry with an explicit PR and full
+ 116 `--match-head-commit`. It checks the live head and effective approval/merge state.
+ 117 Raw REST and GraphQL PR merge writes are rejected: an eligible actor can otherwise
+ 118 use bypass privileges without an `--admin` argument. Follow the
+ 119 [merge and explicit-bypass contract](references/pr_operations.md#merging-prs).
- 123 the same helper; do not bypass the actor check. A failed or timed-out invocation
+ 128 the same helper, except PR merge writes, which stay on the guarded `pr merge`
+ 129 entry. Do not bypass the actor check. A failed or timed-out invocation

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 192 them for local three-way analysis.
+ 192 them for local three-way analysis, or use a local clean result to override a hosted
+ 193 merge refusal. Reconcile disagreement through the diagnostic below.
+ 298 
+ 299 #### When local and hosted merge results disagree
+ 300 
+ 301 The reviewing agent runs this diagnostic when local three-way analysis is clean but
+ 302 GitHub reports `CONFLICTING`/`DIRTY`, or the reverse. Ordinary matching results do not
+ 303 require a second merge. Preserve both observations; green CI tests a candidate, not
+ 304 whether the host can merge it.
+ 305 
+ 306 1. Re-read the hosted head and independently resolved live base, then verify the local
+ 307    objects match both full OIDs. Recompute changed inputs first; different snapshots
+ 308    do not establish a difference in merge semantics.
+ 309 2. Inspect the affected paths' effective `merge` attributes with `git check-attr merge
+ 310    -- <paths>`, the relevant `.gitattributes` at both tips, `.git/info/attributes`, and
+ 311    attribute/config sources (`core.attributesFile`, `merge.default`, and
+ 312    `merge.<driver>.driver`/`recursive`). Record the checkout/attribute context and Git
+ 313    version used by the original local merge. Inspect driver commands before executing
+ 314    them: a PR-controlled driver is untrusted code. Repository attributes and locally
+ 315    configured drivers can produce semantics different from the hosted merge.
+ 316 3. Counter-test the same OIDs with the suspected driver replaced by ordinary text
+ 317    merging for that invocation only. For an effective `merge=union`, use:
+ 318 
+ 319    ```bash
+ 320    git -c 'merge.union.driver=git merge-file %A %O %B' \
+ 321      -c merge.union.recursive=text \
+ 322      merge-tree --write-tree --messages "$CURRENT_BASE_SHA" "$HEAD_SHA"
+ 323    ```
+ 324 
+ 325    This replaces only the named `union` driver; it is not a full GitHub emulator.
+ 326    Adapt the override to each inspected nonstandard driver involved; retain binary
+ 327    paths' intended semantics. Save both exit codes, tree OIDs and conflict paths/stages.
+ 328    A counter-test's nonzero tree is conflict evidence, never a landable tree.
+ 329 4. If the counter-test exposes a conflict hidden by local drivers, explain that
+ 330    concrete difference and inspect the conflicting contents. If it stays clean,
+ 331    keep the hosted discrepancy unresolved until a bounded fresh hosted read or other
+ 332    evidence explains it; do not declare a cache fault from `DIRTY` alone. Stop repeated
+ 333    archive/review/CI or branch-update cycles that add no evidence about the mismatch.
+ 334 
+ 335 Keep configuration, protections and published history unchanged during diagnosis.
+ 336 Only an already-authorized repair may resolve and integrate the actual conflict;
+ 337 then recheck the resulting exact head/live base and required checks. Reuse unaffected
+ 338 evidence under the repository's policy. A local clean result alone never grants a
+ 339 merge bypass or branch-update permission.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 15 ## Overview
- 16 
- 17 The official Tencent IMA skill (ima-skill) exposes a powerful OpenAPI for notes and knowledge base operations, but its installation flow is designed for a specific proprietary agent and recent releases have shipped submodule files that fail strict SKILL.md loaders. IMA Copilot solves both problems:
- 18 
- 19 1. Installs ima-skill to Claude Code, Codex, and OpenClaw in a single command via the [vercel-labs/skills](https://github.com/vercel-labs/skills) open installer.
- 20 2. Walks the user through API key setup with a live validation call.
- 21 3. Detects known upstream issues and — with explicit user consent — fixes them in place, without ever forking, vendoring, or mirroring any part of the upstream package.
- 22 4. Provides a fan-out search strategy that respects user-configured knowledge base priorities and boosts, with awareness of the 100-result per-KB truncation limit.
- 23 
- 37 | 1. Install upstream ima-skill to 3 agents | `scripts/install_ima_skill.sh` | See `references/installation_flow.md` |
+ 28 | 1. Install upstream ima-skill to supported agents | `scripts/install_ima_skill.sh` | See `references/installation_flow.md` |
- 68 The script auto-detects which of the three target agents are installed on the user's machine. For agents that are not present, it skips silently rather than installing anywhere the user hasn't opted in. For agents that are present, it installs globally (`-g`) in vercel skills' default symlink mode: the first detected agent's directory becomes the canonical copy, and the remaining agents are symlinked to it. This means a repair or an upgrade applied once propagates automatically to every agent — `diagnose.sh` detects this sharing and dedupes its reports so you don't see the same issue multiple times.
+ 59 The script auto-detects which target agents are installed on the user's machine. For agents that are not present, it skips silently rather than installing anywhere the user hasn't opted in. For agents that are present, it installs globally (`-g`) in vercel skills' default symlink mode: the first detected agent's directory becomes the canonical copy, and the remaining agents are symlinked to it. This means a repair or an upgrade applied once propagates automatically to every agent — `diagnose.sh` detects this sharing and dedupes its reports so you don't see the same issue multiple times.
- 80 Environment variables `IMA_OPENAPI_CLIENTID` and `IMA_OPENAPI_APIKEY` act as fall-back overrides — the wrapper reads the environment first, then the config file.
+ 71 Environment variables `IMA_OPENAPI_CLIENTID` and `IMA_OPENAPI_APIKEY` take precedence; missing values fall back to the config files.
- 106 ✅ API credentials valid (search_knowledge_base returned 12 KBs)
+ 97 ✅ API credentials valid (search_knowledge_base returned <count> KBs)
- 143 Every repair is **temporary in the sense that ima-skill upgrades replace everything**. This is by design: the skill does not fight upstream for persistent state. When the user upgrades ima-skill via Capability 1, Step 4 of diagnose will again flag the fixed issue, and the user can rerun the repair. This is a feature, not a bug — if upstream eventually fixes the issue, the repair becomes unnecessary and `diagnose.sh` will report ✅ with no prompt.
+ 134 Upgrading ima-skill can replace local repairs. After an upgrade, rerun `diagnose.sh` and follow the existing repair workflow only for issues that return. If upstream has fixed the issue, diagnosis reports it healthy and no repair is needed.
- 147 IMA's OpenAPI has three hard constraints that any serious search workflow must account for:
- 148 
- 149 1. **No cross-knowledge-base endpoint.** `search_knowledge` requires a single `knowledge_base_id` per call. Cross-KB search is a client-side fan-out, not an API feature.
- 150 2. **No relevance score in results.** `info_list` items only carry `media_id`, `title`, `parent_folder_id`, and `highlight_content`. Any ranking beyond insertion order must happen on the client.
- 151 3. **Silent 100-result truncation.** `search_knowledge` returns at most 100 hits per KB with no `is_end` or `next_cursor` field in the response. High-frequency queries are silently capped.
- 152 
- 153 `scripts/search_fanout.py` implements the full workaround:
+ 138 Follow [the search workflow](references/search_best_practices.md) for API constraints,
+ 139 enumeration, ranking, permissions and truncation handling. Run its bundled helper:
- 159 The script reads `~/.config/ima/copilot.json` for personalization (priority KBs, skip list, strategy), calls `search_knowledge_base` to enumerate KBs, fans out `search_knowledge` calls in parallel, detects truncation by exact-100 length match, and renders results grouped by KB with priority groups at the top.
- 160 
- 163 For the full algorithm, truncation handling strategy, rendering format, and a walkthrough of the evidence-based decision to allow a "subset KB skip" (e.g., a curated KB that is a strict subset of a master KB can be safely skipped to reduce duplicate hits), read `references/search_best_practices.md`.
+ 147 For knowledge-base listing parameter errors, use the search workflow's
+ 148 “Knowledge-base enumeration” procedure before diagnosing authentication or access.
- 171 - **Never vendor upstream content.** This directory does not contain and will never contain a copy of `ima-skill/SKILL.md`, `ima-skill/notes/**`, `ima-skill/knowledge-base/**`, or any other upstream file. Anyone adding such files to this skill should be rejected.
- 173 - **Never silently patch upstream files.** Every modification path requires an explicit AskUserQuestion and the user's active choice.
- 176 
- 177 ## File layout
- 178 
- 179 ```
- 180 ima-copilot/
- 181 ├── SKILL.md                         # This file — entry and routing
- 182 ├── scripts/
- 183 │   ├── install_ima_skill.sh         # Download → stage → npx skills add to 3 agents
- 184 │   ├── diagnose.sh                  # Read-only health report
- 185 │   └── search_fanout.py             # Fan-out search with priority grouping
- 186 ├── references/
- 187 │   ├── installation_flow.md         # Capability 1 deep dive
- 188 │   ├── api_key_setup.md             # Capability 2 deep dive
- 189 │   ├── known_issues.md              # Issue registry — source of truth for repairs
- 190 │   ├── search_best_practices.md     # Capability 4 deep dive
- 191 │   └── import_and_extract.md        # Capability 5 deep dive
- 192 └── config-template/
- 193     └── copilot.json.example         # Template for ~/.config/ima/copilot.json
- 194 ```

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 15 ## 先按交付物选模式
+ 15 ## 先选择执行分支
+ 16 
+ 17 用 kimi-cu 操作 macOS 应用时，先读 [通用桌面操作法](references/kimi-cu-desktop-automation.md)，按当前应用自身的任务合同执行。只使用通用桌面分支的任务到该参考继续；下文 Kimi.app 的模式/模型、插件调用、计费与取数权威源复核不适用于其它应用的消息或报告读取。
+ 18 
+ 19 需要 Kimi.app 官方插件或 Chat 深度研究时，再进入下方业务分支。
+ 20 
+ 21 ## 在 Kimi.app 内按交付物选模式
- 46 | **用 kimi-cu 驱动任意 macOS 桌面应用**（Electron / webview / 原生；表单填写、弹窗、前台化、AX 树恢复） | **`references/kimi-cu-desktop-automation.md`**——可靠性分层与操作配方，与 Kimi.app 业务无关、可独立使用 |
+ 52 | **用 kimi-cu 驱动任意 macOS 桌面应用**（Electron / webview / 原生；表单填写、弹窗、前台化、AX 树恢复） | **先读 `references/kimi-cu-desktop-automation.md`**——按当前工具合同绑定权限、目标、读回与重试前提，再选配方；与 Kimi.app 业务无关、可独立使用 |

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 17 Six dimensions, usually scattered across ad-hoc scripts that get rewritten (with the
- 18 same bugs) every time:
+ 17 Choose from the following evaluation dimensions:
- 22 | **Availability** | `scripts/availability_probe.py` | which model IDs work here, with 3-state error classification |
+ 21 | **Availability** | `scripts/availability_probe.py` | which model IDs work here, with explicit error classification |
- 49 Don't run all six ritually — pick what answers the user's question.
+ 48 Run only the dimensions that answer the user's question.
- 86 (below). Pick dimensions by what the user actually asked — don't run all six if they only
- 87 asked "is it fast?".
+ 85 (below). [Select the dimensions for the task](#which-dimensions-to-run).
- 101 - Verdicts are 3-state per failure, not pass/fail: `no-channel` (no route for this
- 102   ID), `upstream-error` (route exists, upstream failing — retry later), `empty-content`
- 103   (usually a max_tokens artifact on reasoning models, NOT a broken model). The probe
- 104   keeps `--max-tokens` at 8192 by default precisely so thinking models don't read as
- 105   dead — do not "optimize" it downward.
+ 99 - Read transport, response outcome and native terminal fields separately. The probe
+ 100   reports `response_outcome` as `answered`, `refused`, `empty` or `unknown`;
+ 101   `transport_ok` means HTTP response headers arrived, not that a usable answer did.
+ 102   `refused` preserves explicit refusal/content-filter markers even when text exists;
+ 103   it does not establish model/provider unavailability. An empty `end_turn` remains
+ 104   cause-unknown; thinking characters alone do not prove token-budget exhaustion.
+ 105   `no-channel` means no route for this ID; `upstream-error` means the upstream failed
+ 106   this request. Keep the generous default `--max-tokens` rather than manufacturing
+ 107   empty replies with a tiny budget. Native `stop_reason`, `finish_reason`,
+ 108   `stop_details` and `refusal` are retained when present, including null/empty values.
+ 109   Exit 1 means at least one probe lacks a usable answer; it is not a service diagnosis.
- 128 - Four checks: `system` (canary code planted in the system prompt — can the model echo
+ 132 - Probe `system` (canary code planted in the system prompt — can the model echo
- 141   `--repeat` (default 10) and a three-state verdict (delivered / intermittent k-of-N /
+ 145   `--repeat` (default 10) and a verdict (delivered / intermittent k-of-N /
- 184 - Distinguish failure modes from the output: HTTP 429 (clean throttle, retriable) vs a TCP
- 185   drop that hangs to timeout (much worse for UX) vs 5xx. They imply very different fixes.
+ 188 - Distinguish failure modes using the status and structured error code/type. HTTP 429 can
+ 189   mean a transient rate limit or exhausted quota; retry only the former with the provider's
+ 190   backoff/reset guidance. Quota exhaustion needs entitlement/quota recovery, not a concurrency
+ 191   retry loop. A TCP drop that hangs to timeout (much worse for UX) and 5xx remain
+ 192   separate observations with different fixes.
- 222   why `--repeat` defaults to 10; generation's verdict has three states (`fully-implemented`,
- 223   `intermittent (k/N)`, `not-implemented`), history-replay's has its own three-plus states
+ 229   why `--repeat` defaults to 10; generation reports `fully-implemented`,
+ 230   `intermittent (k/N)` or `not-implemented`; history-replay reports
- 233 This is two halves on purpose: **collect**, then **judge independently**.
+ 240 **Collect**, then **judge independently**.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 89 For admission decisions, account/resource bindings or recovery that can authorize
- 90 an effect, load [admission and recovery acceptance](references/admission-recovery-acceptance.md)
+ 89 For admission decisions, account/resource bindings, retained sessions or cached
+ 90 permissions across upgrades, and recovery that can authorize an effect,
+ 91 load [admission and recovery acceptance](references/admission-recovery-acceptance.md)

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 50   regardless of what you draw. This line used to open with "Chosen form →", which reads as a
- 51   precondition; a 2026-08 delivery filed the file under "the implementation lookup I'll consult
- 52   if I build one of those components", never opened it, and shipped a page missing three of its
- 53   rules. The gate a step hides behind must not be a step you have not taken yet.
+ 50   regardless of what you draw.
+ 65 - Version-comparison reading order, paired evidence and full-text inspection:
+ 66   `references/version-comparison-reading.md`. Load when the page explains what
+ 67   changed between editions; keep source interpretation separate from presentation.
- 197    Use the nearest approved register; do not copy a skin blindly. (This step used to say
- 198    "the *activated* pattern reference", which let the patterns file be filed as not-yet-needed
- 199    and skipped; the SSOT map above explains why that filter cannot work here.)
+ 197    Use the nearest approved register; do not copy a skin blindly.
- 228    consumer rather than being one more thing only you referee. (It was prose-only for exactly
- 229    one version, and an independent audit named it the next rule likely to get skipped — the
- 230    variable that decides whether a step survives is not "does it produce an artifact" but
- 231    "does anything downstream consume the artifact". The visual-discipline gates were
- 232    already artifact steps when they got skipped.)
- 233 
- 234    Why this is a numbered step rather than a principle: the rule already lived in
- 235    `design-principles.md` §2 *and* in `data-visualization-discipline`, and was read in both
- 236    places immediately before a delivery that shipped eight prose sections and one geometry.
- 237    A judgment step whose only referee is its author gets **comprehended instead of executed**.
- 238    These two attributes are what let a script see whether the step happened.
+ 226    consumer rather than being one more thing only you referee.
- 244    caller's template into this Skill's update-owned `assets/`. Use actual shelf
- 245    components. If the page embeds mutable source documents, follow the long-lived-report
+ 232    caller's template into this Skill's update-owned `assets/`. Before updating an accepted
+ 233    report's facts or content, follow the [incremental maintenance recipe](references/long-lived-report-maintenance.md#63-已验收报告的有界增量更新).
+ 234    Use actual shelf components for new or changed interactions; retain the approved
+ 235    embedded implementation during a data-only update. If the page embeds mutable source documents, follow the long-lived-report
- 505 **Where a new lesson goes — two questions, in this order, before writing one into this skill.**
+ 495 **Where a new lesson goes — answer in this order before writing one into this skill.**
- 597    Two outputs to read correctly rather than wave through. The reconciler prints **how many
+ 587    Read tool output rather than wave it through. The reconciler prints **how many
- 633 5. **Delivery gate ran, and its answers describe this page** — ask for three things, because
- 634    the first two are cheap to fake and the third is what makes them mean something:
+ 623 5. **Delivery gate ran, and its answers describe this page** — check the artifacts and
+ 624    independently compare their recorded answers with the rendered evidence:
- 641    compare the two counts — the masked render is the ground truth here. **Two things before you call a mismatch:** a
+ 631    compare the two counts — the masked render is the ground truth here. **Before calling a mismatch:** a

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

- 79   本机落地状态（§2 脚本）→ [监测轮的线索决策](#监测轮从信息到可行动信号)与台账回填。
+ 79   当前已核身份的实时用量与 banked（`scripts/query_usage.py`，见账号 SOP）→
+ 80   [监测轮的线索决策](#监测轮从信息到可行动信号)与台账回填。
+ 81   先完成能回答当前问题的读取。仅在用户要求历史复盘、需要解释窗口异常，或未兑现承诺的
+ 82   发生区间确实需要匿名快照补证时执行 §2；按相关事件选择回溯天数，不默认重建七天曲线。
+ 83   匿名快照仍不能替账号补身份或独自证明到账。到期未决项继续按 `followup` 逐项核验，
+ 84   不因当前事件已有完成帖而清除旧问题；追加来源不能改变当前有界结论时停止扩查。
- 83   evidence_refs 挂链（见[预测反馈的 findings 节](references/forecast-feedback.md)）。**§2 之后必须再跑一次实时 banked 查询**（`scripts/query_usage.py`，读法与字段表见
- 84   [账号 SOP](references/account-usage.md)）——§2 的 rollout 快照结构上没有备用重置字段，不跑就
- 85   答不全「现在什么情况」这个最常被问的维度；只取 banked 一个数即可，并把输出里的 `account_ref` 一起记进 findings（记录规则见 forecast-feedback.md 的隐私契约，banked 计数的可比范围见账号 SOP）；本条其余部分仍只管重置状态。
- 86   ⚠<U+FE0F> **scan 与 banked 不要 `&&` 串联**：scan_rollouts 无快照时 exit 1，`&&` 会把 banked 查询直接
- 87   短路掉——表面上全套像跑过了，实际少一维（2026-09-19 实测）。两条分开跑，或串联时给 scan
- 88   加 `|| true`。**循环场景下 skill 里的裸命令被 `same-cmd-resend-guard` 拦**（端点抖动失败一次
- 89   后逐字节重发即拦）——命令开头加 `cd <skill 绝对路径> &&` 换结构即放行（2026-09-19 实测）。
+ 88   evidence_refs 挂链（见[预测反馈的 findings 节](references/forecast-feedback.md)）。
+ 89   **实时 banked 查询不能被 §2 替代**：rollout 快照结构上没有备用重置字段。本轮已有身份
+ 90   核实、时间仍适用的实时读数时直接复用；缺失、查询期间发生切号或新事件使旧读数失效时，
+ 91   再按[账号 SOP](references/account-usage.md#实时-api只读一个明确账号)补查并保存同次读数与
+ 92   `account_ref`；计数比较和字段判读也沿该入口执行。本条不授权切号或兑换备用。
+ 93   **scan 与 banked 独立执行并分别记录退出状态**：`scan_rollouts.py` 无快照时退出非零，
+ 94   只表示所选窗口没有观测，不能据此认定没有重置，也不能短路实时 banked 查询。参数、
+ 95   读取或运行错误仍保留失败／unknown；不要用 `|| true` 吞掉错误。
+ 96   宿主提示重复失败时，先核对失败原因和重试依据，再按提示处理；绝对路径只用于纠正
+ 97   已证实的 cwd 问题，不为改变命令文本而绕过提示。修复依赖或取得新证据后再作有依据的重试。
- 137 - 想**自动**驱动隔离 Chrome 查第二账号用量 → `node scripts/read-usage-profile.cjs`（依赖
- 138   `~/.chrome-profiles/tibo-cdp/` 的 playwright；默认 profile a）。读模式直接解析当前登录账号
+ 145 - 想**自动**驱动隔离 Chrome 查第二账号用量 → `node scripts/read-usage-profile.cjs`（默认 profile a）。
+ 146   脚本先解析普通 playwright 安装；未安装时回退到 `~/.chrome-profiles/tibo-cdp/node_modules/playwright`，
+ 147   可用 `TIBO_PLAYWRIGHT_PATH` 指定其他 playwright 包路径，不需要手工设置 `NODE_PATH`。
+ 148   读模式直接解析当前登录账号
+ 162 - **已核信息先交付。** 执行者在任一检查环节核实了会改变当前用量或时限决策的信息，先按
+ 163   宿主现有交付合同报告结论、原始来源、带时区的时限及仍未知的范围或到账状态，再继续不影响
+ 164   该提示成立的补证与收尾；不等全套检查、轮末台账或最终长答。应用托管的只读研究任务只向
+ 165   宿主提交约定产物；宿主不支持中途提交时，及时交付当前足以支持决策的结果，把剩余补证条件
+ 166   留给下一轮。沿用已有通知与重试策略，不因本条新增外送、电话或重复提醒；提交或发送回执
+ 167   不证明送达本人或取得 ACK。没有新增可行动事实时，仍按原合同报告覆盖与边界。
- 202 1. **接上上轮的问题。** 读 `forecast_log.py summary --compact`（审计或需要完整叙述时读 `summary`；compact 保留本步全部决策字段），先看 `due_for_followup`（窗口已过期或
- 203    即将关闭、尚无定论的预测——到期跟进项从这里第一眼读，不用翻 rationale；closing_soon 的
- 204    阈值定义见 forecast-feedback.md）；若有 `withdrawal_conflicts`，先核对冲突的撤回与旧版核验；
- 205    若有 `recent_withdrawn`，先排除已撤回的旧窗口；也看 `snapshot.status`——`lagging` 表示台账
- 206    的 git 快照落后（原因与处置见 forecast-feedback.md 的 findings 节），要在本轮汇报里说明；
- 207    再从同一 state-dir 运行 `forecast_log.py handoff`
- 208    读取最新一条 `invocation=monitor` 的完整原始行；`findings` 子命令的紧凑列表不显示
- 209    `notes`，不能用它代替交接正文。`handoff` 返回 `null` 表示尚无监测交接，不能推断此前
- 210    没有值得追的线索。
- 211    其中的 `notes` 记录上轮尚未解决的具体问题、候选来源、下一次复查条件和用户反馈。上轮
- 212    没有记录就从当前问题与现有预测的 `revision_trigger` 建立这些项，不把空台账说成已覆盖。
- 213    本轮即使只做降频查询，也要在新 finding 的 `notes` 里结转未决项或写明已由哪条证据关闭，
- 214    使它始终能从最新轮次读回；逐字读数仍只放 `readings`，判断不得伪装成原始数据。
- 215    同一 state-dir 再运行 `forecast_log.py followup`，执行其 `event_tasks` 与
- 216    `account_tasks`，不要把输出清单当成已经查过。`confirmed_unscored` 表示事件已经确认、
- 217    预测仍不可评分，不为它继续问「重置发生了吗」；`account_followup` 单独保留已绑定账号的
- 218    未到账项。官宣的具体时刻用 `announce` 保存，字段与状态读
+ 218 1. **接上上轮的问题。** 先完整执行[本地预测反馈的回看流程](references/forecast-feedback.md#每次调用先回看)，
+ 219    读完分页和所需原件，再逐项取得事件与账号证据；任务清单不代表已经核验。
+ 220    正常轮与降频轮都按[交接结转](references/forecast-feedback.md#交接结转)生成可接续的当前交接，
+ 221    将判断与原始读数分开保存。只更正一条交接事实时，执行[安全纠错流程](references/forecast-feedback.md#findings原始读数层)，
+ 222    不用只有纠正内容的 monitor 替换完整交接。官宣的具体时刻用 `announce` 保存，字段与状态读
- 232    的新鲜覆盖，就按[社区增量读取](references/forecast-feedback.md#社区增量读取)调用现有
+ 236    的新鲜覆盖且该缺口会改变当前未决判断，就按[社区增量读取](references/forecast-feedback.md#社区增量读取)调用现有
+ 250    同型覆盖多轮且结论收敛（官宣完成措辞确认不存在、可归因账号证据已随上下文关闭、tracker
+ 251    与本机扫描均无新形状）时，在该轮 review 的 lesson 写明收敛结论与重开条件（官方追溯提及、
+ 252    新账号读数通道等），后续轮次不再重复同型挖掘；事件保持 unknown，不伪造失败或命中
+ 253    （2026-10-31 实测：Day21 预测四轮同结论 unknown 后收敛停止）。
- 255    **反向同样成立：官方已明文预告 global 在途时，先等落地再动备用**——global 落地即全员回满，
- 256    此刻兑现备用等于白扔库存（2026-10-11 实测：4 账号全空 + EOD 官宣在途，官宣后 5h45m 落地、
- 257    距 EOD 上限仍提前 ~3h，2 次备用保住未花）。
+ 263    官方已明文预告 global 在途时，通常先保留 banked，并核对已确认的账号适用范围、当前余额、
+ 264    到账状态，以及原本有价值工作的硬截止或延迟成本。预告上限不是保证可安全等待的窗口，
+ 265    重置可能提前；官宣也不证明本人账号已到账。工作可以等待时建议保留备用；延迟成本明确
+ 266    超过保存一张备用的价值时，给出使用备用完成原任务的条件建议及库存代价。账号状态或成本
+ 267    未核实就保留未知，不断言兑现等于浪费，也不自动兑换备用。
- 312 完全没有索引一条新的独立主帖；主帖时间线也不含 replies，所以前两条都无新仍不能跳过 reply
+ 322 完全没有索引一条新的独立主帖（滞后波动大：2026-10-31 Day26 实测发布后约 13 分钟即被索引，
+ 323 2026-10-30 Day25 实测官宣约 1 小时后仍未索引——滞后是常态而非例外，官宣发现不能依赖 Radar）；主帖时间线也不含 replies，所以前两条都无新仍不能跳过 reply
- 393   `data[].author.screenName`，不是 `userName`。按[回复样本判读](references/signal-readings.md#回复样本判读)
+ 404   `data[].author.screenName`，不是 `userName`。CLI 间歇失败时顶层是 `{ok:false, error:{...}}`
+ 405   ——解析脚本先判 `ok` 再取 `data`，否则失败被 `2>/dev/null` 吞成静默空输出（2026-10-30 实测）。
+ 406   找本人追加回复用两跳法：先对承重主帖跑 `tweet <id>` 扫 `data[]` 里 `screenName==thsottiaux`
+ 407   的非主帖条目，命中后对**该回复的 id** 再跑一次 `tweet <回复id>` 取完整 parent 上下文——
+ 408   `data[]` 按相关性混排，本人回复与 parent 常不相邻（2026-10-30 实测：靠第二次调用才拿到
+ 409   「$500 档 50x?」的 parent）。按[回复样本判读](references/signal-readings.md#回复样本判读)
- 395   的发现性扫描仍走下面的网页滚动法。`twitter search`（含 `from:` 查询）实测 HTTP 404，搜索路线不可用。
+ 411   的发现性扫描仍走下面的网页滚动法。`twitter search`（含 `from:` 查询）实测 HTTP 404，搜索路线不可用
+ 412   （2026-09-24 首测，2026-10-30 复测仍 404）。
- 455 自然周期后的用量回满读数。没有前置读数时只报告当前值：banked 写「到账未核实」，global 写「发生未核实」。
+ 472 自然周期后的用量回满读数。没有前置读数时只报告当前值：banked 写「到账未核实」，global 写
+ 473 「发生未核实」。该站事件列表不完整，缺条目不可作「该日无事件」的反证（2026-10-31 实测：
+ 474 completed 列表缺 10-22/10-23 两轮台账已确认的 global 事件）。

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 153 For a Codex app-server that emits neither a handshake nor a useful log, read
+ 154 [startup before the local protocol](references/codex-startup-before-handshake.md)
+ 155 before repeating the transport probe or changing authentication.
+ 156 

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub

Before Network or broad shell → After Network or broad shell

717fe8510531 → 7c4d326ddd94

+ 94 - After a local failure, use the [existing authorized downloader handoff](references/internal-sop.md#existing-authorized-downloader-handoff) when an available owner can complete the same file request; retain the local diagnostic and original archive destination.

Compare on GitHub

Before Not checked yet → After Network or broad shell

First observation → 717fe8510531

No earlier version was observed for comparison.

Compare on GitHub