# First ten minutes: a verified XLSX agent edit

Install the published `wolfxl` package from public PyPI into a fresh virtual environment. Then create a synthetic workbook, edit it the way an agent would (cell values, a formula, a header style and a new sheet), save, reopen and assert every edit together with stable sheet identity.

The example is `engines/wolfxl/examples/agent_edit_first_ten_minutes.py`. It needs only CPython and network access to PyPI: no repository checkout, compiler, account or credential.

## Install

Copy this single install command. It creates the environment and installs the pinned Community (MIT) release, binary wheels only:

```
python3 -m venv .venv && .venv/bin/python -m pip install --only-binary=:all: wolfxl==2.0.38
```

## Run

With the package installed, run the edit and choose a new output directory:

```
.venv/bin/python agent_edit_first_ten_minutes.py --output-dir agent-edit-output
```

Or let the example perform the clean install itself:

```
python3 agent_edit_first_ten_minutes.py --work-dir first-ten-minutes
```

`--work-dir` creates `first-ten-minutes/.venv`, checks that the environment has no `wolfxl`, runs the install command above with extra flags that isolate pip from user configuration and caches (`-I`, `--isolated`, `--no-cache-dir`) and record a pip install report, then reruns the example inside that environment. It writes `receipt.json` with the installed wheel URL and SHA-256, the Python runtime, the sheet identities before and after the edit, the artifact hashes and each step's elapsed time.

Both modes refuse an existing directory, so a rerun never overwrites earlier workbooks. On success the JSON output has `"status": "passed"`; any failed assertion exits nonzero.

## What the example edits and asserts

| Step | Public API | Asserted after save and reopen |
| --- | --- | --- |
| Create synthetic workbook | `wolfxl.Workbook()`, `Worksheet.append`, `Workbook.create_sheet` | Sheets `Inputs` and `Notes` |
| Change a cell value | `wolfxl.load_workbook`, `ws["B3"] = 450` | `Inputs!B3` is 450; other cells unchanged |
| Add a formula | `ws["B4"] = "=SUM(B2:B3)"` | Formula text saved; `Workbook.calculate()` returns 1650 |
| Style the header | `Font(bold=True)`, `PatternFill(fill_type="solid", ...)` | `A1:B1` bold with a solid `FFDDEBF7` fill; `A2` not bold |
| Add a sheet | `Workbook.create_sheet("Summary")` with `=Inputs!B4` | Sheet order `Inputs`, `Notes`, `Summary` |
| Stable sheet identity | `xl/workbook.xml` and its relationships | `Inputs` and `Notes` keep name, `sheetId`, relationship ID and part; the untouched `Notes` part is byte-identical; `Summary` gets a new `sheetId` |

## Supported and not-qualified scope

| Surface | Status |
| --- | --- |
| `wolfxl==2.0.38` Community wheel from public PyPI (`cp312` `manylinux_2_28_x86_64`), CPython 3.12 on Linux x86_64 | Qualified by two clean-install gate runs |
| The edits and assertions in the table above, on this synthetic workbook | Qualified |
| CPython 3.11, 3.13, 3.14; macOS, Windows, Linux aarch64, musl | Not qualified by this example; wheels are published for them |
| Commercial edition (`wolfxl>=2.1`, authenticated index) and `wolfxl_pro` features | Not qualified by this example |
| Cached formula results in the saved file | Not written; the file stores formula text only, and spreadsheet apps recalculate on open |
| Customer workbooks, charts, pivots, images, macros, encryption | Not qualified by this example |
| Full openpyxl API compatibility | Not claimed; the example uses only the calls listed above |
| Rendering, visual fidelity, Excel desktop validation | Not exercised |
| Speed or memory | Not claimed; recorded elapsed times are observations of two runs |

## Evidence

The machine-readable record is `evidence/ltg-xl-first-ten-minutes-agent-example-20261111.json`. Raw gate logs and per-run receipts are in `engines/wolfxl/results/first-ten-minutes/`.

The focused test `engines/wolfxl/tests/test_agent_edit_first_ten_minutes.py` runs `--work-dir` mode in a temporary directory, so every gate run performs a fresh install from PyPI. It then reads the saved workbook with openpyxl from the test environment, independently of the example's environment, and checks the values, formulas, styles, sheet IDs and the untouched sheet part. A second test checks that an existing work directory is refused without changes.