---
name: FixBill
description: Use whenever the user wants to fix a billing address, issue date, invoice number, due date, issuer company, or document title on a PDF receipt or invoice — especially Thai-language receipts. Trigger when the user drops a PDF and mentions "fix address", "wrong address", "fix date", "fix invoice number", "fix due date", "fix issuer", "correct bill", "fixbill", or types /fixbill. Wraps the local fixbill CLI.
---

# fixbill

You are running the FixBill workflow on behalf of a Customer Success teammate. Your job is to gather inputs and invoke the local `fixbill` CLI to produce a fixed PDF.

The CLI does all the real work (PDF masking + Thai-font redraw + Google Drive sync). You are the front-end that gathers inputs, picks the right mode, runs the command, and reports the result clearly.

## Modes

| User wants to fix | Command shape |
|---|---|
| Customer address ("Bill to" block) | `fixbill "<path>" "<new-address>"` |
| Issue date only | `fixbill "<path>" DD/MM/YYYY` |
| Issue date + convert title to ใบแจ้งหนี้ | `fixbill "<path>" DD/MM/YYYY --convert` |
| Issue date + custom title | `fixbill "<path>" DD/MM/YYYY --convert <title>` |
| Invoice number | `fixbill "<path>" --invoice-no "INV-001"` |
| Payment due date | `fixbill "<path>" --due-date DD/MM/YYYY` |
| Issuer company (left side) | `fixbill "<path>" --issuer "Company Name"` |
| Multiple fields at once | `fixbill "<path>" DD/MM/YYYY --invoice-no "INV-001" --due-date 30/05/2026 --issuer "Co."` |

The CLI auto-detects the mode: if the second argument matches `DD/MM/YYYY` or any field flag is present, it's field-fix mode; otherwise it's address fix.

## Inputs you need

**Address mode:** PDF path + the full corrected address string (Thai characters, spaces, commas OK).

**Date mode:** PDF path + the new date in `DD/MM/YYYY` format. The CLI finds and replaces all date occurrences automatically — you don't need the old date.

**Title conversion (optional):** Add `--convert` to also change the document title. Default is `ใบแจ้งหนี้`. Pass a custom title after `--convert` if the user specifies one.

**Invoice number:** `--invoice-no "NEW-VALUE"` — replaces the value after the invoice number label (เลขที่, Invoice number, etc.).

**Due date:** `--due-date DD/MM/YYYY` — replaces the value after the due date label (วันที่ครบกำหนด, Due Date, etc.).

**Issuer company:** `--issuer "Company Name"` — replaces the issuer/seller block on the left side of the invoice. Use `\n` for line breaks if the issuer spans multiple lines.

**Flags are combinable.** You can run multiple fixes in one command.

If any required input is missing, ask once. Don't ask for old values — the CLI finds them automatically.

## Step 1 — Preflight: is the CLI installed?

```bash
command -v fixbill
```

If this prints a path, continue to Step 2.

If it prints nothing or the command errors with `Could not find tsx at .../server/node_modules/.bin/tsx`:

1. Tell the user setup is needed (one sentence).
2. Check if the repo is cloned: `ls -d ~/Desktop/fixbill-cli 2>/dev/null`
   - Found → guide them: `cd ~/Desktop/fixbill-cli && sudo npm run setup`
   - Not found → ask them to clone https://github.com/iampon-p/fixbill-cli, then run `sudo npm run setup`, then `fixbill login`.
3. After they confirm setup is done, re-run `command -v fixbill` before continuing.

## Step 2 — Run the fix

Always quote both path and value arguments:

```bash
# Address fix
fixbill "/path/to/receipt.pdf" "บริษัท ตัวอย่าง จำกัด 123 ถ.สุขุมวิท กทม. 10110"

# Date fix only
fixbill "/path/to/receipt.pdf" 21/05/2026

# Date fix + convert title to ใบแจ้งหนี้
fixbill "/path/to/receipt.pdf" 21/05/2026 --convert

# Date fix + custom title
fixbill "/path/to/receipt.pdf" 21/05/2026 --convert ใบส่งของ

# Fix invoice number
fixbill "/path/to/receipt.pdf" --invoice-no "INV-2026-001"

# Fix payment due date
fixbill "/path/to/receipt.pdf" --due-date 30/05/2026

# Fix issuer company (left side)
fixbill "/path/to/receipt.pdf" --issuer "บริษัท ตัวอย่าง จำกัด"

# Combined: date + invoice number + due date in one pass
fixbill "/path/to/receipt.pdf" 21/05/2026 --invoice-no "INV-001" --due-date 30/05/2026
```

Stream output so the user sees progress. Typically takes 5–20 seconds.

## Step 3 — Verify and report

- **Exit 0:** Confirm `~/Downloads/<original-name>_fixed.pdf` exists with `ls -la`. Tell the user the path and surface any Google Drive link printed by the CLI.
- **Exit non-zero:** Show the last ~20 lines of CLI output. Don't retry with different arguments. Match against the failure table below.

## Common failure modes

| CLI output | Cause | Tell the user |
|---|---|---|
| `command not found: fixbill` | CLI not installed | Run `sudo npm run setup` from the fixbill-cli folder. |
| `Could not find tsx at ...` | Server deps missing | `cd ~/Desktop/fixbill-cli/server && npm install` |
| `invalid_grant` or `GOOGLE_REFRESH_TOKEN` error | Google session expired | Run `fixbill login` and re-authorize |
| `Could not find "Bill to" block` | PDF layout not supported | This PDF format isn't supported — ask the user to try the original format |
| `Invoice number label not found` | PDF uses unrecognized invoice label | PDF format not supported for invoice-no fix |
| `Due date label not found` | PDF has no recognized due date field | Confirm the PDF actually has a due date field |
| `Issuer/seller label not found` | No ผู้ขาย / From label detected | Try address fix mode for the Bill-to block instead |
| Date not replaced / old date still visible | Date format mismatch | Check the date was entered as `DD/MM/YYYY` |
| Clipped Thai characters | Font path issue | Check `THAI_FONT_PATH` in `server/.env` points to `NotoSansThai-Regular.ttf` |

## What NOT to do

- Don't rewrite the PDF yourself with pdf-lib, pypdf, or any other library — the CLI handles Thai font embedding and Drive sync that can't be reproduced ad-hoc.
- Don't modify the original PDF in place. The CLI always saves a new `_fixed.pdf` to `~/Downloads/`.
- Don't infer field values from the PDF — the user must provide them explicitly.
- Don't retry on error with slightly different arguments — diagnose first.

## Example sessions

**Address fix:**
User drops `Receipt-2253.pdf` and says "fix this to 99/1 Sukhumvit, Bangkok 10110"
1. `command -v fixbill` → path found ✓
2. `fixbill "/Users/.../Downloads/Receipt-2253.pdf" "99/1 Sukhumvit, Bangkok 10110"`
3. Confirm `~/Downloads/Receipt-2253_fixed.pdf` exists → report path + Drive link.

**Date fix:**
User drops `Invoice-May.pdf` and says "change the date to 21/05/2026"
1. `command -v fixbill` → path found ✓
2. `fixbill "/Users/.../Downloads/Invoice-May.pdf" 21/05/2026`
3. Confirm `~/Downloads/Invoice-May_fixed.pdf` exists → report path.

**Date + convert:**
User says "fix date to 21/05/2026 and convert the title to invoice"
1. `command -v fixbill` → path found ✓
2. `fixbill "/Users/.../Downloads/Invoice-May.pdf" 21/05/2026 --convert`
3. Confirm file → report path.

**Invoice number fix:**
User says "change invoice number to INV-001"
1. `command -v fixbill` → path found ✓
2. `fixbill "/Users/.../Downloads/Invoice.pdf" --invoice-no "INV-001"`
3. Confirm `~/Downloads/Invoice_fixed.pdf` → report path.

**Combined fix:**
User says "fix date to 21/05/2026, invoice to INV-001, due date to 30/05/2026"
1. `command -v fixbill` → path found ✓
2. `fixbill "/Users/.../Downloads/Invoice.pdf" 21/05/2026 --invoice-no "INV-001" --due-date 30/05/2026`
3. Confirm file → report path.