Letter design v2

1. 1

   Availability for controlled testing

   Letter Designer v2 is code-complete for controlled testing. The v2 tools are visible only when LETTER_DESIGN_V2_ENABLED=true is set in an isolated Stage or private environment. If letter_design_list_presets is absent, the v2 rollout is off and letter_design_save plus letter_design_preview continue to publish schemaVersion 1 only. This acceptance does not authorize a production-wide launch.

2. 2

   Always start from a preset

   Call letter_design_list_presets without presetId first for the inexpensive list. Only owner-approved candidates are visible and applicable. Until the current owner curation is complete, the list is intentionally empty. Afterwards, presetId returns the complete native v2 JSON and a real inline preview. The apply flow copies it atomically and creates a Brand Kit when needed.

   letter_design_list_presets
   {
     "presetId": "minimal-rule",
     "resolution": "thumb",
     "pages": 1
   }

3. 3

   Save the native v2 source

   letter_design_save expects name, the complete design, and brandingOwnershipConfirmed=true on creation or a branding change. Pass designId to update an existing working design. Design and Brand Kit changes are saved atomically with an ownership audit trail. Compatibility data from a v1 migration is not accepted as input.

   letter_design_save
   {
     "name": "Firm stationery v2",
     "design": "<copy the complete preset.design and adjust supported v2 fields only>",
     "brandingOwnershipConfirmed": true,
     "reasoning": "Adapted the minimal starting point to the existing stationery."
   }

4. 4

   Preview, correct, and repeat

   letter_design_preview accepts exactly one source, either designId or an unsaved design. The preview uses real partner sender data, an explicitly fictional recipient, and the same composer as sending. The response includes an inline PNG, signed pngUrl and pdfUrl, designIdentity, designRender, geometryManifest with boxes, violations, warnings, and bodyCapacity. Links remain valid for 15 minutes. Page 2 is returned only for continuationHeader with pages=2. Preview and save do not charge the wallet. Repeats use a full-artifact cache and distinct misses are capped. Cache and rate state are currently process-local and suitable only for the controlled test lane.

   letter_design_preview
   {
     "designId": "<designId from letter_design_save>",
     "reference": {
       "vorgangsnummer": "2026-0042"
     },
     "resolution": "thumb",
     "pages": 1
   }

5. 5

   Hand off to the dashboard for review

   After the final preview, open /dashboard/designs/<designId>. The native v2 editor leads with annotated PNG pages and the complete PDF. An admin can then adjust colors, font, logo, text, size, and 0.5/5 mm nudges. Save stays disabled until the exact current design-and-Brand-Kit fingerprint has rendered and loaded successfully.

6. 6

   Use the reviewed working design

   Pass designId and the required reference values to order_send, order_send_batch, or letter_draft. Missing required values and postal-zone conflicts stop before any charge. First persistent use mints an immutable version including Brand Kit and assets and pins design_version_id. Keep v2 in the controlled test environment until SQL, deployment, and human gates are complete.

   order_send
   {
     "clientOrderId": "objection-schmidt-2026-08-02",
     "subject": "Objection to tax assessment",
     "content": "Dear Sir or Madam, ...",
     "recipientCompany": "Finanzamt Muenchen-Land",
     "recipientStreet": "Postfach 12 52",
     "recipientZip": "80292",
     "recipientCity": "Muenchen",
     "recipientCountry": "DE",
     "designId": "<reviewed designId>",
     "reference": {
       "vorgangsnummer": "2026-0042"
     }
   }

See the tool reference →See the error catalog →