dimcode-darwin-x64 0.1.2-beta.1 → 0.1.2

package/bin/skills-assets/xlsx/references/ooxml-cheatsheet.md

@@ -1,231 +0,0 @@
-# OOXML SpreadsheetML Cheat Sheet
-
-Quick reference for XML manipulation of xlsx files.
-
----
-
-## Package Structure
-
-```
-my_file.xlsx  (ZIP archive)
-├── [Content_Types].xml          ← declares MIME types for all files
-├── _rels/
-│   └── .rels                    ← root relationship: points to xl/workbook.xml
-└── xl/
-    ├── workbook.xml             ← sheet list, calc settings
-    ├── styles.xml               ← ALL style definitions
-    ├── sharedStrings.xml        ← ALL text strings (referenced by index)
-    ├── _rels/
-    │   └── workbook.xml.rels    ← maps r:id → worksheet/styles/sharedStrings files
-    ├── worksheets/
-    │   ├── sheet1.xml           ← Sheet 1 data
-    │   ├── sheet2.xml           ← Sheet 2 data
-    │   └── ...
-    ├── charts/                  ← chart XML (if any)
-    ├── pivotTables/             ← pivot table XML (if any)
-    └── theme/
-        └── theme1.xml           ← color/font theme
-```
-
----
-
-## Cell Reference Format
-
-```
-A1  → column A (1), row 1
-B5  → column B (2), row 5
-AA1 → column 27, row 1
-```
-
-Column letter ↔ number conversion:
-```python
-def col_letter(n):  # 1-based → letter
-    r = ""
-    while n > 0:
-        n, rem = divmod(n - 1, 26)
-        r = chr(65 + rem) + r
-    return r
-
-def col_number(s):  # letter → 1-based
-    n = 0
-    for c in s.upper():
-        n = n * 26 + (ord(c) - 64)
-    return n
-```
-
----
-
-## Cell XML Reference
-
-### Data Types
-
-| Type | `t` attr | XML Example | Value |
-|------|---------|-------------|-------|
-| Number | omit | `<c r="B2"><v>1000</v></c>` | 1000 |
-| String (shared) | `s` | `<c r="A1" t="s"><v>0</v></c>` | sharedStrings[0] |
-| String (inline) | `inlineStr` | `<c r="A1" t="inlineStr"><is><t>Hi</t></is></c>` | "Hi" |
-| Boolean | `b` | `<c r="D1" t="b"><v>1</v></c>` | TRUE |
-| Error | `e` | `<c r="E1" t="e"><v>#REF!</v></c>` | #REF! |
-| Formula | omit | `<c r="B4"><f>SUM(B2:B3)</f><v></v></c>` | computed |
-
-### Formula Types
-
-```xml
-<!-- Basic formula (no leading = in XML!) -->
-<c r="B4"><f>SUM(B2:B3)</f><v></v></c>
-
-<!-- Cross-sheet -->
-<c r="C1"><f>Assumptions!B5</f><v></v></c>
-<c r="C1"><f>'Sheet With Spaces'!B5</f><v></v></c>
-
-<!-- Shared formula: D2:D100 all use B*C with relative row offset -->
-<c r="D2"><f t="shared" ref="D2:D100" si="0">B2*C2</f><v></v></c>
-<c r="D3"><f t="shared" si="0"/><v></v></c>
-
-<!-- Array formula -->
-<c r="E1"><f t="array" ref="E1:E5">SORT(A1:A5)</f><v></v></c>
-```
-
----
-
-## styles.xml Reference
-
-### Indirect Reference Chain
-
-```
-Cell s="3"
-  ↓
-cellXfs[3] → fontId="2", fillId="0", borderId="0", numFmtId="165"
-  ↓              ↓             ↓            ↓              ↓
-fonts[2]      fills[0]    borders[0]    numFmts: id=165
-blue color    no fill      no border    "0.0%"
-```
-
-### Adding a New Style (step-by-step)
-
-1. In `<numFmts>`: add `<numFmt numFmtId="168" formatCode="0.00%"/>`, update `count`
-2. In `<fonts>`: add font entry, note its index
-3. In `<cellXfs>`: append `<xf numFmtId="168" fontId="N" .../>`, update `count`
-4. New style index = old `cellXfs count` value (before incrementing)
-5. Apply to cells: `<c r="B5" s="NEW_INDEX">...</c>`
-
-### Color Format
-
-`AARRGGBB` — Alpha (always `00` for opaque) + Red + Green + Blue
-
-```
-000000FF → Blue
-00000000 → Black
-00008000 → Green (dark)
-00FF0000 → Red
-00FFFF00 → Yellow (for fills)
-00FFFFFF → White
-```
-
-### Built-in numFmtIds (no declaration needed)
-
-| ID | Format | Display |
-|----|--------|---------|
-| 0 | General | as-is |
-| 1 | 0 | 2024 (use for years!) |
-| 2 | 0.00 | 1000.00 |
-| 3 | #,##0 | 1,000 |
-| 4 | #,##0.00 | 1,000.00 |
-| 9 | 0% | 15% |
-| 10 | 0.00% | 15.25% |
-| 14 | m/d/yyyy | 3/21/2026 |
-
----
-
-## sharedStrings.xml Reference
-
-```xml
-<sst count="3" uniqueCount="3">
-  <si><t>Revenue</t></si>      <!-- index 0 -->
-  <si><t>Cost</t></si>         <!-- index 1 -->
-  <si><t>Margin</t></si>       <!-- index 2 -->
-</sst>
-```
-
-Text with leading/trailing spaces:
-```xml
-<si><t xml:space="preserve">  indented  </t></si>
-```
-
-Special characters:
-```xml
-<si><t>R&amp;D Expenses</t></si>   <!-- & must be &amp; -->
-```
-
----
-
-## workbook.xml / .rels Sync
-
-Every `<sheet>` in workbook.xml needs a matching `<Relationship>` in workbook.xml.rels:
-
-```xml
-<!-- workbook.xml -->
-<!-- NOTE: rId numbering depends on what rIds are already in workbook.xml.rels.
-     The minimal template reserves rId1=sheet1, rId2=styles, rId3=sharedStrings.
-     When ADDING sheets to the template, start from rId4 to avoid conflicts.
-     The rId3 here is just a generic illustration — use the next available rId. -->
-<sheet name="Summary" sheetId="3" r:id="rId3"/>
-
-<!-- workbook.xml.rels -->
-<Relationship Id="rId3"
-  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
-  Target="worksheets/sheet3.xml"/>
-```
-
-And a matching `<Override>` in `[Content_Types].xml`:
-```xml
-<Override PartName="/xl/worksheets/sheet3.xml"
-  ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
-```
-
----
-
-## Column / Row Dimensions
-
-```xml
-<!-- Before <sheetData> -->
-<cols>
-  <col min="1" max="1" width="28" customWidth="1"/>   <!-- A: 28 chars -->
-  <col min="2" max="6" width="14" customWidth="1"/>   <!-- B-F: 14 chars -->
-</cols>
-
-<!-- Row height on individual rows -->
-<row r="1" ht="20" customHeight="1">
-  ...
-</row>
-```
-
----
-
-## Freeze Panes
-
-Inside `<sheetView>`:
-```xml
-<!-- Freeze row 1 (header row stays visible) -->
-<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>
-
-<!-- Freeze column A -->
-<pane xSplit="1" topLeftCell="B1" activePane="topRight" state="frozen"/>
-
-<!-- Freeze both row 1 and column A -->
-<pane xSplit="1" ySplit="1" topLeftCell="B2" activePane="bottomRight" state="frozen"/>
-```
-
----
-
-## 7 Excel Error Types (All Must Be Absent at Delivery)
-
-| Error | Meaning | Detect in XML |
-|-------|---------|---------------|
-| `#REF!` | Invalid cell reference | `<c t="e"><v>#REF!</v></c>` |
-| `#DIV/0!` | Divide by zero | `<c t="e"><v>#DIV/0!</v></c>` |
-| `#VALUE!` | Wrong data type | `<c t="e"><v>#VALUE!</v></c>` |
-| `#NAME?` | Unknown function/name | `<c t="e"><v>#NAME?</v></c>` |
-| `#NULL!` | Empty intersection | `<c t="e"><v>#NULL!</v></c>` |
-| `#NUM!` | Number out of range | `<c t="e"><v>#NUM!</v></c>` |
-| `#N/A` | Value not found | `<c t="e"><v>#N/A</v></c>` |

package/bin/skills-assets/xlsx/references/read-analyze.md

@@ -1,97 +0,0 @@
-# Data Reading & Analysis Guide
-
-> Reference for the READ path. Use `xlsx_reader.py` for structure discovery and data quality auditing,
-> then pandas for custom analysis. **Never modify the source file.**
-
----
-
-## When to Use This Path
-
-The user asks to read, analyze, view, summarize, extract, or answer questions about an Excel/CSV file's contents,
-without requiring file modification. If modification is needed, hand off to `edit.md`.
-
----
-
-## Workflow
-
-### Step 1 — Structure Discovery
-
-Run `xlsx_reader.py` first. It handles format detection, encoding fallback, structure exploration, and data quality audit:
-
-```bash
-python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx                 # full report
-python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx --sheet Sales   # single sheet
-python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx --quality       # quality audit only
-python3 SKILL_DIR/scripts/xlsx_reader.py input.xlsx --json          # machine-readable
-```
-
-Supported formats: `.xlsx`, `.xlsm`, `.csv`, `.tsv`. The script tries multiple encodings for CSV (utf-8-sig, gbk, utf-8, latin-1).
-
-### Step 2 — Custom Analysis with pandas
-
-Load data and perform the analysis the user requests:
-
-```python
-import pandas as pd
-df = pd.read_excel("input.xlsx", sheet_name=None)  # dict of all sheets
-# For CSV: pd.read_csv("input.csv")
-```
-
-**Header handling** (when the default `header=0` doesn't work):
-
-| Situation | Code |
-|-----------|------|
-| Header on row 3 | `pd.read_excel(path, header=2)` |
-| Multi-level merged header | `pd.read_excel(path, header=[0, 1])` |
-| No header | `pd.read_excel(path, header=None)` |
-
-**Analysis quick reference:**
-
-| Scenario | Pattern |
-|----------|---------|
-| Descriptive stats | `df.describe()` or `df['Col'].agg(['sum', 'mean', 'min', 'max'])` |
-| Group aggregation | `df.groupby('Region')['Revenue'].agg(Total='sum', Avg='mean')` |
-| Top N | `df.groupby('Region')['Revenue'].sum().sort_values(ascending=False).head(5)` |
-| Pivot table | `df.pivot_table(values='Revenue', index='Region', columns='Quarter', aggfunc='sum', margins=True)` |
-| Time series | `df.set_index(pd.to_datetime(df['Date'])).resample('ME')['Revenue'].sum()` |
-| Cross-sheet merge | `pd.merge(sales, customers, on='CustomerID', how='left', validate='m:1')` |
-| Stack sheets | `pd.concat([df.assign(Source=name) for name, df in sheets.items()], ignore_index=True)` |
-| Large files (>50MB) | `pd.read_excel(path, usecols=['Date', 'Revenue'])` or `pd.read_csv(path, chunksize=10000)` |
-
-### Step 3 — Output
-
-If the user specifies an output file path, write results to it (highest priority). Format the report as:
-
-```
-## Analysis Report: {filename}
-### File Overview     — format, sheets, row counts
-### Data Quality      — nulls, duplicates, mixed types (or "no issues")
-### Key Findings      — direct answer to the user's question
-### Additional Notes  — formula NaN, encoding issues, caveats
-```
-
-**Numeric display**: monetary `1,234,567.89`, percentage `12.3%`, multiples `8.5x`, counts as integers.
-
----
-
-## Common Pitfalls
-
-| Pitfall | Cause | Fix |
-|---------|-------|-----|
-| Formula cells read as NaN | `<v>` cache empty in freshly generated files | Inform user; suggest opening in Excel and re-saving; or use `libreoffice_recalc.py` |
-| CSV encoding errors | Chinese Windows exports use GBK | `xlsx_reader.py` auto-tries multiple encodings; manually specify if all fail |
-| Mixed types in column | Column has both numbers and text (e.g., "N/A") | `pd.to_numeric(df['Col'], errors='coerce')` — report unconvertible rows |
-| Year shows as 2,024 | Thousands separator format applied to year | `df['Year'].astype(int).astype(str)` |
-| Multi-level headers | Two-row header merged | `pd.read_excel(path, header=[0, 1])`, then flatten with `' - '.join()` |
-| Row number mismatch | pandas 0-indexed vs Excel 1-indexed | `excel_row = pandas_index + 2` (+1 for 1-index, +1 for header) |
-
-**Critical**: Never open with `data_only=True` then `save()` — this permanently destroys all formulas.
-
----
-
-## Prohibitions
-
-- Never modify the source file (no `save()`, no XML edits)
-- Never report formula NaN as "data is zero" — explain it's a formula cache issue
-- Never report pandas indices as Excel row numbers
-- Never make speculative conclusions unsupported by the data