@mkterswingman/5mghost-wonder 0.0.11 → 0.0.14

package/skills/use-5mghost-wonder/references/read-export.md

@@ -0,0 +1,97 @@
+# Export-Backed Read
+
+Use this path for supported, exportable WeCom docs, sheets, and slides.
+
+## URL Types
+
+| URL prefix | Type | First command |
+| --- | --- | --- |
+| `sheet/e3_` | Spreadsheet | `wonder read <url>` |
+| `doc/w3_` | Document | `wonder read <url>` |
+| `doc/e2_` | Document | `wonder read <url>` |
+| `slide/p3_` | Presentation | `wonder read <url>` |
+| `smartpage/a1_` | Smart page | Try no-export browser path |
+| `mind/m4_` | Mind map | Try no-export browser path |
+
+If export fails because the document cannot be exported, is read-only, or the
+export job does not complete, switch to `read-no-export-browser.md`.
+
+## Spreadsheet
+
+First get workbook metadata:
+
+```bash
+wonder read <url>
+```
+
+Then read the relevant tab:
+
+```bash
+wonder read <url> --tab <tab-name>
+```
+
+Use the returned JSON directly. Important rules:
+
+- `row`, `col`, and merge coordinates are 0-based internally. Convert to
+  1-based spreadsheet addresses for the user.
+- Use `text` for date/time cells. Raw `value` may be an Excel serial number.
+- A `mergeSpan` on a cell means that anchor cell covers the full merged range.
+- Image cells point to local extracted image paths. Load only images the user
+  specifically needs.
+
+Render visual layout when color, layout, merged-cell density, screenshots, or
+image relationships matter:
+
+```bash
+soffice --headless \
+  --convert-to 'pdf:calc_pdf_Export:{"SinglePageSheets":{"type":"boolean","value":"true"}}' \
+  --outdir /tmp/ <path-to-downloaded-xlsx>
+```
+
+## Document
+
+Download:
+
+```bash
+wonder read <url>
+```
+
+Read text:
+
+```bash
+pandoc <path> -o /tmp/wonder-doc-output.md && cat /tmp/wonder-doc-output.md
+```
+
+When layout or images matter, render PDF:
+
+```bash
+soffice --headless --convert-to pdf --outdir /tmp/ <path>
+```
+
+To inspect embedded images:
+
+```bash
+mkdir -p /tmp/wonder-doc-unpack
+cp <path> /tmp/wonder-doc-unpack/doc.zip
+unzip -o /tmp/wonder-doc-unpack/doc.zip -d /tmp/wonder-doc-unpack/
+```
+
+Read images from `/tmp/wonder-doc-unpack/word/media/`.
+
+## Presentation
+
+Download:
+
+```bash
+wonder read <url>
+```
+
+Always extract both text and visual layout:
+
+```bash
+pandoc <path> -o /tmp/wonder-slide-output.md && cat /tmp/wonder-slide-output.md
+soffice --headless --convert-to pdf --outdir /tmp/ <path>
+```
+
+Use text extraction for exact wording and PDF rendering for visual structure,
+timelines, screenshots, and image-text relationships.

package/skills/use-5mghost-wonder/references/read-no-export-browser.md

@@ -0,0 +1,81 @@
+# No-Export Browser Read
+
+Use this experimental path when export-backed `wonder read` is unavailable or
+insufficient:
+
+- Read-only document.
+- Export disabled.
+- Export job fails or never completes.
+- Smart page / mind map / unsupported type.
+- User specifically needs browser-visible images, floating images, merged
+  tables, or layout that export misses.
+
+## Goal
+
+Read from the browser-loaded document without relying on WeCom's export API.
+Prefer structured runtime or network data over screenshots.
+
+## Evidence Ladder
+
+Treat results by evidence strength:
+
+| Result | Requirement |
+| --- | --- |
+| `pass` | Text, table cells, merge ranges, image resources or URLs, and image-to-cell/position relationships are captured without export. |
+| `partial` | Some structured data is captured, but images, merges, anchors, or positions are missing. |
+| `fail` | Only screenshots/OCR are available, or the page cannot be loaded. |
+
+Do not describe screenshot/OCR output as lossless.
+
+## Procedure
+
+1. Confirm cookies are valid. If not, follow `cookie-recovery.md`.
+2. Start with the built-in evidence probe:
+
+```bash
+wonder browser probe <url> --save /tmp/wonder-browser-probe
+```
+
+Use `--headed` only when login/debug visibility is needed.
+
+3. If the probe is insufficient, continue with the available browser automation
+   runtime.
+4. Capture non-destructive evidence:
+   - page URL and document type
+   - visible title
+   - loaded script/runtime globals that look like document stores
+   - network responses that contain cell text, merge ranges, image metadata, or
+     media URLs
+   - WebSocket messages if they expose structured document operations
+   - screenshots only as a fallback or visual cross-check
+5. For tables, specifically look for:
+   - cell coordinates
+   - displayed text
+   - merge ranges
+   - row/column sizes if available
+   - fixed cell images
+   - floating images with position, size, and anchor
+6. For image-heavy docs, verify whether each image can be fetched as an original
+   resource or only appears in a raster screenshot.
+7. Report `pass`, `partial`, or `fail` with the missing fields.
+
+## Output Contract
+
+Return a concise result:
+
+```json
+{
+  "mode": "browser-no-export",
+  "status": "pass|partial|fail",
+  "textAvailable": true,
+  "tablesAvailable": true,
+  "mergeRangesAvailable": true,
+  "imagesAvailable": true,
+  "imageAnchorsAvailable": true,
+  "evidence": ["runtime-store", "network-response", "websocket", "screenshot"],
+  "missing": []
+}
+```
+
+If the user asked for an answer, answer only from fields that are backed by
+evidence. State any partial gaps plainly.

package/skills/use-5mghost-wonder/references/route-map.md

@@ -0,0 +1,21 @@
+# Route Map
+
+Classify by the user's job, not only by URL shape.
+
+| Signal | Route |
+| --- | --- |
+| User asks to read, summarize, translate, extract, inspect content | `read-export.md` first |
+| `wonder read` fails due to export disabled, read-only, unsupported export, or stuck export | `read-no-export-browser.md` |
+| User asks to edit, append, format, rewrite in place, or change toolbar styles | `edit-browser-runtime.md` |
+| User asks about images, screenshots, layout, colors, embedded media, merged cells, or table structure | `read-export.md` plus `verification.md`; use `read-no-export-browser.md` if export is unavailable |
+| Cookie/auth failure | `cookie-recovery.md` |
+| Need exact command syntax | `cli-reference.md` |
+
+Mixed task order:
+
+1. Session init if not already done.
+2. Cookie recovery if needed.
+3. Read enough context.
+4. Execute edit or extraction.
+5. Verify with `verification.md`.
+6. Report supported, partial, and not-verified parts separately.

package/skills/use-5mghost-wonder/references/session-init.md

@@ -0,0 +1,19 @@
+# Session Initialization
+
+Run this once per AI session before processing a WeCom document.
+
+```bash
+wonder update
+wonder --version
+wonder wecom status
+```
+
+Compare `wonder --version` with the version in `SKILL.md`. If they differ, the
+loaded skill text and CLI are out of sync. Stop and tell the user to run
+`/update-5mghost-wonder`, then start a fresh AI session.
+
+If `wonder wecom status` reports missing, expired, invalid, 401, or 403, follow
+`cookie-recovery.md`.
+
+Do not repeat these checks for every document in the same session unless a
+Wonder command reports an auth/cookie failure.

package/skills/use-5mghost-wonder/references/verification.md

@@ -0,0 +1,49 @@
+# Verification
+
+Verification depends on the path.
+
+## Export-Backed Reads
+
+- For sheets, trust structured JSON for text, values, merges, and extracted
+  image files.
+- Use PDF rendering when visual layout, colors, screenshots, or image
+  relationships matter.
+- For docs/slides, combine text extraction with PDF rendering when layout
+  matters.
+
+## Browser Writes
+
+Clicking a toolbar button is not success.
+
+When export is available:
+
+1. Write a unique marker or make a targeted change.
+2. Run `wonder read <url> --save <dir>`.
+3. Inspect the exported DOCX/XLSX/PPTX internals or parsed output.
+4. Confirm the marker/change carries the expected semantic property.
+
+Examples:
+
+- DOCX bold uses Word XML run properties such as `<w:b`.
+- DOCX underline uses `<w:u`.
+- Lists use paragraph numbering properties such as `<w:numPr`.
+- Quote-like blocks may show paragraph borders or related paragraph properties.
+
+When export is unavailable:
+
+1. Use browser runtime/network evidence.
+2. Prefer structured editor state over screenshot evidence.
+3. If only screenshot/OCR proves the change, report `partial`, not `success`.
+
+## No-Export Reads
+
+The goal is lossless structured data. Verify each field independently:
+
+- text
+- table cell coordinates
+- merge ranges
+- image original resources or URLs
+- image anchors, positions, and sizes
+- floating vs fixed cell images
+
+If any field is missing, report exactly which capability is missing.