pn-new-crm/assets/README.md

# `assets/`

Server-side runtime assets bundled by Next.js (via `outputFileTracingIncludes`
in `next.config.ts`). These files are read with `fs.readFile` from
`process.cwd()` at runtime, so they are NOT served as public URLs — use
`public/` for that.

## `eoi-template.pdf`

The source PDF used by the in-app EOI generation pathway
(`src/lib/pdf/fill-eoi-form.ts`). It must be the **same** PDF that the
Documenso EOI template uploads, so both pathways produce equivalent
documents.

The PDF must contain AcroForm fields with these exact names (mirroring the
Documenso template's `formValues` keys — see
`docs/eoi-documenso-field-mapping.md`):

| Field name     | Type     | Filled with                                           |
| -------------- | -------- | ----------------------------------------------------- |
| `Name`         | Text     | `EoiContext.client.fullName`                          |
| `Email`        | Text     | `EoiContext.client.primaryEmail`                      |
| `Address`      | Text     | `street, city, country`                               |
| `Yacht Name`   | Text     | `EoiContext.yacht.name`                               |
| `Length`       | Text     | `EoiContext.yacht.lengthFt`                           |
| `Width`        | Text     | `EoiContext.yacht.widthFt`                            |
| `Draft`        | Text     | `EoiContext.yacht.draftFt`                            |
| `Berth Number` | Text     | `EoiContext.berth.mooringNumber`                      |
| `Lease_10`     | Checkbox | always `false` (legacy default — Purchase, not Lease) |
| `Purchase`     | Checkbox | always `true`                                         |

The fill path **flattens** the AcroForm after writing values, so the
recipient can't edit pre-filled values (yacht dimensions, address, berth
number) after the fact. Documenso pathway flattens server-side; the
in-app pathway brings the artifact to parity.

### Expected sha256

The source PDF's sha256 is pinned to guard against silent template swaps
(an unreviewed asset swap would change legal output without a code diff):

```
ba495fd88d99ebe4b7f61acbe397fb2f1cd116e1e1f1b217de93106915c7c44b
```

`scripts/check-eoi-template-sha.ts` verifies this at boot of the in-app
pathway; the function exposes the expected hash via `EXPECTED_EOI_SHA256`
so tests can re-check after a deliberate template revision.

To intentionally update the template:

1. Drop the new PDF as `eoi-template.pdf`.
2. Run `shasum -a 256 assets/eoi-template.pdf`.
3. Update the hash in this README **and** in
   `src/lib/pdf/fill-eoi-form.ts` (search for `EXPECTED_EOI_SHA256`).

### Override path

In dev/test, set `EOI_TEMPLATE_PDF_PATH=/abs/path/to/your/template.pdf` to
point at a different file (e.g. a fixture).

### How to extract this PDF

The legacy flow uploads this PDF to Documenso template ID 8. To get the
exact bytes:

1. In Documenso, open the EOI template.
2. Download the source PDF.
3. Drop it here as `eoi-template.pdf`.

### Known asset issue: Email field clipped at top

The current `eoi-template.pdf` has the `Email` AcroForm field box positioned
slightly too low — long email addresses render with the top pixel row
clipped. **Fix is asset-side, not code-side**: pdf-lib only fills field
boxes, it can't move them. To resolve:

1. Open `eoi-template.pdf` in any PDF form editor (Acrobat, PDFescape,
   PDF Studio, or Documenso's own template editor).
2. Select the `Email` field box; nudge its `y` origin down by ~3 pt (or
   increase its height by ~3 pt) so the rendered text has visual margin
   from the top edge.
3. Save → re-upload to Documenso (so both pathways stay in sync) →
   bump the sha256 in this README + `EXPECTED_EOI_SHA256` per the steps
   above.

Affects both the in-app pathway (renders via pdf-lib AcroForm fill) and
the Documenso pathway (Documenso's own renderer respects the same field
geometry).