# ShortcutXL — AgentController Reference

Two channels to control Excel:

1. **`POST /exec`** — run Python with full COM access. Use for imperative actions (write cells, format, create charts, read data).
2. **Filesystem (`modules/`)** — write `.py` files with `@xl_func` decorators. Hot-reloads in ~200ms. Use for custom Excel formulas and tick loops.

---

## `/exec`

```
POST http://localhost:8080/exec
Content-Type: application/json
{"code": "app.Range('A1').Value = 42"}
```

Returns `{"ok": true, "output": "..."}` or `{"ok": false, "error": "..."}`.

**Import statements are disabled in `/exec`.** The sandbox pre-injects everything you need: `app` (Excel.Application COM object), `Workbook`, `Worksheet`, and helper functions. Standard Python builtins work normally. Do NOT use `import`.

`app` is the Excel.Application COM object — same API as VBA. Use `print()` to read values back.

---

## `modules/`

Discover the path: `GET http://localhost:8080/config` → `{"modules_path": "..."}`.

```python
# modules/example.py
from shortcut_xl import xl_func, schedule_call, xl_app

@xl_func
def my_formula(x, y):
    return x + y          # In Excel: =my_formula(A1, B1)

def tick():
    xl_app().Calculate()
    schedule_call(tick, 1)  # continuous updates

schedule_call(tick, 1)
```

Rules: function name = formula name, args are `float`/`str`/`None`, return `float`/`int`/`str`/`bool`, max 32 functions, all modules reload together on any file change.

---

## Hard rules

| | `/exec` | `modules/` |
|---|---|---|
| **Use for** | One-shot actions, layout, formatting | Custom formulas, live data, tick loops |
| **Imports** | Allowed (safe stdlib only; blacklist blocks `os`, `subprocess`, `socket`, etc.) | `xl_func`, `xl_app`, `xl_batch`, `schedule_call`, `xl_log` |

Never mix the two.

## Debugging

- `/exec` errors → response `error` field
- `@xl_func` errors → `#VALUE!` in cell, details in `%TEMP%\shortcutxl.log`
