Customization — org + entity overlays

Last updated Jun 14, 2026

Overlays let an org tweak rendering behavior without authoring a new template revision. The overlay editor (under /settings/templates/{template_id}) surfaces four kinds of changes:

1. Clause toggles — pick a value from the platform clause's standard_position or fallbacks[].
2. Field defaults — pre-fill Cover Page fields with org or entity-specific values.
3. Signer renames — change the displayed name of a signer role ("Authorized Signatory" → "Chief Legal Officer") without changing the underlying capacity enum.
4. Attached side letters — declare auto-attachment for an entire document class ("every SAFE rendered by us auto-attaches our pro- rata side letter").

The four-layer composition

Every render composes overlays in this order:

Platform body  →  Jurisdiction Variant  →  Org overlay  →  Entity overlay

• Cross-mode isolation. mode is part of the lookup predicate; a test-mode customization can never apply to a live render.
• Compat range. Each overlay declares compatible_revisions: { min, max }. Outside the range, the render returns 409 overlay_incompatible_with_revision — the overlay was authored against an older revision whose contract may have changed.
• Method constraint composition is union, not intersection. Overlays may ADD methods to method_forbidden_in_live; they may NEVER REMOVE them. The API rejects an attempted weakening with 422 method_constraint_cannot_be_weakened.

Overlay grammar

{
  "clause_overlays": [
    {
      "clause_id": "vesting_acceleration_on_acquisition",
      "selected_value": "double_trigger_full",
      "justification": "Investor protections in our seed paperwork compensate for the trade-off."
    }
  ],
  "field_default_overlays": [
    { "field_name": "notice_address", "value": "100 Matter Way, Wilmington, DE 19801" }
  ],
  "signer_role_overrides": [
    { "role": "authorized_officer", "display_name": "Chief Legal Officer" }
  ],
  "attachments": [
    { "attachment_id": "pro_rata_side_letter" }
  ]
}

Three-position guard

Every selected_value is validated against the platform clause's permittedSelections (standard + fallbacks). Two failure modes:

• selected_value is in unacceptable_deviations → 422 deviation_not_permitted. Surfaced in the editor with the specific deviation that's been rejected.
• selected_value is unknown to the clause → 422 value_not_in_grammar. The clause has been updated since the overlay was authored; the editor surfaces the upgrade-fence error and offers a one-click rebase against the latest revision.

When to overlay vs fork

Forks author a new TemplateRevision with visibility: org_private, publisher_org_id set to the calling org, and parent_revision_id pointing at the platform revision the fork was based on. Forks are created via multipart upload to POST /templates/{template_id}/revisions — body is multipart/form-data, NEVER a caller-supplied URL (that would be SSRF). The new revision is returned in org_private state, retrievable only by tokens whose orgId matches the publisher.

Signer-portal trust signal

When a fork-rendered document reaches the signer portal, the displayed template name is suffixed [Custom: <publisher_org.name>] and a Trust card explains: "This document is based on <platform_template_name>, customized by <publisher_org.name>." with a link to the diff.

The suffix is presentation-only — the underlying name column is unchanged — but it prevents an org from passing a fork off as the unmodified platform original.

Overlay-size bounds

Hard caps per overlay:

The caps are enforced at three layers — Zod at the API boundary, Postgres CHECK (pg_column_size(...) < 262144) at the storage layer, and the OpenAPI x-matter-explainer so SDK consumers see the bound inline. Above these bounds, the overlay is almost certainly misuse (usually a fork would be the right answer).

Soft-delete + re-creation

OrgTemplateCustomization and EntityTemplateOverride are soft- deletable; the deletedAt tombstone lives on the row so previously- rendered Documents that reference the customization at render time remain auditable. The partial-unique INDEX UNIQUE (orgId, templateId, mode) WHERE deletedAt IS NULL permits re-creating a customization after deletion without violating the contract.

See also

• MCTF format — clause / signer / fields grammar the overlays speak.
• Render and sign — full agent flow.
• Multi-jurisdiction — how JurisdictionVariant layers between platform and org.