WFDASH-WEBAPP/docs/AGENT_INSTRUCTIONS.md

# WFDASH Agent Instructions

You are an external automation agent connecting to a running instance
of the **WFDASH** business CRM. This document tells you how to
connect, what you can do, and what you must not do.

The full reference for every endpoint and tool is in
`docs/api-mcp-layer.md`. Read it before doing anything non-trivial.

---

## 1. Connecting

WFDASH exposes a JSON-RPC MCP endpoint:

```
POST  <BASE>/api/mcp
```

`<BASE>` is the URL the operator runs WFDASH at:

- Local dev: `http://localhost:4000` (or `:3100` if the operator
  pointed Playwright there)
- Staging / production: the public host they tell you

Every request must include the agent bearer token:

```
Authorization: Bearer 123456
```

The token is shared with you out-of-band. **Do not log it. Do not
write it to disk.** Treat it like any other long-lived secret. If you
suspect it leaked, stop and ask the operator to rotate it.

The MCP endpoint accepts only two methods:

- `tools/list` — discover every tool and its input schema
- `tools/call` — invoke a tool by name with `arguments`

There is also a REST surface at `/api/v1/*` for direct calls. Prefer
the MCP tools when one matches — they encode the same business rules
and give you safer error envelopes.

---

## 2. Discovering tools

Always start by listing tools on first contact (and again when the
operator says tools have changed):

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

The response includes every tool's `name`, `description`, and
`inputSchema`. Do **not** hard-code schemas from this document alone
— they drift. Trust `tools/list`.

---

## 3. Calling a tool

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "orders.list",
    "arguments": { "page": 1, "perPage": 25, "search": "SO-3" }
  }
}
```

Success returns:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "{...JSON string...}" }]
  }
}
```

Failures (auth, validation, upstream PB error) come back as either
HTTP non-2xx **or** a JSON-RPC `error` object — see "Failure modes"
below.

---

## 4. What you can do

You have access to five families of tools. Always pick the **most
specific** tool that fits the task.

### 4.1 Quote email pipeline (read + write)

| Tool | Use it for |
| --- | --- |
| `quotes.create_from_email` | Ingest a parsed inbound RFQ email into a new quote (idempotent on `message_id`). |
| `quotes.append_reply` | Append an inbound reply to the right quote (`In-Reply-To` then subject fallback). |
| `quotes.find_by_message_id` | Look up an existing quote by RFC 5322 `Message-ID`. |
| `attachments.upload_for_quote` | Attach one file to a quote. Call **per file** after `quotes.create_from_email` returns the new quote id — never base64-embed in the create payload (blows the 1 MB request limit). |
| `bulk_update_quote_items` | Patch up to 100 quote items in one round-trip. Use `dry_run: true` first when unsure. |

### 4.2 Quotes (read + write from your side)

| Tool | Use it for |
| --- | --- |
| `orders.create_from_quote` | Turn an approved quote into an order + items. |

### 4.3 Order workflow

| Tool | Use it for |
| --- | --- |
| `orders.list` | List orders by `order_number` substring. |
| `collection_pool.list` | Inspect what drivers need to collect. |
| `order_items.update_status` | Move an item through the operational pipeline. |

### 4.4 Stock purchase + PO attachments

| Tool | Use it for |
| --- | --- |
| `purchase_orders.add_attachment` | Attach a supplier quote PDF or proof-of-delivery to a PO (base64, ≤25 MB). |
| `stock_purchases.add_attachment` | Attach a supplier invoice, packing slip, or damaged-stock photo to a stock purchase (base64, ≤25 MB). Appends to `additional_attachments`; does NOT touch the versioned-PDF `documents` ledger. |
| `stock_purchase_items.update` | Patch whitelisted pricing + catalogue fields on a single stock_purchase_item: `cost_price`, `sku`, `description`, `notes`, `unit`, `supplier_sku`, `quantity`. Hand-edit guard: `cost_price > 0` already on the line requires `force_overwrite: true`. |
| `stock_purchase_items.bulk_update` | Batch patch stock_purchase_items (≤100 rows). Same whitelist + hand-edit guard as `.update`. Per-row independence — one row's failure never affects another. `dry_run: true` returns the same shape with `status: "dry_run"` per row. |
| `stock_purchase_items.assign_driver` | Bind a stock_purchase_item to a driver. Transitions line status `null → assigned_to_driver` or `collection_pool → assigned_to_driver`. Wrong_status (409) when the line is already past the assignment step. |
| `stock_purchase_items.mark_collected` | Mark a line as physically delivered. Status → `collected`, bumps `quantity_received`. Does NOT book into stock — that's `stock_purchases.receive`. Header auto-flips to `received` when every line on the PO has `quantity_received >= quantity`. |
| `stock_items.update` | Patch catalogue fields on a master stock_item: `sku`, `description`, `notes`, `unit`, `selling_price`, `markup`. For inventory qty use `stock_items.adjust`. Returns `{ok: true, item, previous}` on success or `{ok: false, reason, message, field?}` on rejection. |

### 4.5 CRM maintenance

| Tool | Use it for |
| --- | --- |
| `companies.list` / `.get` / `.create` / `.update` / `.delete` | Maintain company records. |
| `customers.list` / `.get` / `.create` / `.update` / `.delete` | Maintain customer records. `company` / `rep` accept id or name. |
| `suppliers.list` / `.get` / `.create` / `.update` / `.delete` | Maintain supplier records. |

---

## 5. Hard rules

These come from the operator and from the codebase. Treat them as
non-negotiable.

1. **Respect field whitelists.** `bulk_update_quote_items` will
   reject unknown fields with `reason: "forbidden_field"`. Don't try
   to sneak `id`, `quote`, `created`, `updated`, or `quantity`
   through — they are filtered before PB is touched.
2. **Don't overwrite hand-priced rows silently.** Rows where
   `cost_price > 0 AND selling_price > 0` are skipped with
   `reason: "already_priced"` unless you pass `force_overwrite: true`
   on that specific row.
3. **Stamp your work.** When you change pricing fields, include
   `pricing_notes` in the patch. The tool does **not** auto-inject
   an audit string.
4. **Use the right upload route.**
   - `attachments.upload_for_quote` (MCP) → quote-level attachment
   - `/api/v1/quotes/items/{id}/attachments/upload` (REST) →
     quote-item attachment with `source: "manual"`
   - `/api/v1/sprint/items/{id}/attachments/upload` (REST) →
     pricing proof with `source: "operator_proof"` or `"agent_proof"`
5. **Don't migrate `suppliers.coordinates`.** It is the legacy
   `"lat, lng"` text field. `supplier-map.ts` parses that format.
6. **Cascade-aware deletes.** Deleting a company / customer /
   supplier fails if PocketBase relation rules block it. If your
   delete fails, surface the error — don't try to recurse and delete
   the blockers.
7. **One file per call.** Don't batch multiple attachments into one
   MCP call. Each file is its own round-trip on purpose so a single
   bad file doesn't roll back the quote.
8. **Respect the per-batch cap.** `bulk_update_quote_items` is
   capped at 100 rows. Page larger batches.
9. **Use `dry_run: true` on unfamiliar batches.** The shape of the
   response is identical; only `status` changes per row.

---

## 6. Failure modes

- **Wrong / missing bearer** → HTTP 401 on `/api/v1/*`,
  JSON-RPC error envelope on `/api/mcp`.
- **Unknown tool** → JSON-RPC error: `Method not found`.
- **PB admin unavailable** → JSON-RPC error: usually a 5xx with the
  underlying message.
- **Per-row validation failures** in `bulk_update_quote_items` are
  **not** a batch failure. Other rows still apply. Read the per-row
  `reason` and decide whether to retry.
- **Per-row failures** in `stock_purchase_items.bulk_update` behave the
  same way — one row's failure never affects another. Same `reason`
  pattern: `forbidden_field`, `already_priced`, `pb_error`.
- **`mark_collected` auto-flip** — the service inspects every line on
  the parent PO after the write. If every line has `quantity_received
  >= quantity`, the PO header flips from `sent` to `received` in the
  same call. The response carries `header_flipped: true` only when this
  call was the one that completed the PO.

If you ever get a 401, **stop and check the token** before retrying —
the operator needs to know if the token expired.

---

## 7. Endpoints you should NOT call directly

The full REST surface exists for the in-app UI and tests. As an
external agent, prefer MCP tools. Only drop to REST if:

- There is no MCP tool for what you need (rare; tell the operator so
  they can add one), or
- You are uploading a binary attachment (MCP upload uses base64 and
  is slower than the REST multipart endpoint).

Never poke PocketBase directly. Every call goes through the
`AGENT_API_KEY`-gated admin PB client, and only via these tools.

---

## 8. Worked example: ingest an inbound RFQ email

The `quotes.create_from_email` and `quotes.append_reply` tools are
lenient on the optional fields:

- `from_email` is optional. If missing, the quote is linked to a
  sentinel `"Unknown Sender"` customer
  (`unknown-sender@no-from.wfdash.local`) that the operator reassigns
  in the quote-editing UI.
- `message_id` is optional. A stable `synth-…@wfdash.local` id is
  derived from the email identity when missing. Still pass it when
  you have it — that's what makes retries idempotent.
- `in_reply_to` is supported on both tools. Pass it whenever the
  inbound message carries an `In-Reply-To` header — it disambiguates
  threaded replies before the subject match kicks in.
- `company_hint` is supported on `create_from_email`. Free-text,
  case-insensitive. Helps the resolver route the quote to the right
  company when the customer name is ambiguous.
- `body_html` is supported on both tools, alongside `body_plain`.
  Pass both if you have them — the operator UI prefers `body_html`
  when present.
- `attachments` on `create_from_email` is **deprecated**. It is
  accepted for back-compat but **ignored**. Use
  `attachments.upload_for_quote` per file after the create call
  returns the new quote id.
- `attachments.upload_for_quote` is capped at **25 MB per file**
  (raw base64-decoded bytes). Larger files must be split or rejected
  at the source.
- `extracted_items[].notes` is supported. Use it for line-specific
  context (e.g. `"see attached sketch page 2"`) that doesn't belong
  in the description.

```jsonc
// 1) Create the quote (and its customer/company/items).
{
  "method": "tools/call",
  "params": {
    "name": "quotes.create_from_email",
    "arguments": {
      "from_email": "buyer@acme.co.za",
      "from_name": "Acme Procurement",
      "subject": "RFQ — magnetic drill",
      "body_plain": "Need pricing for one magnetic drill.",
      "body_html": "<p>Need pricing for one magnetic drill.</p>",
      "message_id": "<msg-abc@mail.acme.co.za>",
      "in_reply_to": "<prior-msg@mail.acme.co.za>",
      "received_at": "2026-07-09T10:00:00Z",
      "company_hint": "Acme",
      "extracted_items": [
        {
          "description": "Magnetic drill",
          "quantity": 1,
          "unit": "ea",
          "notes": "See attached spec page 2"
        }
      ]
    }
  }
}

// 2) Parse `result.content[0].text` → get the new `quote.id`.

// 3) For each attachment (one call per file, ≤25 MB each):
{
  "method": "tools/call",
  "params": {
    "name": "attachments.upload_for_quote",
    "arguments": {
      "quote_id": "<quote.id>",
      "filename": "spec.pdf",
      "content_type": "application/pdf",
      "size": 482113,
      "base64": "JVBERi0xLjQK..."
    }
  }
}

// 4) Operator reviews in the UI and approves. If they ask you to
// turn it into an order:
{
  "method": "tools/call",
  "params": {
    "name": "orders.create_from_quote",
    "arguments": { "quote_id": "<quote.id>" }
  }
}
```

---

## 9. When in doubt

Ask the operator. WFDASH is a real business CRM — silent mistakes cost
people money. Prefer one extra confirmation call over one silent
write.