v2.17.0

## Description

Documents API page: adds the missing Cancel Document section and fixes a
fabricated request body on get-many that would fail schema validation
for anyone copying the docs.

## Changes Made

- Added a `## Cancel Document` section: `POST /envelope/cancel` with `{
envelopeId, reason? }`, PENDING-only (400 otherwise), not idempotent,
two-stage access (404 if not visible, 401 without owner/MANAGER+), fires
`DOCUMENT_CANCELLED` webhook, emails only SENT/OPENED non-CC
non-rejected recipients.
- Replaced the fabricated `envelopeIds: [...]` get-many body with the
real nested selector: `{ "ids": { "type": "envelopeId" | "documentId" |
"templateId", "ids": [...] } }` (string[] for envelopeId, number[]
otherwise, 1–20 IDs).
- Added the missing `### Response` for get-many (`{ "data": [...] }`)
and documented silent filtering of inaccessible IDs (no 404).
- Added `CANCELLED` to the status table, mermaid state diagram,
transitions prose, and filter values.
- Removed the nonexistent `source: "API"` value (real enum: `DOCUMENT |
TEMPLATE | TEMPLATE_DIRECT_LINK`).
- Fixed fabricated `pagination` wrappers to the real flat shape `{ data,
count, currentPage, perPage, totalPages }`; fixed Field `id` type and
mismatched code fences.
- Migration guide: warned that get-many's body shape changed from
`documentIds: number[]` — the breaking part of that migration.

## Testing Performed

Docs-only change (plus the migration guide). Verified against the
envelope-router types, `cancel-document.ts`, the cancel e2e spec, and
`schema.prisma`.

.agents/skills/create-justification/SKILL.md

@@ -1,56 +0,0 @@
----
-name: create-justification
-description: Create a new justification file in .agents/justifications/ with a unique three-word ID, frontmatter, and formatted title
-license: MIT
-compatibility: opencode
-metadata:
-  audience: agents
-  workflow: decision-making
----
-
-## What I do
-
-I help you create new justification files in the `.agents/justifications/` directory. Each justification file gets:
-
-- A unique three-word identifier (e.g., `swift-emerald-river`)
-- Frontmatter with the current date and formatted title
-- Content you provide
-
-## How to use
-
-Run the script with a slug and content:
-
-```bash
-npx tsx scripts/create-justification.ts "decision-name" "Justification content here"
-```
-
-Or use heredoc for multi-line content:
-
-```bash
-npx tsx scripts/create-justification.ts "decision-name" << HEREDOC
-Multi-line
-justification content
-goes here
-HEREDOC
-```
-
-## File format
-
-Files are created as: `{three-word-id}-{slug}.md`
-
-Example: `swift-emerald-river-decision-name.md`
-
-The file includes frontmatter:
-
-```markdown
----
-date: 2026-01-13
-title: Decision Name
----
-
-Your content here
-```
-
-## When to use me
-
-Use this skill when you need to document the reasoning or justification for a decision, approach, or architectural choice. The unique ID ensures no filename conflicts, and the frontmatter provides metadata for organization.

.agents/skills/create-plan/SKILL.md

@@ -1,56 +0,0 @@
----
-name: create-plan
-description: Create a new plan file in .agents/plans/ with a unique three-word ID, frontmatter, and formatted title
-license: MIT
-compatibility: opencode
-metadata:
-  audience: agents
-  workflow: planning
----
-
-## What I do
-
-I help you create new plan files in the `.agents/plans/` directory. Each plan file gets:
-
-- A unique three-word identifier (e.g., `happy-blue-moon`)
-- Frontmatter with the current date and formatted title
-- Content you provide
-
-## How to use
-
-Run the script with a slug and content:
-
-```bash
-npx tsx scripts/create-plan.ts "feature-name" "Plan content here"
-```
-
-Or use heredoc for multi-line content:
-
-```bash
-npx tsx scripts/create-plan.ts "feature-name" << HEREDOC
-Multi-line
-plan content
-goes here
-HEREDOC
-```
-
-## File format
-
-Files are created as: `{three-word-id}-{slug}.md`
-
-Example: `happy-blue-moon-feature-name.md`
-
-The file includes frontmatter:
-
-```markdown
----
-date: 2026-01-13
-title: Feature Name
----
-
-Your content here
-```
-
-## When to use me
-
-Use this skill when you need to create a new plan document for a feature, task, or project. The unique ID ensures no filename conflicts, and the frontmatter provides metadata for organization.

.agents/skills/create-scratch/SKILL.md

@@ -1,56 +0,0 @@
----
-name: create-scratch
-description: Create a new scratch file in .agents/scratches/ with a unique three-word ID, frontmatter, and formatted title
-license: MIT
-compatibility: opencode
-metadata:
-  audience: agents
-  workflow: exploration
----
-
-## What I do
-
-I help you create new scratch files in the `.agents/scratches/` directory. Each scratch file gets:
-
-- A unique three-word identifier (e.g., `calm-teal-cloud`)
-- Frontmatter with the current date and formatted title
-- Content you provide
-
-## How to use
-
-Run the script with a slug and content:
-
-```bash
-npx tsx scripts/create-scratch.ts "note-name" "Scratch content here"
-```
-
-Or use heredoc for multi-line content:
-
-```bash
-npx tsx scripts/create-scratch.ts "note-name" << HEREDOC
-Multi-line
-scratch content
-goes here
-HEREDOC
-```
-
-## File format
-
-Files are created as: `{three-word-id}-{slug}.md`
-
-Example: `calm-teal-cloud-note-name.md`
-
-The file includes frontmatter:
-
-```markdown
----
-date: 2026-01-13
-title: Note Name
----
-
-Your content here
-```
-
-## When to use me
-
-Use this skill when you need to create a temporary note, exploration document, or scratch pad for ideas. The unique ID ensures no filename conflicts, and the frontmatter provides metadata for organization.

.github/workflows/ci.yml

@@ -15,6 +15,7 @@ jobs:
   build_app:
     name: Build App
     runs-on: ubuntu-latest
+    timeout-minutes: 60
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -32,6 +33,7 @@ jobs:
   build_docker:
     name: Build Docker Image
     runs-on: ubuntu-latest
+    timeout-minutes: 60
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/codeql-analysis.yml

@@ -11,6 +11,7 @@ jobs:
   analyze:
     name: Analyze
     runs-on: ubuntu-latest
+    timeout-minutes: 60
     permissions:
       actions: read
       contents: read

.github/workflows/deploy.yml

@@ -8,6 +8,7 @@ on:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    timeout-minutes: 60
 
     steps:
       - name: Checkout code

.github/workflows/issue-labeler.yml

@@ -7,6 +7,7 @@ on:
 jobs:
   label-when-assigned:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - name: Label issue
         uses: actions/github-script@v6

.github/workflows/issue-opened.yml

@@ -7,6 +7,7 @@ on:
 jobs:
   label_issues:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       issues: write
     steps:

.github/workflows/pr-labeler.yml

@@ -13,6 +13,7 @@ jobs:
       contents: read
       pull-requests: write
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: actions/labeler@v4
         with:

.github/workflows/publish.yml

@@ -14,6 +14,7 @@ jobs:
   build_and_publish_platform_containers:
     name: Build and publish platform containers
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
     strategy:
       fail-fast: false
       matrix:
@@ -78,6 +79,7 @@ jobs:
   create_and_publish_manifest:
     name: Create and publish manifest
     runs-on: ubuntu-latest
+    timeout-minutes: 60
     needs: build_and_publish_platform_containers
     steps:
       - name: Checkout

.github/workflows/semantic-pull-requests.yml

@@ -15,6 +15,7 @@ jobs:
   validate-pr:
     name: Validate PR title
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: amannn/action-semantic-pull-request@v5
         id: lint_pr_title

.github/workflows/stale.yml

@@ -7,6 +7,7 @@ on:
 jobs:
   stale:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       issues: write
       pull-requests: write

.github/workflows/translations-force-pull.yml

@@ -18,6 +18,7 @@ jobs:
   pull_translations:
     name: Force pull translations
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     environment: Translations
     permissions:
       contents: write

.github/workflows/translations-pull.yml

@@ -16,6 +16,7 @@ jobs:
   pull_translations:
     name: Pull translations
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     environment: Translations
     permissions:
       contents: write

.github/workflows/translations-upload.yml

@@ -14,6 +14,7 @@ jobs:
   extract_translations:
     name: Extract and upload translations
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     environment: Translations
     permissions:
       contents: write

.npmrc

@@ -1,3 +1,3 @@
 legacy-peer-deps = true
 prefer-dedupe = true
-# min-release-age = 7
+min-release-age = 7

apps/docs/content/docs/developers/api/documents.mdx

@@ -29,14 +29,25 @@ Each document contains one or more PDF files, a list of recipients, and the fiel
 A document object contains the following properties:
 
 | Property            | Type           | Description                                                                                  |
-| --------------- | -------------- | -------------------------------------------------------------- |
+| ------------------- | -------------- | -------------------------------------------------------------------------------------------- |
 | `id`                | string         | Unique identifier (e.g., `envelope_abc123`)                                                  |
+| `secondaryId`       | string         | Legacy identifier in prefixed form (`document_123` for documents, `template_123` for templates) |
+| `internalVersion`   | number         | Internal envelope schema version                                                             |
 | `type`              | string         | `DOCUMENT` or `TEMPLATE`                                                                     |
-| `status`        | string         | Current status: `DRAFT`, `PENDING`, `COMPLETED`, or `REJECTED` |
+| `status`            | string         | Current status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, or `CANCELLED`                  |
 | `title`             | string         | Document title                                                                               |
-| `source`        | string         | How the document was created: `DOCUMENT`, `TEMPLATE`, `API`    |
+| `source`            | string         | How the document was created: `DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK`                 |
 | `visibility`        | string         | Who can view: `EVERYONE`, `ADMIN`, `MANAGER_AND_ABOVE`                                       |
+| `templateType`      | string         | Template visibility: `PUBLIC`, `PRIVATE`, or `ORGANISATION` (only meaningful for templates)  |
 | `externalId`        | string \| null | Your custom identifier for the document                                                      |
+| `userId`            | number         | ID of the user who owns the document                                                         |
+| `teamId`            | number         | ID of the team the document belongs to                                                       |
+| `folderId`          | string \| null | ID of the folder containing the document                                                     |
+| `templateId`        | number \| null | Legacy ID of the template this document was created from                                     |
+| `authOptions`       | object \| null | Access and action authentication requirements                                                |
+| `formValues`        | object \| null | Pre-filled form values                                                                       |
+| `publicTitle`       | string         | Public title shown on profile and direct-link pages                                          |
+| `publicDescription` | string         | Public description shown on profile and direct-link pages                                    |
 | `createdAt`         | string         | ISO 8601 timestamp                                                                           |
 | `updatedAt`         | string         | ISO 8601 timestamp                                                                           |
 | `completedAt`       | string \| null | Timestamp when all recipients completed signing                                              |
@@ -44,19 +55,35 @@ A document object contains the following properties:
 | `recipients`        | array          | List of recipients and their signing status                                                  |
 | `fields`            | array          | Signature and form fields on the document                                                    |
 | `envelopeItems`     | array          | PDF files attached to the document                                                           |
+| `directLink`        | object \| null | Direct-link signing configuration (`id`, `token`, `enabled`, `directTemplateRecipientId`)    |
+| `team`              | object         | Owning team (`id`, `url`)                                                                    |
+| `user`              | object         | Document owner (`id`, `name`, `email`)                                                       |
 | `documentMeta`      | object         | Email settings, redirect URL, signing options                                                |
 
+Documents created through the API have `source: "DOCUMENT"` — there is no separate `API` source value. To tag documents created by your integration, set `externalId` when creating them.
+
 ### Example Document Object
 
 ```json
 {
   "id": "envelope_abc123xyz",
+  "secondaryId": "document_123",
+  "internalVersion": 2,
   "type": "DOCUMENT",
   "status": "PENDING",
-  "source": "API",
+  "source": "DOCUMENT",
   "visibility": "EVERYONE",
+  "templateType": "PRIVATE",
   "title": "Service Agreement",
   "externalId": "contract-2025-001",
+  "userId": 1,
+  "teamId": 1,
+  "folderId": null,
+  "templateId": null,
+  "authOptions": null,
+  "formValues": null,
+  "publicTitle": "",
+  "publicDescription": "",
   "createdAt": "2025-01-15T10:30:00.000Z",
   "updatedAt": "2025-01-15T10:35:00.000Z",
   "completedAt": null,
@@ -73,23 +100,41 @@ A document object contains the following properties:
   ],
   "fields": [
     {
-      "id": "field_123",
+      "id": 123,
+      "secondaryId": "field_abc123",
       "type": "SIGNATURE",
+      "recipientId": 1,
+      "envelopeId": "envelope_abc123xyz",
+      "envelopeItemId": "envelope_item_xyz",
       "page": 1,
-      "positionX": 10,
-      "positionY": 80,
-      "width": 30,
-      "height": 5,
-      "recipientId": 1
+      "positionX": "10",
+      "positionY": "80",
+      "width": "30",
+      "height": "5",
+      "customText": "",
+      "inserted": false,
+      "fieldMeta": null
     }
   ],
   "envelopeItems": [
     {
       "id": "envelope_item_xyz",
+      "envelopeId": "envelope_abc123xyz",
+      "documentDataId": "doc_data_abc123",
       "title": "contract.pdf",
       "order": 1
     }
   ],
+  "directLink": null,
+  "team": {
+    "id": 1,
+    "url": "your-team"
+  },
+  "user": {
+    "id": 1,
+    "name": "Jane Smith",
+    "email": "jane@example.com"
+  },
   "documentMeta": {
     "subject": "Please sign this document",
     "message": "Hi, please review and sign this agreement.",
@@ -99,6 +144,8 @@ A document object contains the following properties:
 }
 ```
 
+Field position and size values are stored as decimals and serialized as strings in API responses.
+
 ## List Documents
 
 Retrieve a paginated list of documents.
@@ -114,7 +161,7 @@ GET /envelope
 | `page`             | integer | Page number (default: 1)                                      |
 | `perPage`          | integer | Results per page (default: 10, max: 100)                      |
 | `type`             | string  | Filter by `DOCUMENT` or `TEMPLATE`                            |
-| `status`           | string  | Filter by status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` |
+| `status`           | string  | Filter by status: `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, `CANCELLED` |
 | `source`           | string  | Filter by creation source                                     |
 | `folderId`         | string  | Filter by folder ID                                           |
 | `orderByColumn`    | string  | Sort field (only `createdAt` supported)                       |
@@ -154,8 +201,8 @@ const response = await fetch(`${BASE_URL}/envelope`, {
   },
 });
 
-const { data, pagination } = await response.json();
-console.log(`Found ${pagination.totalItems} documents`);
+const { data, count } = await response.json();
+console.log(`Found ${count} documents`);
 
 // Filter by status
 const pendingResponse = await fetch(
@@ -197,12 +244,10 @@ const pendingDocs = await pendingResponse.json();
       ]
     }
   ],
-  "pagination": {
-    "page": 1,
+  "count": 42,
+  "currentPage": 1,
   "perPage": 10,
-    "totalPages": 5,
-    "totalItems": 42
-  }
+  "totalPages": 5
 }
 ```
 
@@ -628,6 +673,72 @@ The response includes signing URLs for each recipient:
 
 ---
 
+## Cancel Document
+
+Cancel a pending document. This changes its status from `PENDING` to `CANCELLED`.
+
+```
+POST /envelope/cancel
+```
+
+### Request Body
+
+| Field        | Type   | Required | Description                         |
+| ------------ | ------ | -------- | ----------------------------------- |
+| `envelopeId` | string | Yes      | Document ID                         |
+| `reason`     | string | No       | Reason for cancelling the document |
+
+### Code Examples
+
+<Tabs items={['curl', 'TypeScript']}>
+<Tab value="curl">
+```bash
+curl -X POST "https://app.documenso.com/api/v2/envelope/cancel" \
+  -H "Authorization: api_xxxxxxxxxxxxxxxx" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "envelopeId": "envelope_abc123",
+    "reason": "The agreement is no longer needed."
+  }'
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+const response = await fetch('https://app.documenso.com/api/v2/envelope/cancel', {
+  method: 'POST',
+  headers: {
+    Authorization: 'api_xxxxxxxxxxxxxxxx',
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    envelopeId: 'envelope_abc123',
+    reason: 'The agreement is no longer needed.',
+  }),
+});
+
+const { success } = await response.json();
+```
+</Tab>
+</Tabs>
+
+### Response
+
+```json
+{
+  "success": true
+}
+```
+
+### Behavior
+
+- Only documents in `PENDING` status can be cancelled. Other statuses return `400`.
+- Cancellation is not idempotent. Cancelling the same document again returns `400`.
+- The document owner and team members with `MANAGER` or higher permissions can cancel it. Requests for documents you cannot view return `404`; requests for visible documents without sufficient permissions return `401`.
+- A successful cancellation fires the `DOCUMENT_CANCELLED` webhook.
+- Cancellation emails are sent only to eligible non-CC, non-rejected recipients who were sent or opened the document.
+
+---
+
 ## Delete Document
 
 Delete a document. Completed documents cannot be deleted.
@@ -670,7 +781,7 @@ const response = await fetch('https://app.documenso.com/api/v2/envelope/delete',
 
 const { success } = await response.json();
 
-````
+```
 </Tab>
 </Tabs>
 
@@ -680,7 +791,7 @@ const { success } = await response.json();
 {
   "success": true
 }
-````
+```
 
 ---
 
@@ -695,8 +806,10 @@ POST /envelope/get-many
 ### Request Body
 
 | Field      | Type   | Required | Description                                                                  |
-| ------------- | ----- | -------- | --------------------- |
-| `envelopeIds` | array | Yes      | Array of document IDs |
+| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
+| `ids`      | object | Yes      | ID selector containing `type` and `ids`                                      |
+| `ids.type` | string | Yes      | `envelopeId`, `documentId`, or `templateId`                                  |
+| `ids.ids`  | array  | Yes      | 1-20 IDs: strings for `envelopeId`; numbers for `documentId` or `templateId` |
 
 ### Code Examples
 
@@ -707,12 +820,17 @@ curl -X POST "https://app.documenso.com/api/v2/envelope/get-many" \
   -H "Authorization: api_xxxxxxxxxxxxxxxx" \
   -H "Content-Type: application/json" \
   -d '{
-    "envelopeIds": ["envelope_abc123", "envelope_def456", "envelope_ghi789"]
+    "ids": {
+      "type": "envelopeId",
+      "ids": ["envelope_abc123", "envelope_def456", "envelope_ghi789"]
+    }
   }'
 ```
 </Tab>
 <Tab value="TypeScript">
 ```typescript
+const requestedIds = ['envelope_abc123', 'envelope_def456', 'envelope_ghi789'];
+
 const response = await fetch('https://app.documenso.com/api/v2/envelope/get-many', {
   method: 'POST',
   headers: {
@@ -720,16 +838,36 @@ const response = await fetch('https://app.documenso.com/api/v2/envelope/get-many
     'Content-Type': 'application/json',
   },
   body: JSON.stringify({
-    envelopeIds: ['envelope_abc123', 'envelope_def456', 'envelope_ghi789'],
+    ids: {
+      type: 'envelopeId',
+      ids: requestedIds,
+    },
   }),
 });
 
-const documents = await response.json();
+const { data } = await response.json();
 
-````
+```
 </Tab>
 </Tabs>
 
+### Response
+
+```json
+{
+  "data": [
+    {
+      "id": "envelope_abc123",
+      "type": "DOCUMENT",
+      "status": "PENDING",
+      "title": "Service Agreement"
+    }
+  ]
+}
+```
+
+The endpoint silently omits envelopes you cannot access instead of returning `404`. Compare `data.length` with `requestedIds.length` to detect omissions.
+
 ---
 
 ## Document Statuses
@@ -740,6 +878,7 @@ const documents = await response.json();
 | `PENDING` | Document has been sent. Waiting for recipients to sign. |
 | `COMPLETED` | All recipients have signed. Document is sealed. |
 | `REJECTED` | A recipient rejected the document. |
+| `CANCELLED` | The document was cancelled by its owner or a team member with `MANAGER` or higher permissions. |
 
 ### Status Transitions
 
@@ -747,11 +886,13 @@ const documents = await response.json();
 flowchart LR
   DRAFT --> PENDING --> COMPLETED
   PENDING --> REJECTED
+  PENDING --> CANCELLED
 ```
 
 - **DRAFT to PENDING**: Call the distribute endpoint
 - **PENDING to COMPLETED**: All recipients complete their signing
 - **PENDING to REJECTED**: A recipient rejects the document
+- **PENDING to CANCELLED**: The document owner or a team member with `MANAGER` or higher permissions cancels the document
 
 <Callout type="warn">
   You cannot modify recipients or fields after a document moves to `PENDING` status.
@@ -773,8 +914,8 @@ flowchart LR
 | Parameter  | Values                                      | Description               |
 | ---------- | ------------------------------------------- | ------------------------- |
 | `type`     | `DOCUMENT`, `TEMPLATE`                      | Filter by envelope type   |
-| `status`   | `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED` | Filter by status          |
-| `source`   | `DOCUMENT`, `TEMPLATE`, `API`               | Filter by creation source |
+| `status`   | `DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, `CANCELLED` | Filter by status          |
+| `source`   | `DOCUMENT`, `TEMPLATE`, `TEMPLATE_DIRECT_LINK`          | Filter by creation source |
 | `folderId` | string                                      | Filter by folder          |
 
 ### Sorting
@@ -800,10 +941,10 @@ async function getAllPendingDocuments() {
       },
     );
 
-    const { data, pagination } = await response.json();
+    const { data, currentPage, totalPages } = await response.json();
     documents.push(...data);
 
-    hasMore = page < pagination.totalPages;
+    hasMore = currentPage < totalPages;
     page++;
   }
 

apps/docs/content/docs/developers/api/migrate-to-envelopes.mdx

@@ -119,7 +119,7 @@ Full reference in the [V2 OpenAPI reference](https://openapi.documenso.com).
 | ------------------------------------------------- | ----------------------------------------------------- |
 | `GET /api/v2/document`                            | `GET /api/v2/envelope`                                |
 | `GET /api/v2/document/{documentId}`               | `GET /api/v2/envelope/{envelopeId}`                   |
-| `POST /api/v2/document/get-many`                  | `POST /api/v2/envelope/get-many`                      |
+| `POST /api/v2/document/get-many`                  | `POST /api/v2/envelope/get-many` (body changes from `documentIds: number[]` to `ids: { type: "documentId"; ids: number[] }`) |
 | `POST /api/v2/document/create`                    | `POST /api/v2/envelope/create`                        |
 | `POST /api/v2/document/create/beta`               | `POST /api/v2/envelope/create`                        |
 | `POST /api/v2/document/update`                    | `POST /api/v2/envelope/update`                        |
@@ -140,7 +140,7 @@ Full reference in the [V2 OpenAPI reference](https://openapi.documenso.com).
 | ------------------------------------- | ------------------------------------------------ |
 | `GET /api/v2/template`                | `GET /api/v2/envelope` (with `type=TEMPLATE`)    |
 | `GET /api/v2/template/{templateId}`   | `GET /api/v2/envelope/{envelopeId}`              |
-| `POST /api/v2/template/get-many`      | `POST /api/v2/envelope/get-many`                 |
+| `POST /api/v2/template/get-many`      | `POST /api/v2/envelope/get-many` (body changes from `templateIds: number[]` to `ids: { type: "templateId"; ids: number[] }`) |
 | `POST /api/v2/template/create`        | `POST /api/v2/envelope/create` (`type=TEMPLATE`) |
 | `POST /api/v2/template/create/beta`   | `POST /api/v2/envelope/create` (`type=TEMPLATE`) |
 | `POST /api/v2/template/update`        | `POST /api/v2/envelope/update`                   |

apps/docs/content/docs/developers/api/rate-limits.mdx

@@ -11,6 +11,12 @@ Documenso enforces rate limits on all API endpoints to ensure service stability.
 
 ## HTTP Rate Limits
 
+The rate limit applies to:
+
+- `/api/v1/*`
+- `/api/v2/*`
+- `/api/v2-beta/*`
+
 **Limit:** 1000 requests per minute per IP address  
 **Response:** 429 Too Many Requests
 
@@ -19,7 +25,7 @@ Documenso enforces rate limits on all API endpoints to ensure service stability.
   this value, in which case you can be rate-limited before reaching the global limit.
 </Callout>
 
-### Rate Limit Response
+### Global per-IP 429 Response
 
 ```json
 {
@@ -27,10 +33,22 @@ Documenso enforces rate limits on all API endpoints to ensure service stability.
 }
 ```
 
-<Callout type="warn">
-  No rate limit headers are currently provided. When you receive a 429 response, wait at least 60
-  seconds before retrying.
-</Callout>
+### Rate Limit Headers
+
+Responses from `/api/v1/*`, `/api/v2/*`, and `/api/v2-beta/*` include these headers. The only
+exception is CORS preflight (`OPTIONS`) requests, which are answered before the rate limiter runs
+and carry no rate limit headers:
+
+| Header                  | Description                                                            |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `X-RateLimit-Limit`     | Maximum requests allowed in the current global window                  |
+| `X-RateLimit-Remaining` | Requests remaining in the current global window                        |
+| `X-RateLimit-Reset`     | End of the current global window, as a Unix epoch timestamp in seconds |
+
+A 429 response from a windowed limiter also includes `Retry-After`, in seconds, with a minimum
+value of `1`. The global API limit uses fixed, epoch-aligned one-minute buckets, so the actual wait
+until the next window is between 1 and 60 seconds. Honor `Retry-After` exactly instead of sleeping
+for a fixed 60 seconds. See the [Retry-After handling example](/docs/developers/examples/common-workflows#error-handling-patterns).
 
 ## Resource Limits
 
@@ -44,25 +62,56 @@ Beyond HTTP rate limits, your account has usage limits based on your subscriptio
 | Total Recipients | 10   | Unlimited | Unlimited   | Unlimited  |
 | Direct Templates | 3    | Unlimited | Unlimited   | Unlimited  |
 
-### Error Response
+### Organisation Limit 429 Responses
 
-When you exceed a resource limit:
+Organisation windowed limits and organisation monthly quotas produce 429 responses whose body
+shape depends on the API version, and neither matches the global per-IP limiter's
+`{ "error": "..." }` body.
+
+On `/api/v1/*`, the body contains only a message:
 
 ```json
 {
-  "error": "You have reached your document limit for this month. Please upgrade your plan.",
-  "code": "LIMIT_EXCEEDED",
-  "statusCode": 400
+  "message": "Too many requests, please try again later. Contact support if you require higher limits."
 }
 ```
 
+On `/api/v2/*` and `/api/v2-beta/*`, the body is a structured error object:
+
+```json
+{
+  "message": "Too many requests, please try again later. Contact support if you require higher limits.",
+  "code": "TOO_MANY_REQUESTS",
+  "data": {
+    "code": "TOO_MANY_REQUESTS",
+    "httpStatus": 429,
+    "appError": {
+      "code": "TOO_MANY_REQUESTS",
+      "message": "Too many requests, please try again later. Contact support if you require higher limits."
+    }
+  }
+}
+```
+
+Organisation windowed limit responses include the `X-RateLimit-*` headers and `Retry-After` for
+their own window. Monthly quota responses carry no quota-specific rate limit headers or
+`Retry-After` because the quota is not a time window; rely on the status code and message instead.
+
 ## Error Codes
 
 | Code                | Status | Description                                                        |
-| ------------------- | ------ | ----------------------------- |
-| `TOO_MANY_REQUESTS` | 429    | HTTP rate limit exceeded      |
+| ------------------- | ------ | ------------------------------------------------------------------ |
+| `TOO_MANY_REQUESTS` | 429    | Global per-IP, organisation windowed, or monthly quota exceeded    |
 | `LIMIT_EXCEEDED`    | 400    | Resource usage limit exceeded                                      |
 
+There are three sources of `TOO_MANY_REQUESTS` responses:
+
+1. The global per-IP limit, returning the `{ "error": "..." }` body shown above.
+2. Organisation windowed rate limits for the `api`, `document`, and `email` counters.
+3. Organisation monthly quotas for the same three counters. Every authenticated API request
+   consumes the `api` counter, so any endpoint can return this 429 once the monthly API quota is
+   exhausted — not just envelope-related ones.
+
 ---
 
 ## See Also

apps/docs/content/docs/developers/examples/common-workflows.mdx

@@ -1000,9 +1000,12 @@ async function fetchWithRetry(
       // Retry on rate limit
       if (response.status === 429) {
         const retryAfter = response.headers.get('Retry-After');
-        const delay = retryAfter ? parseInt(retryAfter) * 1000 : baseDelayMs * Math.pow(2, attempt);
+        // Honor Retry-After exactly; the cap only applies to the exponential fallback.
+        const delay = retryAfter
+          ? parseInt(retryAfter) * 1000
+          : Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
         console.log(`Rate limited, waiting ${delay}ms...`);
-        await new Promise((resolve) => setTimeout(resolve, Math.min(delay, maxDelayMs)));
+        await new Promise((resolve) => setTimeout(resolve, delay));
         continue;
       }
 

apps/docs/content/docs/self-hosting/deployment/docker-compose.mdx

@@ -81,7 +81,7 @@ services:
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?err}
       - POSTGRES_DB=${POSTGRES_DB:?err}
     healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER}']
+      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}']
       interval: 10s
       timeout: 5s
       retries: 5

apps/docs/package.json

@@ -10,13 +10,12 @@
     "postinstall": "fumadocs-mdx"
   },
   "dependencies": {
-    "@radix-ui/react-tabs": "^1.1.13",
-    "fumadocs-core": "16.5.0",
-    "fumadocs-mdx": "14.2.6",
-    "fumadocs-ui": "16.5.0",
+    "fumadocs-core": "16.14.3",
+    "fumadocs-mdx": "15.2.3",
+    "fumadocs-ui": "16.14.3",
     "lucide-react": "^0.563.0",
     "mermaid": "^11.12.2",
-    "next": "16.2.6",
+    "next": "16.3.0",
     "next-plausible": "^3.12.5",
     "next-themes": "^0.4.6",
     "react": "^19.2.4",

apps/openpage-api/package.json

@@ -12,11 +12,11 @@
   "dependencies": {
     "@documenso/prisma": "*",
     "luxon": "^3.7.2",
-    "next": "16.2.6"
+    "next": "16.3.0"
   },
   "devDependencies": {
     "@types/node": "^20",
-    "@types/react": "18.3.27",
+    "@types/react": "^19.2.17",
     "typescript": "5.6.2"
   }
 }

apps/remix/app/components/embed/embed-document-signing-page-v1.tsx

@@ -1,6 +1,7 @@
 import { useThrottleFn } from '@documenso/lib/client-only/hooks/use-throttle-fn';
 import { APP_I18N_OPTIONS } from '@documenso/lib/constants/i18n';
 import { PDF_VIEWER_PAGE_SELECTOR } from '@documenso/lib/constants/pdf-viewer';
+import { AppError } from '@documenso/lib/errors/app-error';
 import { ZSignDocumentEmbedDataSchema } from '@documenso/lib/types/embed-document-sign-schema';
 import { isFieldUnsignedAndRequired } from '@documenso/lib/utils/advanced-fields-helpers';
 import { getDocumentDataUrlForPdfViewer } from '@documenso/lib/utils/envelope-download';
@@ -32,6 +33,7 @@ import { useEffect, useId, useLayoutEffect, useMemo, useState } from 'react';
 import { BrandingLogo } from '~/components/general/branding-logo';
 import PDFViewerLazy from '~/components/general/pdf-viewer/pdf-viewer-lazy';
 import { injectCss } from '~/utils/css-vars';
+import { getSigningCompletionErrorMessage } from '~/utils/toast-error-messages';
 
 import { DocumentSigningAttachmentsPopover } from '../general/document-signing/document-signing-attachments-popover';
 import { useRequiredDocumentSigningContext } from '../general/document-signing/document-signing-provider';
@@ -162,9 +164,12 @@ export const EmbedSignDocumentV1ClientPage = ({
         );
       }
 
+      const error = AppError.parseError(err);
+      const toastMessage = getSigningCompletionErrorMessage(error.code);
+
       toast({
-        title: _(msg`Something went wrong`),
-        description: _(msg`We were unable to submit this document at this time. Please try again later.`),
+        title: _(toastMessage.title),
+        description: _(toastMessage.description),
         variant: 'destructive',
       });
     }

apps/remix/app/components/embed/multisign/multi-sign-document-signing-view.tsx

@@ -26,6 +26,7 @@ import { useState } from 'react';
 import { match, P } from 'ts-pattern';
 
 import PDFViewerLazy from '~/components/general/pdf-viewer/pdf-viewer-lazy';
+import { getSigningCompletionErrorMessage } from '~/utils/toast-error-messages';
 
 import { useRequiredDocumentSigningContext } from '../../general/document-signing/document-signing-provider';
 import { DocumentSigningRejectDialog } from '../../general/document-signing/document-signing-reject-dialog';
@@ -141,9 +142,12 @@ export const MultiSignDocumentSigningView = ({
     } catch (err) {
       onDocumentError?.();
 
+      const error = AppError.parseError(err);
+      const toastMessage = getSigningCompletionErrorMessage(error.code);
+
       toast({
-        title: _(msg`Error`),
-        description: _(msg`Failed to complete the document. Please try again.`),
+        title: _(toastMessage.title),
+        description: _(toastMessage.description),
         variant: 'destructive',
       });
     } finally {

apps/remix/app/components/general/app-command-menu.tsx

@@ -19,7 +19,7 @@ import { msg } from '@lingui/core/macro';
 import { useLingui } from '@lingui/react';
 import { Trans } from '@lingui/react/macro';
 import { keepPreviousData } from '@tanstack/react-query';
-import { commandScore } from 'cmdk/dist/command-score';
+import { defaultFilter as commandScore } from 'cmdk';
 import {
   ArrowLeftIcon,
   CheckIcon,

apps/remix/app/components/general/document-signing/document-signing-complete-dialog.tsx

@@ -14,6 +14,7 @@ import {
 } from '@documenso/ui/primitives/dialog';
 import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@documenso/ui/primitives/form/form';
 import { Input } from '@documenso/ui/primitives/input';
+import { useToast } from '@documenso/ui/primitives/use-toast';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { Trans, useLingui } from '@lingui/react/macro';
 import type { Field, Recipient } from '@prisma/client';
@@ -27,6 +28,8 @@ import { useEmbedSigningContext } from '~/components/embed/embed-signing-context
 import { AccessAuth2FAForm } from '~/components/general/document-signing/access-auth-2fa-form';
 import { DocumentSigningDisclosure } from '~/components/general/document-signing/document-signing-disclosure';
 
+import { getSigningCompletionErrorMessage } from '~/utils/toast-error-messages';
+
 import { useRequiredDocumentSigningAuthContext } from './document-signing-auth-provider';
 
 export type DocumentSigningCompleteDialogProps = {
@@ -85,7 +88,8 @@ export const DocumentSigningCompleteDialog = ({
   position,
   disableNameInput = false,
 }: DocumentSigningCompleteDialogProps) => {
-  const { t } = useLingui();
+  const { t, i18n } = useLingui();
+  const { toast } = useToast();
 
   const [showDialog, setShowDialog] = useState(false);
 
@@ -174,6 +178,18 @@ export const DocumentSigningCompleteDialog = ({
 
         return;
       }
+
+      // This dialog owns the completion error toast for every signing surface
+      // so the user gets a specific, actionable message. Callers should run
+      // their own side effects (e.g. embeds posting document-error) and
+      // rethrow rather than toasting themselves.
+      const toastMessage = getSigningCompletionErrorMessage(err.code);
+
+      toast({
+        title: i18n._(toastMessage.title),
+        description: i18n._(toastMessage.description),
+        variant: 'destructive',
+      });
     }
   };
 

apps/remix/app/components/general/document-signing/document-signing-form.tsx

@@ -1,3 +1,4 @@
+import { AppError } from '@documenso/lib/errors/app-error';
 import type { DocumentAndSender } from '@documenso/lib/server-only/document/get-document-by-token';
 import type { TRecipientAccessAuth } from '@documenso/lib/types/document-auth';
 import { isFieldUnsignedAndRequired } from '@documenso/lib/utils/advanced-fields-helpers';
@@ -19,6 +20,8 @@ import { useId, useMemo, useState } from 'react';
 import { Controller, useForm } from 'react-hook-form';
 import { useNavigate } from 'react-router';
 
+import { getSigningCompletionErrorMessage } from '~/utils/toast-error-messages';
+
 import { AssistantConfirmationDialog, type NextSigner } from '../../dialogs/assistant-confirmation-dialog';
 import { DocumentSigningCompleteDialog } from './document-signing-complete-dialog';
 import { useRequiredDocumentSigningContext } from './document-signing-provider';
@@ -100,9 +103,12 @@ export const DocumentSigningForm = ({
     try {
       await completeDocument({ nextSigner });
     } catch (err) {
+      const error = AppError.parseError(err);
+      const toastMessage = getSigningCompletionErrorMessage(error.code);
+
       toast({
-        title: _(msg`Error`),
-        description: _(msg`An error occurred while completing the document. Please try again.`),
+        title: _(toastMessage.title),
+        description: _(toastMessage.description),
         variant: 'destructive',
       });
 

apps/remix/app/components/general/document-signing/document-signing-radio-field.tsx

@@ -146,14 +146,17 @@ export const DocumentSigningRadioField = ({ field, onSignField, onUnsignField }:
       {isLoading && <DocumentSigningFieldsLoader />}
 
       {!field.inserted && (
-        <RadioGroup onValueChange={(value) => handleSelectItem(value)} className="z-10 my-0.5 gap-y-1">
+        <RadioGroup
+          value={selectedOption}
+          onValueChange={(value) => handleSelectItem(value)}
+          className="z-10 my-0.5 gap-y-1"
+        >
           {values?.map((item, index) => (
             <div key={index} className="flex items-center">
               <RadioGroupItem
                 className="h-3 w-3 shrink-0"
                 value={item.value}
                 id={`option-${field.id}-${item.id}`}
-                checked={item.checked}
                 disabled={isReadOnly}
               />
               {!item.value.includes('empty-value-') && item.value && (
@@ -167,14 +170,13 @@ export const DocumentSigningRadioField = ({ field, onSignField, onUnsignField }:
       )}
 
       {field.inserted && (
-        <RadioGroup className="my-0.5 gap-y-1">
+        <RadioGroup value={field.customText ?? ''} className="my-0.5 gap-y-1">
           {values?.map((item, index) => (
             <div key={index} className="flex items-center">
               <RadioGroupItem
                 className="h-3 w-3"
                 value={item.value}
                 id={`option-${field.id}-${item.id}`}
-                checked={item.value === field.customText}
                 disabled={isReadOnly}
               />
               {!item.value.includes('empty-value-') && item.value && (

apps/remix/app/components/general/document/document-attachments-popover.tsx

@@ -21,12 +21,6 @@ export type DocumentAttachmentsPopoverProps = {
   envelopeId: string;
   buttonClassName?: string;
   buttonSize?: 'sm' | 'default';
-
-  /**
-   * Visually hide the button label below the `sm` breakpoint while keeping it
-   * available to screen readers.
-   */
-  collapseLabelOnMobile?: boolean;
 };
 
 const ZAttachmentFormSchema = z.object({
@@ -41,7 +35,6 @@ export const DocumentAttachmentsPopover = ({
   envelopeId,
   buttonClassName,
   buttonSize,
-  collapseLabelOnMobile = false,
 }: DocumentAttachmentsPopoverProps) => {
   const { toast } = useToast();
   const { _ } = useLingui();
@@ -136,7 +129,7 @@ export const DocumentAttachmentsPopover = ({
         <Button variant="outline" className={cn('gap-2', buttonClassName)} size={buttonSize}>
           <Paperclip className="h-4 w-4" />
 
-          <span className={cn(collapseLabelOnMobile && 'sr-only sm:not-sr-only')}>
+          <span>
             <Trans>Attachments</Trans>
             {attachments && attachments.data.length > 0 && <span className="ml-1">({attachments.data.length})</span>}
           </span>

apps/remix/app/components/general/document/embedded-editor-attachment-popover.tsx

@@ -19,12 +19,6 @@ import { z } from 'zod';
 export type EmbeddedEditorAttachmentPopoverProps = {
   buttonClassName?: string;
   buttonSize?: 'sm' | 'default';
-
-  /**
-   * Visually hide the button label below the `sm` breakpoint while keeping it
-   * available to screen readers.
-   */
-  collapseLabelOnMobile?: boolean;
 };
 
 const ZAttachmentFormSchema = z.object({
@@ -38,7 +32,6 @@ type TAttachmentFormSchema = z.infer<typeof ZAttachmentFormSchema>;
 export const EmbeddedEditorAttachmentPopover = ({
   buttonClassName,
   buttonSize,
-  collapseLabelOnMobile = false,
 }: EmbeddedEditorAttachmentPopoverProps) => {
   const { toast } = useToast();
   const { _ } = useLingui();
@@ -97,7 +90,7 @@ export const EmbeddedEditorAttachmentPopover = ({
         <Button variant="outline" className={cn('gap-2', buttonClassName)} size={buttonSize}>
           <Paperclip className="h-4 w-4" />
 
-          <span className={cn(collapseLabelOnMobile && 'sr-only sm:not-sr-only')}>
+          <span>
             <Trans>Attachments</Trans>
             {attachments.length > 0 && <span className="ml-1">({attachments.length})</span>}
           </span>

apps/remix/app/components/general/envelope-editor/envelope-editor-fields-drag-drop.tsx

@@ -24,7 +24,6 @@ import {
   UserIcon,
 } from 'lucide-react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { createPortal } from 'react-dom';
 
 const MIN_HEIGHT_PX = 12;
 const MIN_WIDTH_PX = 36;
@@ -89,18 +88,11 @@ export const fieldButtonList = [
 type EnvelopeEditorFieldDragDropProps = {
   selectedRecipientId: number | null;
   selectedEnvelopeItemId: string | null;
-
-  /**
-   * Called when the user picks a field type from the palette, before the field
-   * is placed on the document.
-   */
-  onFieldSelect?: (fieldType: FieldType) => void;
 };
 
 export const EnvelopeEditorFieldDragDrop = ({
   selectedRecipientId,
   selectedEnvelopeItemId,
-  onFieldSelect,
 }: EnvelopeEditorFieldDragDropProps) => {
   const { envelope, editorFields, isTemplate, getRecipientColorKey } = useCurrentEnvelopeEditor();
 
@@ -253,10 +245,7 @@ export const EnvelopeEditorFieldDragDrop = ({
             disabled={isFieldsDisabled}
             key={field.type}
             type="button"
-            onClick={() => {
-              setSelectedField(field.type);
-              onFieldSelect?.(field.type);
-            }}
+            onClick={() => setSelectedField(field.type)}
             onMouseDown={() => setSelectedField(field.type)}
             data-selected={selectedField === field.type ? true : undefined}
             className={cn(
@@ -278,14 +267,7 @@ export const EnvelopeEditorFieldDragDrop = ({
         ))}
       </div>
 
-      {/*
-       * Portalled to the body because the fields panel ancestor carries a CSS
-       * transform (the slide-in overlay below `md`), which would otherwise
-       * become the containing block for this fixed-position preview and pin
-       * it inside the panel instead of the viewport.
-       */}
-      {selectedField &&
-        createPortal(
+      {selectedField && (
         <div
           className={cn(
             'pointer-events-none fixed z-50 flex cursor-pointer flex-col items-center justify-center rounded-[2px] bg-white font-noto text-muted-foreground ring-2 transition duration-200 [container-type:size] dark:text-muted',
@@ -304,8 +286,7 @@ export const EnvelopeEditorFieldDragDrop = ({
           }}
         >
           <span className="text-[clamp(0.425rem,25cqw,0.825rem)]">{t(FRIENDLY_FIELD_TYPE[selectedField])}</span>
-          </div>,
-          document.body,
+        </div>
       )}
     </>
   );

apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page.tsx

@@ -30,7 +30,7 @@ import { msg } from '@lingui/core/macro';
 import { useLingui } from '@lingui/react';
 import { Trans } from '@lingui/react/macro';
 import { DocumentStatus, FieldType, RecipientRole } from '@prisma/client';
-import { AlertTriangleIcon, FileTextIcon, MousePointerClickIcon, PencilIcon, SparklesIcon, XIcon } from 'lucide-react';
+import { AlertTriangleIcon, FileTextIcon, PencilIcon, SparklesIcon } from 'lucide-react';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { useRevalidator, useSearchParams } from 'react-router';
 import { isDeepEqual } from 'remeda';
@@ -89,10 +89,6 @@ export const EnvelopeEditorFieldsPage = () => {
   const [isAiEnableDialogOpen, setIsAiEnableDialogOpen] = useState(false);
   const { revalidate } = useRevalidator();
 
-  // Whether the fields panel overlay is open. Only relevant below the `md`
-  // breakpoint, where the panel is hidden behind a floating trigger button.
-  const [isMobileFieldsPanelOpen, setIsMobileFieldsPanelOpen] = useState(false);
-
   const envelopeItemPermissions = useMemo(
     () => getEnvelopeItemPermissions(envelope, envelope.recipients),
     [envelope, envelope.recipients],
@@ -191,10 +187,6 @@ export const EnvelopeEditorFieldsPage = () => {
   }, []);
 
   const onDetectClick = () => {
-    // Close the panel overlay on small viewports so the document stays
-    // visible while the AI dialogs are open.
-    setIsMobileFieldsPanelOpen(false);
-
     if (!team.preferences.aiFeaturesEnabled) {
       setIsAiEnableDialogOpen(true);
       return;
@@ -316,57 +308,7 @@ export const EnvelopeEditorFieldsPage = () => {
 
       {/* Right Section - Form Fields Panel */}
       {currentEnvelopeItem && envelope.recipients.length > 0 && (
-        <>
-          {/* Floating trigger for the fields panel, visible below the `md` breakpoint. */}
-          <Button
-            type="button"
-            className="fixed right-4 bottom-4 z-30 shadow-lg md:hidden"
-            onClick={() => setIsMobileFieldsPanelOpen(true)}
-          >
-            <MousePointerClickIcon className="mr-2 h-4 w-4" />
-            <Trans>Fields</Trans>
-          </Button>
-
-          {isMobileFieldsPanelOpen && (
-            <div
-              role="presentation"
-              className="fixed inset-0 z-40 bg-background/80 backdrop-blur-sm md:hidden"
-              onClick={() => setIsMobileFieldsPanelOpen(false)}
-            />
-          )}
-
-          {/*
-           * Below `md` the panel is a slide-in overlay, from `md` upwards it is a
-           * static sidebar.
-           *
-           * This is deliberately one always-mounted element toggled with CSS rather
-           * than a Sheet/Drawer: the field palette registers window-level mouse
-           * listeners that must survive the panel closing mid click-to-place, and
-           * unmounting would also double-mount the field settings forms and AI
-           * dialogs. `invisible` (with the transition covering visibility) keeps the
-           * closed overlay out of the tab order and accessibility tree.
-           */}
-          <div
-            className={cn(
-              'fixed inset-y-0 right-0 z-50 w-80 max-w-[85vw] overflow-y-auto border-border border-l bg-background py-4 transition-[transform,visibility] duration-200',
-              isMobileFieldsPanelOpen ? 'translate-x-0 shadow-xl' : 'translate-x-full max-md:invisible',
-              'md:sticky md:top-0 md:z-auto md:h-full md:w-80 md:max-w-none md:flex-shrink-0 md:translate-x-0 md:shadow-none md:transition-none',
-            )}
-          >
-            {/* Panel header with close button, visible below the `md` breakpoint. */}
-            <div className="mb-4 flex items-center justify-between px-4 md:hidden">
-              <h3 className="font-semibold text-foreground text-sm">
-                <Trans>Fields</Trans>
-              </h3>
-
-              <Button variant="ghost" size="sm" onClick={() => setIsMobileFieldsPanelOpen(false)}>
-                <XIcon className="h-4 w-4" />
-                <span className="sr-only">
-                  <Trans>Close</Trans>
-                </span>
-              </Button>
-            </div>
-
+        <div className="sticky top-0 h-full w-80 flex-shrink-0 overflow-y-auto border-border border-l bg-background py-4">
           {/* Recipient selector section. */}
           <section className="px-4">
             <h3 className="mb-2 font-semibold text-foreground text-sm">
@@ -405,7 +347,6 @@ export const EnvelopeEditorFieldsPage = () => {
             <EnvelopeEditorFieldDragDrop
               selectedRecipientId={editorFields.selectedRecipient?.id ?? null}
               selectedEnvelopeItemId={currentEnvelopeItem?.id ?? null}
-                onFieldSelect={() => setIsMobileFieldsPanelOpen(false)}
             />
 
             {editorConfig.fields?.allowAIDetection && (
@@ -573,7 +514,6 @@ export const EnvelopeEditorFieldsPage = () => {
             )}
           </AnimateGenericFadeInOut>
         </div>
-        </>
       )}
     </div>
   );

apps/remix/app/components/general/envelope-editor/envelope-editor-header.tsx

@@ -70,18 +70,17 @@ export default function EnvelopeEditorHeader() {
   return (
     <nav className="w-full border-border border-b bg-background px-4 py-3 md:px-6">
       <div className="flex items-center justify-between gap-4">
-        <div className="flex min-w-0 flex-1 items-center gap-2 sm:gap-4">
-          {/* The logo and separator are hidden on small viewports to leave room for the title. */}
+        <div className="flex min-w-0 flex-1 items-center space-x-4">
           {editorConfig.embedded?.customBrandingLogo ? (
-            <img src={`/api/branding/logo/team/${envelope.teamId}`} alt="Logo" className="hidden h-6 w-auto sm:block" />
+            <img src={`/api/branding/logo/team/${envelope.teamId}`} alt="Logo" className="h-6 w-auto" />
           ) : (
-            <Link to="/" className="hidden sm:block">
+            <Link to="/">
               <BrandingLogo className="h-6 w-auto" />
             </Link>
           )}
-          <Separator orientation="vertical" className="hidden h-6 shrink-0 sm:block" />
+          <Separator orientation="vertical" className="h-6 shrink-0" />
 
-          <div className="flex min-w-0 items-center gap-2">
+          <div className="flex min-w-0 items-center space-x-2">
             <EnvelopeItemTitleInput
               dataTestId="envelope-title-input"
               disabled={!envelopeItemPermissions.canTitleBeChanged || !allowConfigureEnvelopeTitle}
@@ -99,19 +98,19 @@ export default function EnvelopeEditorHeader() {
             {envelope.type === EnvelopeType.TEMPLATE && (
               <>
                 {envelope.templateType === TemplateType.PRIVATE && (
-                  <Badge variant="secondary" className="hidden shrink-0 sm:inline-flex">
+                  <Badge variant="secondary" className="shrink-0">
                     <LockIcon className="mr-2 h-4 w-4 text-blue-600 dark:text-blue-300" />
                     <Trans>Private Template</Trans>
                   </Badge>
                 )}
                 {envelope.templateType === TemplateType.ORGANISATION && (
-                  <Badge variant="orange" className="hidden shrink-0 sm:inline-flex">
+                  <Badge variant="orange" className="shrink-0">
                     <Building2Icon className="mr-2 size-4" />
                     <Trans>Organisation Template</Trans>
                   </Badge>
                 )}
                 {envelope.templateType === TemplateType.PUBLIC && (
-                  <Badge variant="default" className="hidden shrink-0 sm:inline-flex">
+                  <Badge variant="default" className="shrink-0">
                     <Globe2Icon className="mr-2 h-4 w-4 text-green-500 dark:text-green-300" />
                     <Trans>Public Template</Trans>
                   </Badge>
@@ -119,7 +118,7 @@ export default function EnvelopeEditorHeader() {
 
                 {envelope.directLink?.token && (
                   <TemplateDirectLinkBadge
-                    className="hidden shrink-0 py-1 sm:flex"
+                    className="shrink-0 py-1"
                     token={envelope.directLink.token}
                     enabled={envelope.directLink.enabled}
                   />
@@ -181,9 +180,9 @@ export default function EnvelopeEditorHeader() {
         <div className="flex shrink-0 items-center space-x-2">
           {allowAttachments &&
             (isEmbedded ? (
-              <EmbeddedEditorAttachmentPopover buttonSize="sm" collapseLabelOnMobile />
+              <EmbeddedEditorAttachmentPopover buttonSize="sm" />
             ) : (
-              <DocumentAttachmentsPopover envelopeId={envelope.id} buttonSize="sm" collapseLabelOnMobile />
+              <DocumentAttachmentsPopover envelopeId={envelope.id} buttonSize="sm" />
             ))}
 
           {editorConfig.settings && (
@@ -203,10 +202,8 @@ export default function EnvelopeEditorHeader() {
                   documentRootPath={relativePath.documentRootPath}
                   trigger={
                     <Button size="sm">
-                      <SendIcon className="h-4 w-4 sm:mr-2" />
-                      <span className="sr-only sm:not-sr-only">
+                      <SendIcon className="mr-2 h-4 w-4" />
                       <Trans>Send Document</Trans>
-                      </span>
                     </Button>
                   }
                 />
@@ -215,10 +212,8 @@ export default function EnvelopeEditorHeader() {
                   envelope={envelope}
                   trigger={
                     <Button size="sm">
-                      <SendIcon className="h-4 w-4 sm:mr-2" />
-                      <span className="sr-only sm:not-sr-only">
+                      <SendIcon className="mr-2 h-4 w-4" />
                       <Trans>Resend Document</Trans>
-                      </span>
                     </Button>
                   }
                 />

apps/remix/app/components/general/envelope-editor/envelope-editor-recipient-form.tsx

@@ -592,7 +592,7 @@ export const EnvelopeEditorRecipientForm = () => {
 
   return (
     <Card backdropBlur={false} className="border">
-      <CardHeader className="flex flex-col justify-between gap-4 space-y-0 sm:flex-row">
+      <CardHeader className="flex flex-row justify-between">
         <div>
           <CardTitle>
             <Trans>Recipients</Trans>
@@ -602,7 +602,7 @@ export const EnvelopeEditorRecipientForm = () => {
           </CardDescription>
         </div>
 
-        <div className="flex flex-row flex-wrap items-center gap-2">
+        <div className="flex flex-row items-center space-x-2">
           {editorConfig.recipients?.allowAIDetection && (
             <Tooltip>
               <TooltipTrigger asChild>
@@ -842,9 +842,9 @@ export const EnvelopeEditorRecipientForm = () => {
                                 'pr-3': isSigningOrderSequential,
                               })}
                             >
-                              <div className="flex flex-row flex-wrap items-center gap-2 sm:flex-nowrap">
+                              <div className="flex flex-row items-center gap-x-2">
                                 {isSigningOrderSequential && isCcRecipient(signer) && (
-                                  <div className="mt-auto hidden h-10 w-[4.25rem] flex-shrink-0 sm:block" />
+                                  <div className="mt-auto h-10 w-[4.25rem] flex-shrink-0" />
                                 )}
 
                                 {isSigningOrderSequential && !isCcRecipient(signer) && (
@@ -900,9 +900,8 @@ export const EnvelopeEditorRecipientForm = () => {
                                           !form.formState.errors.signers[index]?.email,
                                       })}
                                     >
-                                      {/* Below `sm` the rows are stacked, so every row needs its own labels. */}
-                                      {!showAdvancedSettings && (
-                                        <FormLabel className={cn(index !== 0 && 'sm:hidden')}>
+                                      {!showAdvancedSettings && index === 0 && (
+                                        <FormLabel>
                                           <Trans>Email</Trans>
                                         </FormLabel>
                                       )}
@@ -948,8 +947,8 @@ export const EnvelopeEditorRecipientForm = () => {
                                           !form.formState.errors.signers[index]?.name,
                                       })}
                                     >
-                                      {!showAdvancedSettings && (
-                                        <FormLabel className={cn(index !== 0 && 'sm:hidden')}>
+                                      {!showAdvancedSettings && index === 0 && (
+                                        <FormLabel>
                                           <Trans>Name</Trans>
                                         </FormLabel>
                                       )}

apps/remix/app/components/general/envelope-editor/envelope-editor-upload-page.tsx

@@ -448,7 +448,7 @@ export const EnvelopeEditorUploadPage = () => {
   };
 
   return (
-    <div className="mx-auto max-w-4xl space-y-6 p-4 md:p-8">
+    <div className="mx-auto max-w-4xl space-y-6 p-8">
       <input {...getReplaceInputProps()} />
 
       <EnvelopeEditorInvalidDirectTemplateAlert className="max-w-none" />

apps/remix/app/components/general/envelope-editor/envelope-editor.tsx

@@ -1,4 +1,3 @@
-import { useIsMobileViewport } from '@documenso/lib/client-only/hooks/use-media-query';
 import type { EnvelopeEditorStep } from '@documenso/lib/client-only/providers/envelope-editor-provider';
 import { useCurrentEnvelopeEditor } from '@documenso/lib/client-only/providers/envelope-editor-provider';
 import { mapSecondaryIdToTemplateId } from '@documenso/lib/utils/envelope';
@@ -90,8 +89,6 @@ export const EnvelopeEditor = () => {
 
   const [searchParams, setSearchParams] = useSearchParams();
 
-  const isMobileViewport = useIsMobileViewport();
-
   const {
     general: { minimizeLeftSidebar, allowUploadAndRecipientStep, allowAddFieldsStep, allowPreviewStep },
     actions: {
@@ -104,10 +101,6 @@ export const EnvelopeEditor = () => {
     },
   } = editorConfig;
 
-  // Fall back to the icon-only sidebar on small viewports since the full
-  // sidebar would consume most of the screen.
-  const isSidebarMinimized = minimizeLeftSidebar || isMobileViewport;
-
   const envelopeEditorSteps = useMemo(() => {
     const steps: EnvelopeEditorStepData[] = [];
 
@@ -182,19 +175,19 @@ export const EnvelopeEditor = () => {
   const currentStepData = envelopeEditorSteps.find((step) => step.id === searchParamsStep) || envelopeEditorSteps[0];
 
   return (
-    <div className="h-[100dvh] w-full bg-envelope-editor-background">
+    <div className="h-screen w-screen bg-envelope-editor-background">
       <EnvelopeEditorHeader />
 
       {/* Main Content Area */}
-      <div className="flex h-[calc(100dvh-4rem)] w-full">
+      <div className="flex h-[calc(100vh-4rem)] w-screen">
         {/* Left Section - Step Navigation */}
         <div
           className={cn('flex w-80 flex-shrink-0 flex-col overflow-y-auto border-border border-r bg-background py-4', {
-            'w-14': isSidebarMinimized,
+            'w-14': minimizeLeftSidebar,
           })}
         >
           {/* Left section step selector. */}
-          {isSidebarMinimized ? (
+          {minimizeLeftSidebar ? (
             <div className="flex justify-center px-4">
               <div className="relative flex h-10 w-10 items-center justify-center">
                 <svg className="size-10 -rotate-90" viewBox="0 0 40 40" aria-hidden>
@@ -261,8 +254,8 @@ export const EnvelopeEditor = () => {
 
           <div
             className={cn('space-y-3', {
-              'px-4': !isSidebarMinimized,
-              'mt-4 flex flex-col items-center': isSidebarMinimized,
+              'px-4': !minimizeLeftSidebar,
+              'mt-4 flex flex-col items-center': minimizeLeftSidebar,
             })}
           >
             {envelopeEditorSteps.map((step) => {
@@ -281,7 +274,7 @@ export const EnvelopeEditor = () => {
                         : 'border border-gray-200 hover:bg-gray-50 dark:border-gray-400/20 dark:hover:bg-gray-400/10'
                     }`,
                     {
-                      'p-3': !isSidebarMinimized,
+                      'p-3': !minimizeLeftSidebar,
                     },
                   )}
                   onClick={() => void navigateToStep(step.id as EnvelopeEditorStep)}
@@ -297,7 +290,7 @@ export const EnvelopeEditor = () => {
                       <Icon className={`h-4 w-4 ${isActive ? 'text-green-600' : 'text-gray-600'}`} />
                     </div>
 
-                    {!isSidebarMinimized && (
+                    {!minimizeLeftSidebar && (
                       <div>
                         <div
                           className={`font-medium text-sm ${
@@ -319,17 +312,17 @@ export const EnvelopeEditor = () => {
 
           <Separator
             className={cn('my-6', {
-              'mx-auto mb-4 w-4/5': isSidebarMinimized,
+              'mx-auto mb-4 w-4/5': minimizeLeftSidebar,
             })}
           />
 
           {/* Quick Actions. */}
           <div
             className={cn('space-y-3 px-4 [&_.lucide]:text-muted-foreground', {
-              'px-2': isSidebarMinimized,
+              'px-2': minimizeLeftSidebar,
             })}
           >
-            {!isSidebarMinimized && (
+            {!minimizeLeftSidebar && (
               <h4 className="font-semibold text-foreground text-sm">
                 <Trans>Quick Actions</Trans>
               </h4>
@@ -341,7 +334,7 @@ export const EnvelopeEditor = () => {
                   <Button variant="ghost" size="sm" className="w-full justify-start" title={t(msg`Settings`)}>
                     <SettingsIcon className="h-4 w-4" />
 
-                    {!isSidebarMinimized && (
+                    {!minimizeLeftSidebar && (
                       <span className="ml-2">
                         {isDocument ? <Trans>Document Settings</Trans> : <Trans>Template Settings</Trans>}
                       </span>
@@ -359,7 +352,7 @@ export const EnvelopeEditor = () => {
                     <Button variant="ghost" size="sm" className="w-full justify-start" title={t(msg`Send Envelope`)}>
                       <SendIcon className="h-4 w-4" />
 
-                      {!isSidebarMinimized && (
+                      {!minimizeLeftSidebar && (
                         <span className="ml-2">
                           <Trans>Send Document</Trans>
                         </span>
@@ -374,7 +367,7 @@ export const EnvelopeEditor = () => {
                     <Button variant="ghost" size="sm" className="w-full justify-start" title={t(msg`Resend Envelope`)}>
                       <SendIcon className="h-4 w-4" />
 
-                      {!isSidebarMinimized && (
+                      {!minimizeLeftSidebar && (
                         <span className="ml-2">
                           <Trans>Resend Document</Trans>
                         </span>
@@ -396,7 +389,7 @@ export const EnvelopeEditor = () => {
                   <Button variant="ghost" size="sm" className="w-full justify-start" title={t(msg`Direct Link`)}>
                     <LinkIcon className="h-4 w-4" />
 
-                    {!isSidebarMinimized && (
+                    {!minimizeLeftSidebar && (
                       <span className="ml-2">
                         <Trans>Direct Link</Trans>
                       </span>
@@ -414,7 +407,7 @@ export const EnvelopeEditor = () => {
                   <Button variant="ghost" size="sm" className="w-full justify-start" title={t(msg`Duplicate Envelope`)}>
                     <CopyPlusIcon className="h-4 w-4" />
 
-                    {!isSidebarMinimized && (
+                    {!minimizeLeftSidebar && (
                       <span className="ml-2">
                         {isDocument ? <Trans>Duplicate Document</Trans> : <Trans>Duplicate Template</Trans>}
                       </span>
@@ -431,7 +424,7 @@ export const EnvelopeEditor = () => {
                   <Button variant="ghost" size="sm" className="w-full justify-start" title={t(msg`Save as Template`)}>
                     <FileOutputIcon className="h-4 w-4" />
 
-                    {!isSidebarMinimized && (
+                    {!minimizeLeftSidebar && (
                       <span className="ml-2">
                         <Trans>Save as Template</Trans>
                       </span>
@@ -451,7 +444,7 @@ export const EnvelopeEditor = () => {
                   <Button variant="ghost" size="sm" className="w-full justify-start" title={t(msg`Download PDF`)}>
                     <DownloadCloudIcon className="h-4 w-4" />
 
-                    {!isSidebarMinimized && (
+                    {!minimizeLeftSidebar && (
                       <span className="ml-2">
                         <Trans>Download PDF</Trans>
                       </span>
@@ -479,7 +472,7 @@ export const EnvelopeEditor = () => {
                   >
                     <Trash2Icon className="h-4 w-4" />
 
-                    {!isSidebarMinimized && (
+                    {!minimizeLeftSidebar && (
                       <span className="ml-2">
                         {isDocument ? <Trans>Delete Document</Trans> : <Trans>Delete Template</Trans>}
                       </span>
@@ -501,20 +494,20 @@ export const EnvelopeEditor = () => {
           {!editorConfig.embedded && (
             <div
               className={cn('mt-auto px-4', {
-                'px-2': isSidebarMinimized,
+                'px-2': minimizeLeftSidebar,
               })}
             >
               <Button
                 variant="ghost"
                 className={cn('w-full justify-start', {
-                  'flex items-center justify-center': isSidebarMinimized,
+                  'flex items-center justify-center': minimizeLeftSidebar,
                 })}
                 asChild
               >
                 <Link to={relativePath.basePath}>
                   <ArrowLeftIcon className="h-4 w-4 flex-shrink-0" />
 
-                  {!isSidebarMinimized && (
+                  {!minimizeLeftSidebar && (
                     <span className="ml-2">
                       {isDocument ? <Trans>Return to documents</Trans> : <Trans>Return to templates</Trans>}
                     </span>

apps/remix/app/components/general/envelope-signing/envelope-signing-complete-dialog.tsx

@@ -148,15 +148,11 @@ export const EnvelopeSignerCompleteDialog = () => {
       const error = AppError.parseError(err);
 
       if (error.code !== AppErrorCode.TWO_FACTOR_AUTH_FAILED) {
-        toast({
-          title: t`Something went wrong`,
-          description: t`We were unable to submit this document at this time. Please try again later.`,
-          variant: 'destructive',
-        });
-
         onDocumentError?.();
       }
 
+      // Rethrow so DocumentSigningCompleteDialog can handle 2FA retries and
+      // toast a specific completion error message.
       throw err;
     }
   };
@@ -224,14 +220,11 @@ export const EnvelopeSignerCompleteDialog = () => {
       }
     } catch (err) {
       console.log('err', err);
-      toast({
-        title: t`Something went wrong`,
-        description: t`We were unable to submit this document at this time. Please try again later.`,
-        variant: 'destructive',
-      });
 
       onDocumentError?.();
 
+      // Rethrow so DocumentSigningCompleteDialog can toast a specific
+      // completion error message.
       throw err;
     }
   };

apps/remix/app/components/general/pdf-viewer/pdf-viewer.tsx

@@ -215,7 +215,7 @@ export default function PDFViewer({
 
 type VirtualizedPageListProps = {
   scrollParentRef: ScrollTarget;
-  constraintRef: React.RefObject<HTMLDivElement>;
+  constraintRef: React.RefObject<HTMLDivElement | null>;
   pages: PageMeta[];
   numPages: number;
   pdf: pdfjsLib.PDFDocumentProxy;

apps/remix/app/entry.client.tsx

@@ -31,6 +31,26 @@ function initPosthog() {
   }
 }
 
+/**
+ * Surfaces hydration recoveries (React 19 discards the server HTML and
+ * re-renders on the client instead of dying) so we can track how often
+ * extensions/early clicks interfere with hydration in the wild.
+ */
+function onRecoverableError(error: unknown, errorInfo: { componentStack?: string }) {
+  console.error('[hydration] recovered from error', error, errorInfo.componentStack);
+
+  if (extractPostHogConfig()) {
+    void import('posthog-js').then(({ default: posthog }) => {
+      if (posthog.__loaded) {
+        posthog.capture('$hydration_recoverable_error', {
+          message: error instanceof Error ? error.message : String(error),
+          componentStack: errorInfo.componentStack,
+        });
+      }
+    });
+  }
+}
+
 async function main() {
   const locale = detect(fromHtmlTag('lang')) || 'en';
 
@@ -44,6 +64,7 @@ async function main() {
           <HydratedRouter />
         </I18nProvider>
       </StrictMode>,
+      { onRecoverableError },
     );
   });
 

apps/remix/app/utils/toast-error-messages.ts

@@ -42,6 +42,51 @@ export const getDirectTemplateErrorMessage = (code: string): ToastMessageDescrip
     }));
 };
 
+/**
+ * Toast messages for errors thrown while a recipient attempts to complete
+ * (sign) a document, so the user knows whether retrying can help and what to
+ * do next.
+ */
+export const getSigningCompletionErrorMessage = (code: string): ToastMessageDescriptor => {
+  return match(code)
+    .with(AppErrorCode.NOT_FOUND, () => ({
+      title: msg`Document no longer available`,
+      description: msg`This document can no longer be signed. It may have been removed by the sender, or your signing access may have been revoked. Please contact the sender for a new signing link.`,
+    }))
+    .with(AppErrorCode.RECIPIENT_HAS_UNSIGNED_FIELDS, () => ({
+      title: msg`Some fields were not saved`,
+      description: msg`One or more of your required fields have not been saved. Please refresh the page, complete any empty required fields, and try again.`,
+    }))
+    .with(AppErrorCode.RECIPIENT_OUT_OF_TURN, () => ({
+      title: msg`It's not your turn to sign yet`,
+      description: msg`This document is signed in a set order and other recipients must sign before you. You will receive an email when it is your turn.`,
+    }))
+    .with(AppErrorCode.RECIPIENT_EXPIRED, () => ({
+      title: msg`Signing link expired`,
+      description: msg`Your signing link has expired. Please contact the sender to request a new one.`,
+    }))
+    .with(AppErrorCode.ENVELOPE_COMPLETED, () => ({
+      title: msg`Document already completed`,
+      description: msg`This document has already been completed and no further signatures can be added.`,
+    }))
+    .with(AppErrorCode.ENVELOPE_REJECTED, () => ({
+      title: msg`Document rejected`,
+      description: msg`This document has been rejected by a recipient and can no longer be signed.`,
+    }))
+    .with(AppErrorCode.ENVELOPE_CANCELLED, () => ({
+      title: msg`Document cancelled`,
+      description: msg`This document has been cancelled by the sender and can no longer be signed. Please contact the sender if you believe this is a mistake.`,
+    }))
+    .with(AppErrorCode.ENVELOPE_DRAFT, () => ({
+      title: msg`Document not ready`,
+      description: msg`This document has not been sent for signing yet. Please wait for the sender to send it before signing.`,
+    }))
+    .otherwise(() => ({
+      title: msg`Something went wrong`,
+      description: msg`We were unable to submit this document at this time. Please try again later.`,
+    }));
+};
+
 export const getUploadErrorMessage = (code: string): ToastMessageDescriptor => {
   return match(code)
     .with(AppErrorCode.TOO_MANY_REQUESTS, () => FAIR_USE_LIMIT_EXCEEDED_ERROR_MESSAGE)

apps/remix/package.json

@@ -57,9 +57,9 @@
     "papaparse": "^5.5.3",
     "posthog-js": "^1.297.2",
     "posthog-node": "4.18.0",
-    "react": "^18",
+    "react": "^19.2.7",
     "react-call": "^1.8.1",
-    "react-dom": "^18",
+    "react-dom": "^19.2.7",
     "react-dropzone": "^14.3.8",
     "react-hook-form": "^7.66.1",
     "react-hotkeys-hook": "^4.6.2",
@@ -93,11 +93,11 @@
     "@types/luxon": "^3.7.1",
     "@types/node": "^20",
     "@types/papaparse": "^5.5.0",
-    "@types/react": "18.3.27",
-    "@types/react-dom": "^18",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "@types/ua-parser-js": "^0.7.39",
     "cross-env": "^10.1.0",
-    "esbuild": "^0.27.0",
+    "esbuild": "^0.28.1",
     "remix-flat-routes": "^0.8.5",
     "rollup": "^4.53.3",
     "tsx": "^4.23.1",
@@ -106,5 +106,5 @@
     "vite-plugin-babel-macros": "^1.0.6",
     "vite-tsconfig-paths": "^5.1.4"
   },
-  "version": "2.16.0"
+  "version": "2.17.0"
 }

apps/remix/vite.config.ts

@@ -121,7 +121,7 @@ export default defineConfig({
         'nodemailer',
         /playwright/,
         '@playwright/browser-chromium',
-        'skia-canvas',
+        '@documenso/skia-canvas',
       ],
     },
   },

docker/Dockerfile

@@ -76,7 +76,6 @@ COPY --from=builder /app/out/json/ .
 COPY --from=builder /app/out/package-lock.json ./package-lock.json
 
 COPY --from=builder /app/lingui.config.ts ./lingui.config.ts
-COPY --from=builder /app/patches ./patches
 
 RUN npm ci
 
@@ -115,8 +114,6 @@ WORKDIR /app
 COPY --from=builder --chown=nodejs:nodejs /app/out/json/ .
 # Copy the tailwind config files across
 COPY --from=builder --chown=nodejs:nodejs /app/out/full/packages/tailwind-config ./packages/tailwind-config
-# Copy the patches across
-COPY --from=builder --chown=nodejs:nodejs /app/patches ./patches
 
 RUN npm ci --only=production
 

docker/development/compose.yml

@@ -7,7 +7,7 @@ services:
     volumes:
       - documenso_database:/var/lib/postgresql/data
     healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER}']
+      test: ['CMD-SHELL', 'pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB']
       interval: 10s
       timeout: 5s
       retries: 5

docker/production/compose.yml

@@ -8,7 +8,7 @@ services:
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?err}
       - POSTGRES_DB=${POSTGRES_DB:?err}
     healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER}']
+      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}']
       interval: 10s
       timeout: 5s
       retries: 5

docker/testing/compose.yml

@@ -8,7 +8,7 @@ services:
       - POSTGRES_PASSWORD=password
       - POSTGRES_DB=documenso
     healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U documenso']
+      test: ['CMD-SHELL', 'pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB']
       interval: 1s
       timeout: 5s
       retries: 5

package.json

@@ -5,7 +5,7 @@
     "apps/*",
     "packages/*"
   ],
-  "version": "2.16.0",
+  "version": "2.17.0",
   "scripts": {
     "postinstall": "patch-package",
     "build": "turbo run build",
@@ -48,20 +48,23 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.8",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@datadog/pprof": "^5.13.5",
+    "@documenso/skia-canvas": "^3.0.8-documenso.3",
     "@lingui/cli": "^5.6.0",
     "@prisma/client": "^6.19.0",
-    "@trpc/client": "11.8.1",
-    "@trpc/react-query": "11.8.1",
-    "@trpc/server": "11.8.1",
+    "@trpc/client": "11.17.0",
+    "@trpc/react-query": "11.17.0",
+    "@trpc/server": "11.17.0",
     "@ts-rest/core": "^3.52.1",
     "@ts-rest/open-api": "^3.52.1",
     "@ts-rest/serverless": "^3.52.1",
     "dotenv": "^17.2.3",
     "dotenv-cli": "^11.0.0",
-    "esbuild": "^0.27.0",
+    "esbuild": "^0.28.1",
     "husky": "^9.1.7",
     "inngest": "^3.54.0",
     "inngest-cli": "^1.17.9",
@@ -86,27 +89,61 @@
     "zod-prisma-types": "3.3.5"
   },
   "dependencies": {
-    "@ai-sdk/google-vertex": "3.0.81",
+    "@ai-sdk/google-vertex": "5.0.48",
     "@documenso/prisma": "*",
     "@libpdf/core": "^0.4.1",
     "@lingui/conf": "^5.6.0",
     "@lingui/core": "^5.6.0",
     "@prisma/extension-read-replicas": "^0.4.1",
-    "ai": "^5.0.104",
+    "@radix-ui/react-accordion": "^1.2.16",
+    "@radix-ui/react-alert-dialog": "^1.1.19",
+    "@radix-ui/react-aspect-ratio": "^1.1.11",
+    "@radix-ui/react-avatar": "^1.2.2",
+    "@radix-ui/react-checkbox": "^1.3.7",
+    "@radix-ui/react-collapsible": "^1.1.16",
+    "@radix-ui/react-context-menu": "^2.3.3",
+    "@radix-ui/react-dialog": "^1.1.19",
+    "@radix-ui/react-dropdown-menu": "^2.1.20",
+    "@radix-ui/react-hover-card": "^1.1.19",
+    "@radix-ui/react-label": "^2.1.11",
+    "@radix-ui/react-menubar": "^1.1.20",
+    "@radix-ui/react-navigation-menu": "^1.2.18",
+    "@radix-ui/react-popover": "^1.1.19",
+    "@radix-ui/react-progress": "^1.1.12",
+    "@radix-ui/react-radio-group": "^1.4.3",
+    "@radix-ui/react-scroll-area": "^1.2.14",
+    "@radix-ui/react-select": "^2.3.3",
+    "@radix-ui/react-separator": "^1.1.11",
+    "@radix-ui/react-slider": "^1.4.3",
+    "@radix-ui/react-slot": "^1.3.0",
+    "@radix-ui/react-switch": "^1.3.3",
+    "@radix-ui/react-tabs": "^1.1.17",
+    "@radix-ui/react-toast": "^1.2.19",
+    "@radix-ui/react-toggle": "^1.1.14",
+    "@radix-ui/react-toggle-group": "^1.1.15",
+    "@radix-ui/react-tooltip": "^1.2.12",
+    "ai": "^7.0.58",
     "cron-parser": "^5.5.0",
     "fflate": "^0.8.3",
     "luxon": "^3.7.2",
     "patch-package": "^8.0.1",
     "posthog-node": "4.18.0",
-    "react": "^18",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "sharp": "0.35.3",
     "typescript": "5.6.2",
     "@marsidev/react-turnstile": "^1.5.0",
     "zod": "^3.25.76"
   },
   "overrides": {
     "lodash": "4.18.1",
+    "brace-expansion@1": "^1.1.18",
     "pdfjs-dist": "5.4.296",
     "postcss": "^8.5.19",
+    "react": "$react",
+    "react-dom": "$react-dom",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "typescript": "5.6.2",
     "zod": "$zod",
     "fumadocs-mdx": {

packages/ee/package.json

@@ -19,7 +19,7 @@
     "arctic": "^3.7.0",
     "hono": "^4.12.14",
     "luxon": "^3.7.2",
-    "react": "^18",
+    "react": "^19.2.7",
     "ts-pattern": "^5.9.0",
     "zod": "^3.25.76"
   }

packages/email/components.ts

@@ -1,17 +1,19 @@
-export { Body } from '@react-email/body';
-export { Button } from '@react-email/button';
-export { Column } from '@react-email/column';
-export { Container } from '@react-email/container';
-export { Font } from '@react-email/font';
-export { Head } from '@react-email/head';
-export { Heading } from '@react-email/heading';
-export { Hr } from '@react-email/hr';
-export { Html } from '@react-email/html';
-export { Img } from '@react-email/img';
-export { Link } from '@react-email/link';
-export { Preview } from '@react-email/preview';
-export { render } from '@react-email/render';
-export { Row } from '@react-email/row';
-export { Section } from '@react-email/section';
-export { Tailwind } from '@react-email/tailwind';
-export { Text } from '@react-email/text';
+export {
+  Body,
+  Button,
+  Column,
+  Container,
+  Font,
+  Head,
+  Heading,
+  Hr,
+  Html,
+  Img,
+  Link,
+  Preview,
+  Row,
+  render,
+  Section,
+  Tailwind,
+  Text,
+} from 'react-email';

packages/email/package.json

@@ -19,27 +19,9 @@
   "dependencies": {
     "@documenso/nodemailer-resend": "5.0.0",
     "@documenso/tailwind-config": "*",
-    "@react-email/body": "0.2.0",
-    "@react-email/button": "0.2.0",
-    "@react-email/code-block": "0.2.0",
-    "@react-email/code-inline": "0.0.5",
-    "@react-email/column": "0.0.13",
-    "@react-email/container": "0.0.15",
-    "@react-email/font": "0.0.9",
-    "@react-email/head": "0.0.12",
-    "@react-email/heading": "0.0.15",
-    "@react-email/hr": "0.0.11",
-    "@react-email/html": "0.0.11",
-    "@react-email/img": "0.0.11",
-    "@react-email/link": "0.0.12",
-    "@react-email/preview": "0.0.13",
-    "@react-email/render": "2.0.0",
-    "@react-email/row": "0.0.12",
-    "@react-email/section": "0.0.16",
-    "@react-email/tailwind": "^2.0.1",
-    "@react-email/text": "0.1.5",
+    "@react-email/render": "2.1.0",
     "nodemailer": "^9.0.0",
-    "react-email": "^5.0.6",
+    "react-email": "^6.9.0",
     "resend": "^6.5.2"
   },
   "devDependencies": {

packages/lib/client-only/hooks/use-autosave.ts

@@ -8,7 +8,7 @@ type SaveRequest<T, R> = {
 export const useAutoSave = <T, R = void>(onSave: (data: T) => Promise<R>, options: { delay?: number } = {}) => {
   const { delay = 2000 } = options;
 
-  const saveTimeoutRef = useRef<NodeJS.Timeout>();
+  const saveTimeoutRef = useRef<NodeJS.Timeout | undefined>(undefined);
   const saveQueueRef = useRef<SaveRequest<T, R>[]>([]);
   const isProcessingRef = useRef(false);
 

packages/lib/client-only/hooks/use-media-query.ts

@@ -1,34 +0,0 @@
-import { useCallback, useSyncExternalStore } from 'react';
-
-/**
- * Tracks whether the given CSS media query currently matches.
- *
- * Returns `false` on the server since the viewport is unknown until hydration.
- */
-export const useMediaQuery = (query: string) => {
-  const subscribe = useCallback(
-    (onStoreChange: () => void) => {
-      const mediaQueryList = window.matchMedia(query);
-
-      mediaQueryList.addEventListener('change', onStoreChange);
-
-      return () => mediaQueryList.removeEventListener('change', onStoreChange);
-    },
-    [query],
-  );
-
-  return useSyncExternalStore(
-    subscribe,
-    () => window.matchMedia(query).matches,
-    // The server snapshot: the viewport is unknown during SSR, so we assume
-    // the query does not match rather than throwing. React re-renders with
-    // the real value after hydration, so the only cost is a brief first
-    // paint with the non-matching variant.
-    () => false,
-  );
-};
-
-/**
- * Whether the viewport is below the Tailwind `md` breakpoint (768px).
- */
-export const useIsMobileViewport = () => useMediaQuery('(max-width: 767px)');

packages/lib/client-only/providers/envelope-editor-provider.tsx

@@ -15,7 +15,7 @@ import { useToast } from '@documenso/ui/primitives/use-toast';
 import { useLingui } from '@lingui/react/macro';
 import { EnvelopeType, Prisma, ReadStatus, SendStatus, SigningStatus } from '@prisma/client';
 import type React from 'react';
-import { createContext, useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { createContext, useCallback, useContext, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { useSearchParams } from 'react-router';
 
 import type { TDocumentEmailSettings } from '../../types/document-email';
@@ -107,7 +107,39 @@ export const EnvelopeEditorProvider = ({
 
   const [_searchParams, setSearchParams] = useSearchParams();
 
-  const [envelope, _setEnvelope] = useState(initialEnvelope);
+  /**
+   * The envelope is kept in a ref-backed external store instead of useState so
+   * that async consumers (debounced autosave callbacks, flushAutosave, resetForms)
+   * can synchronously read the latest value via `getEnvelope`.
+   *
+   * React subscribes to the store through useSyncExternalStore, keeping renders in
+   * sync without maintaining a separate copy of the state.
+   */
+  const envelopeStoreRef = useRef(initialEnvelope);
+  const envelopeStoreSubscribersRef = useRef(new Set<() => void>());
+
+  const subscribeToEnvelopeStore = useCallback((onStoreChange: () => void) => {
+    envelopeStoreSubscribersRef.current.add(onStoreChange);
+
+    return () => {
+      envelopeStoreSubscribersRef.current.delete(onStoreChange);
+    };
+  }, []);
+
+  const getEnvelope = useCallback(() => envelopeStoreRef.current, []);
+
+  const setEnvelope = useCallback((action: React.SetStateAction<TEditorEnvelope>) => {
+    const next = typeof action === 'function' ? action(envelopeStoreRef.current) : action;
+
+    envelopeStoreRef.current = next;
+
+    for (const onStoreChange of envelopeStoreSubscribersRef.current) {
+      onStoreChange();
+    }
+  }, []);
+
+  const envelope = useSyncExternalStore(subscribeToEnvelopeStore, getEnvelope, getEnvelope);
+
   const [autosaveError, setAutosaveError] = useState<boolean>(false);
 
   const isCscMode = IS_INSTANCE_CSC_MODE();
@@ -135,8 +167,6 @@ export const EnvelopeEditorProvider = ({
     };
   }, [isCscMode, providedEditorConfig]);
 
-  const envelopeRef = useRef(initialEnvelope);
-
   const externalFlushCallbacksRef = useRef<Map<string, () => Promise<void>>>(new Map());
   const pendingMutationsRef = useRef<Set<Promise<unknown>>>(new Set());
 
@@ -156,14 +186,6 @@ export const EnvelopeEditorProvider = ({
     });
   }, []);
 
-  const setEnvelope: typeof _setEnvelope = (action) => {
-    _setEnvelope((prev) => {
-      const next = typeof action === 'function' ? action(prev) : action;
-      envelopeRef.current = next;
-      return next;
-    });
-  };
-
   const isEmbedded = editorConfig.embedded !== undefined;
 
   const editorFields = useEditorFields({
@@ -192,16 +214,18 @@ export const EnvelopeEditorProvider = ({
     try {
       let recipients: TEditorEnvelope['recipients'] = [];
 
+      const currentEnvelope = getEnvelope();
+
       if (!isEmbedded) {
         const response = await setRecipientsMutation.mutateAsync({
-          envelopeId: envelope.id,
-          envelopeType: envelope.type,
+          envelopeId: currentEnvelope.id,
+          envelopeType: currentEnvelope.type,
           recipients: localRecipients,
         });
 
         recipients = response.data;
       } else {
-        recipients = mapLocalRecipientsToRecipients({ envelope, localRecipients });
+        recipients = mapLocalRecipientsToRecipients({ envelope: currentEnvelope, localRecipients });
       }
 
       setEnvelope((prev) => ({
@@ -211,9 +235,7 @@ export const EnvelopeEditorProvider = ({
       }));
 
       // Reset the local fields to ensure deleted recipient fields are removed.
-      editorFields.resetForm(
-        envelope.fields.filter((field) => recipients.some((recipient) => recipient.id === field.recipientId)),
-      );
+      editorFields.resetForm(getEnvelope().fields);
 
       setAutosaveError(false);
     } catch (err) {
@@ -248,16 +270,18 @@ export const EnvelopeEditorProvider = ({
     try {
       let fields: TSetEnvelopeFieldsResponse['data'] = [];
 
+      const currentEnvelope = getEnvelope();
+
       if (!isEmbedded) {
         const response = await setFieldsMutation.mutateAsync({
-          envelopeId: envelope.id,
-          envelopeType: envelope.type,
+          envelopeId: currentEnvelope.id,
+          envelopeType: currentEnvelope.type,
           fields: localFields,
         });
 
         fields = response.data;
       } else {
-        fields = mapLocalFieldsToFields({ envelope, localFields });
+        fields = mapLocalFieldsToFields({ envelope: currentEnvelope, localFields });
       }
 
       setEnvelope((prev) => ({
@@ -309,7 +333,7 @@ export const EnvelopeEditorProvider = ({
     try {
       const response = !isEmbedded
         ? await updateEnvelopeMutation.mutateAsync({
-            envelopeId: envelope.id,
+            envelopeId: getEnvelope().id,
             data,
             meta,
           })
@@ -467,12 +491,14 @@ export const EnvelopeEditorProvider = ({
   };
 
   const resetForms = () => {
+    const currentEnvelope = getEnvelope();
+
     editorRecipients.resetForm({
-      recipients: envelopeRef.current.recipients,
-      documentMeta: envelopeRef.current.documentMeta,
+      recipients: currentEnvelope.recipients,
+      documentMeta: currentEnvelope.documentMeta,
     });
 
-    editorFields.resetForm(envelopeRef.current.fields);
+    editorFields.resetForm(currentEnvelope.fields);
   };
 
   const flushAutosave = async (): Promise<TEditorEnvelope> => {
@@ -488,7 +514,7 @@ export const EnvelopeEditorProvider = ({
       await Promise.allSettled(Array.from(pendingMutationsRef.current));
     }
 
-    return envelopeRef.current;
+    return getEnvelope();
   };
 
   return (

packages/lib/errors/app-error.ts

@@ -43,6 +43,20 @@ export enum AppErrorCode {
    */
   RECIPIENT_ALREADY_SIGNED = 'RECIPIENT_ALREADY_SIGNED',
 
+  /**
+   * A completion request was made for a recipient that still has required
+   * fields which have not been inserted. Usually indicates the client's field
+   * state is out of sync with the server (e.g. a field insert failed to
+   * persist before submission).
+   */
+  RECIPIENT_HAS_UNSIGNED_FIELDS = 'RECIPIENT_HAS_UNSIGNED_FIELDS',
+
+  /**
+   * A completion request was made by a recipient in a sequential signing flow
+   * before the preceding recipients have signed.
+   */
+  RECIPIENT_OUT_OF_TURN = 'RECIPIENT_OUT_OF_TURN',
+
   /**
    * A signer recipient does not have a signature field assigned. Thrown when
    * distributing an envelope or using a direct template where at least one
@@ -99,6 +113,8 @@ export const genericErrorCodeToTrpcErrorCodeMap: Record<string, { code: string;
   [AppErrorCode.ENVELOPE_LEGACY]: { code: 'BAD_REQUEST', status: 400 },
   [AppErrorCode.ENVELOPE_TSP_LOCKED]: { code: 'BAD_REQUEST', status: 400 },
   [AppErrorCode.MISSING_SIGNATURE_FIELD]: { code: 'BAD_REQUEST', status: 400 },
+  [AppErrorCode.RECIPIENT_HAS_UNSIGNED_FIELDS]: { code: 'BAD_REQUEST', status: 400 },
+  [AppErrorCode.RECIPIENT_OUT_OF_TURN]: { code: 'BAD_REQUEST', status: 400 },
   [AppErrorCode.CSC_INSTANCE_MODE_MISMATCH]: { code: 'BAD_REQUEST', status: 400 },
   [AppErrorCode.CSC_UNLICENSED]: { code: 'FORBIDDEN', status: 403 },
   [AppErrorCode.CSC_PROVIDER_INFO_FAILED]: { code: 'INTERNAL_SERVER_ERROR', status: 500 },
@@ -307,6 +323,8 @@ export class AppError extends Error {
         AppErrorCode.ENVELOPE_LEGACY,
         AppErrorCode.ENVELOPE_TSP_LOCKED,
         AppErrorCode.MISSING_SIGNATURE_FIELD,
+        AppErrorCode.RECIPIENT_HAS_UNSIGNED_FIELDS,
+        AppErrorCode.RECIPIENT_OUT_OF_TURN,
         AppErrorCode.CSC_INSTANCE_MODE_MISMATCH,
         AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY,
         AppErrorCode.CSC_CERT_INVALID,

packages/lib/package.json

@@ -15,7 +15,7 @@
     "clean": "rimraf node_modules"
   },
   "dependencies": {
-    "@ai-sdk/google-vertex": "3.0.81",
+    "@ai-sdk/google-vertex": "5.0.48",
     "@aws-sdk/client-s3": "^3.998.0",
     "@aws-sdk/client-sesv2": "^3.998.0",
     "@aws-sdk/cloudfront-signer": "^3.998.0",
@@ -29,6 +29,7 @@
     "@documenso/email": "*",
     "@documenso/prisma": "*",
     "@documenso/signing": "*",
+    "@documenso/skia-canvas": "^3.0.8-documenso.3",
     "@lingui/core": "^5.6.0",
     "@lingui/macro": "^5.6.0",
     "@lingui/react": "^5.6.0",
@@ -42,7 +43,7 @@
     "@sindresorhus/slugify": "^3.0.0",
     "@team-plain/typescript-sdk": "^5.11.0",
     "@vvo/tzdb": "^6.196.0",
-    "ai": "^5.0.104",
+    "ai": "^7.0.58",
     "bullmq": "^5.71.1",
     "colord": "^2.9.3",
     "csv-parse": "^6.1.0",
@@ -64,10 +65,9 @@
     "postcss-selector-parser": "^7.1.4",
     "posthog-js": "^1.297.2",
     "posthog-node": "4.18.0",
-    "react": "^18",
+    "react": "^19.2.7",
     "remeda": "^2.32.0",
-    "sharp": "0.34.5",
-    "skia-canvas": "^3.0.8",
+    "sharp": "0.35.3",
     "stripe": "^12.18.0",
     "ts-pattern": "^5.9.0",
     "zod": "^3.25.76"

packages/lib/server-only/ai/pdf-to-images.ts

@@ -1,6 +1,6 @@
+import { Canvas, Image, Path2D } from '@documenso/skia-canvas';
 import pMap from 'p-map';
 import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs';
-import { Canvas, Image, Path2D } from 'skia-canvas';
 
 // @ts-expect-error napi-rs/canvas satisfies the requirements
 globalThis.Path2D = Path2D;

packages/lib/server-only/document/complete-document-with-token.ts

@@ -59,7 +59,7 @@ export const completeDocumentWithToken = async ({
   nextSigner,
   recipientOverride,
 }: CompleteDocumentWithTokenOptions) => {
-  const envelope = await prisma.envelope.findFirstOrThrow({
+  const envelope = await prisma.envelope.findFirst({
     where: {
       ...unsafeBuildEnvelopeIdQuery(id, EnvelopeType.DOCUMENT),
       recipients: {
@@ -78,10 +78,23 @@ export const completeDocumentWithToken = async ({
     },
   });
 
+  // The most common cause is a stale signing page: the document was deleted,
+  // or the recipient was removed, after the link was opened. Surface a
+  // NOT_FOUND instead of leaking a Prisma P2025 as a 500.
+  if (!envelope) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Document not found for the provided signing token',
+      statusCode: 404,
+    });
+  }
+
   const legacyDocumentId = mapSecondaryIdToDocumentId(envelope.secondaryId);
 
   if (envelope.recipients.length === 0) {
-    throw new Error(`Document ${envelope.id} has no recipient with token ${token}`);
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: `Document ${envelope.id} has no recipient with the provided token`,
+      statusCode: 404,
+    });
   }
 
   const [recipient] = envelope.recipients;
@@ -98,7 +111,19 @@ export const completeDocumentWithToken = async ({
   }
 
   if (envelope.status !== DocumentStatus.PENDING) {
-    throw new Error(`Document ${envelope.id} must be pending`);
+    const envelopeStatusErrorCode: Record<DocumentStatus, AppErrorCode> = {
+      [DocumentStatus.DRAFT]: AppErrorCode.ENVELOPE_DRAFT,
+      [DocumentStatus.COMPLETED]: AppErrorCode.ENVELOPE_COMPLETED,
+      [DocumentStatus.REJECTED]: AppErrorCode.ENVELOPE_REJECTED,
+      [DocumentStatus.CANCELLED]: AppErrorCode.ENVELOPE_CANCELLED,
+      // Unreachable: guarded by the status check above.
+      [DocumentStatus.PENDING]: AppErrorCode.INVALID_REQUEST,
+    };
+
+    throw new AppError(envelopeStatusErrorCode[envelope.status], {
+      message: `Document ${envelope.id} must be pending to be completed, found ${envelope.status}`,
+      statusCode: 400,
+    });
   }
 
   assertRecipientNotExpired(recipient);
@@ -116,7 +141,10 @@ export const completeDocumentWithToken = async ({
     });
 
     if (!isRecipientsTurn) {
-      throw new Error(`Recipient ${recipient.id} attempted to complete the document before it was their turn`);
+      throw new AppError(AppErrorCode.RECIPIENT_OUT_OF_TURN, {
+        message: `Recipient ${recipient.id} attempted to complete the document before it was their turn`,
+        statusCode: 400,
+      });
     }
   }
 
@@ -279,7 +307,10 @@ export const completeDocumentWithToken = async ({
   }
 
   if (fieldsContainUnsignedRequiredField(fields)) {
-    throw new Error(`Recipient ${recipient.id} has unsigned fields`);
+    throw new AppError(AppErrorCode.RECIPIENT_HAS_UNSIGNED_FIELDS, {
+      message: `Recipient ${recipient.id} has unsigned fields`,
+      statusCode: 400,
+    });
   }
 
   await prisma.$transaction(async (tx) => {

packages/lib/server-only/konva/skia-backend.ts

@@ -2,8 +2,9 @@
  * !: This is a workaround to fix the memory leak in the skia-canvas library.
  * !: Internals are ported from the original `konva/skia-backend.js` file.
  */
+
+import { Canvas, DOMMatrix, Image, Path2D } from '@documenso/skia-canvas';
 import { Konva } from 'konva/lib/_CoreInternals';
-import { Canvas, DOMMatrix, Image, Path2D } from 'skia-canvas';
 
 // @ts-expect-error skia-canvas satisfies the requirements
 global.DOMMatrix = DOMMatrix;
@@ -37,6 +38,6 @@ Konva.Util.createImageElement = () => {
   return node as unknown as HTMLImageElement;
 };
 
-Konva._renderBackend = 'skia-canvas';
+Konva._renderBackend = '@documenso/skia-canvas';
 
 export default Konva;

packages/lib/server-only/pdf/helpers.ts

@@ -1,8 +1,8 @@
 import path from 'node:path';
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { FontLibrary } from '@documenso/skia-canvas';
 import type { Recipient } from '@prisma/client';
 import { FieldType } from '@prisma/client';
-import { FontLibrary } from 'skia-canvas';
 import { match } from 'ts-pattern';
 
 /**

packages/lib/server-only/pdf/insert-field-in-pdf-v2.ts

@@ -2,8 +2,8 @@
 import '../konva/skia-backend';
 
 import type { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
+import type { Canvas } from '@documenso/skia-canvas';
 import Konva from 'konva';
-import type { Canvas } from 'skia-canvas';
 
 import { renderField } from '../../universal/field-renderer/render-field';
 import { ensureFontLibrary } from './helpers';

packages/lib/server-only/pdf/render-audit-logs.ts

@@ -1,14 +1,16 @@
+// sort-imports-ignore
+import '../konva/skia-backend';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Canvas } from '@documenso/skia-canvas';
+import { Image as SkiaImage } from '@documenso/skia-canvas';
 import type { I18n } from '@lingui/core';
 import { msg } from '@lingui/core/macro';
 import type { DocumentMeta, Envelope, RecipientRole } from '@prisma/client';
 import Konva from 'konva';
-import 'konva/skia-backend';
-import fs from 'node:fs';
-import path from 'node:path';
 import type { DateTimeFormatOptions } from 'luxon';
 import { DateTime } from 'luxon';
-import type { Canvas } from 'skia-canvas';
-import { Image as SkiaImage } from 'skia-canvas';
 import { match, P } from 'ts-pattern';
 import { UAParser } from 'ua-parser-js';
 

packages/lib/server-only/pdf/render-certificate.ts

@@ -1,14 +1,16 @@
+// sort-imports-ignore
+import '../konva/skia-backend';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Canvas } from '@documenso/skia-canvas';
+import { Image as SkiaImage } from '@documenso/skia-canvas';
 import type { I18n } from '@lingui/core';
 import { msg } from '@lingui/core/macro';
 import type { Field, RecipientRole, Signature } from '@prisma/client';
 import { SigningStatus } from '@prisma/client';
 import Konva from 'konva';
-import 'konva/skia-backend';
-import fs from 'node:fs';
-import path from 'node:path';
 import { DateTime } from 'luxon';
-import type { Canvas } from 'skia-canvas';
-import { Image as SkiaImage } from 'skia-canvas';
 import { UAParser } from 'ua-parser-js';
 import { renderSVG } from 'uqr';
 

packages/lib/universal/field-renderer/render-signature-field.ts

@@ -14,7 +14,7 @@ let SkiaImage: any;
 
 void (async () => {
   if (typeof window === 'undefined') {
-    const mod = await import('skia-canvas');
+    const mod = await import('@documenso/skia-canvas');
     SkiaImage = mod.Image;
   }
 })();

packages/trpc/package.json

@@ -12,9 +12,9 @@
     "@documenso/prisma": "*",
     "@simplewebauthn/server": "^13.2.2",
     "@tanstack/react-query": "5.90.10",
-    "@trpc/client": "11.8.1",
-    "@trpc/react-query": "11.8.1",
-    "@trpc/server": "11.8.1",
+    "@trpc/client": "11.17.0",
+    "@trpc/react-query": "11.17.0",
+    "@trpc/server": "11.17.0",
     "@ts-rest/core": "^3.52.1",
     "formidable": "^3.5.4",
     "luxon": "^3.7.2",

packages/trpc/server/envelope-router/cancel-envelope.types.ts

@@ -8,13 +8,14 @@ export const cancelEnvelopeMeta: TrpcRouteMeta = {
     method: 'POST',
     path: '/envelope/cancel',
     summary: 'Cancel envelope',
+    description: 'Cancel a pending envelope',
     tags: ['Envelope'],
   },
 };
 
 export const ZCancelEnvelopeRequestSchema = z.object({
-  envelopeId: z.string(),
-  reason: z.string().optional(),
+  envelopeId: z.string().describe('The ID of the envelope to cancel.'),
+  reason: z.string().describe('The reason for cancelling the envelope.').optional(),
 });
 
 export const ZCancelEnvelopeResponseSchema = ZSuccessResponseSchema;

packages/trpc/server/envelope-router/delete-envelope.types.ts

@@ -8,12 +8,13 @@ export const deleteEnvelopeMeta: TrpcRouteMeta = {
     method: 'POST',
     path: '/envelope/delete',
     summary: 'Delete envelope',
+    description: 'Delete an envelope',
     tags: ['Envelope'],
   },
 };
 
 export const ZDeleteEnvelopeRequestSchema = z.object({
-  envelopeId: z.string(),
+  envelopeId: z.string().describe('The ID of the envelope to delete.'),
 });
 
 export const ZDeleteEnvelopeResponseSchema = ZSuccessResponseSchema;

packages/trpc/server/envelope-router/update-envelope.types.ts

@@ -12,24 +12,32 @@ export const updateEnvelopeMeta: TrpcRouteMeta = {
     method: 'POST',
     path: '/envelope/update',
     summary: 'Update envelope',
+    description: 'Update envelope properties and settings',
     tags: ['Envelope'],
   },
 };
 
 export const ZUpdateEnvelopeRequestSchema = z.object({
-  envelopeId: z.string(),
+  envelopeId: z.string().describe('The ID of the envelope to update.'),
   data: z
     .object({
       title: ZDocumentTitleSchema.optional(),
       externalId: ZDocumentExternalIdSchema.nullish(),
       visibility: ZDocumentVisibilitySchema.optional(),
-      globalAccessAuth: z.array(ZDocumentAccessAuthTypesSchema).optional(),
-      globalActionAuth: z.array(ZDocumentActionAuthTypesSchema).optional(),
-      folderId: z.string().nullish(),
-      templateType: z.nativeEnum(TemplateType).optional(),
-    })
+      globalAccessAuth: z
+        .array(ZDocumentAccessAuthTypesSchema)
+        .describe('The authentication methods required to access the envelope.')
         .optional(),
-  meta: ZDocumentMetaUpdateSchema.optional(),
+      globalActionAuth: z
+        .array(ZDocumentActionAuthTypesSchema)
+        .describe('The authentication methods required to sign the envelope.')
+        .optional(),
+      folderId: z.string().describe('The ID of the folder containing the envelope.').nullish(),
+      templateType: z.nativeEnum(TemplateType).describe('The template type.').optional(),
+    })
+    .describe('The envelope properties to update.')
+    .optional(),
+  meta: ZDocumentMetaUpdateSchema.describe('The email and signing settings to update.').optional(),
 });
 
 export const ZUpdateEnvelopeResponseSchema = ZEnvelopeLiteSchema;

packages/trpc/server/recipient-router/router.ts

@@ -603,7 +603,7 @@ export const recipientRouter = router({
         // can't complete via this route — they go through the CSC sync sign
         // flow (`enterprise.csc.signEnvelope`). This route returns the redirect URL
         // for the credential-scope OAuth round-trip.
-        const envelope = await prisma.envelope.findFirstOrThrow({
+        const envelope = await prisma.envelope.findFirst({
           where: {
             ...unsafeBuildEnvelopeIdQuery({ type: 'documentId', id: documentId }, EnvelopeType.DOCUMENT),
             recipients: { some: { token } },
@@ -611,6 +611,16 @@ export const recipientRouter = router({
           select: { signatureLevel: true, internalVersion: true },
         });
 
+        // The most common cause is a stale signing page: the document was
+        // deleted, or the recipient was removed, after the link was opened.
+        // Surface a NOT_FOUND instead of leaking a Prisma P2025 as a 500.
+        if (!envelope) {
+          throw new AppError(AppErrorCode.NOT_FOUND, {
+            message: 'Document not found for the provided signing token',
+            statusCode: 404,
+          });
+        }
+
         if (isTspEnvelope(envelope)) {
           return await prepareCscRecipientSigning({
             recipientToken: token,

packages/ui/components/document/envelope-recipient-field-tooltip.tsx

@@ -2,16 +2,27 @@ import { getBoundingClientRect } from '@documenso/lib/client-only/get-bounding-c
 import { PDF_VIEWER_PAGE_SELECTOR } from '@documenso/lib/constants/pdf-viewer';
 import { Trans, useLingui } from '@lingui/react/macro';
 import type { Field, Recipient } from '@prisma/client';
-import { SigningStatus } from '@prisma/client';
-import { ClockIcon, EyeOffIcon, LockIcon } from 'lucide-react';
-import { useCallback, useEffect, useState } from 'react';
+import { FieldType, SigningStatus } from '@prisma/client';
+import {
+  CalendarDaysIcon,
+  CheckSquareIcon,
+  ChevronDownIcon,
+  ContactIcon,
+  DiscIcon,
+  EyeOffIcon,
+  HashIcon,
+  LockIcon,
+  MailIcon,
+  TypeIcon,
+  UserIcon,
+} from 'lucide-react';
+import { type ElementType, useCallback, useEffect, useState } from 'react';
 
 import { isTemplateRecipientEmailPlaceholder } from '../../../lib/constants/template';
 import { extractInitials } from '../../../lib/utils/recipient-formatter';
 import { SignatureIcon } from '../../icons/signature';
 import { cn } from '../../lib/utils';
 import { Avatar, AvatarFallback } from '../../primitives/avatar';
-import { Badge } from '../../primitives/badge';
 import { FRIENDLY_FIELD_TYPE } from '../../primitives/document-flow/types';
 import { PopoverHover } from '../../primitives/popover';
 
@@ -27,16 +38,18 @@ interface EnvelopeRecipientFieldTooltipProps {
   showRecipientColors?: boolean;
 }
 
-const getRecipientDisplayText = (recipient: { name: string; email: string }) => {
-  if (recipient.name && !isTemplateRecipientEmailPlaceholder(recipient.email)) {
-    return `${recipient.name} (${recipient.email})`;
-  }
-
-  if (recipient.name && isTemplateRecipientEmailPlaceholder(recipient.email)) {
-    return recipient.name;
-  }
-
-  return recipient.email;
+const FIELD_TYPE_ICONS: Record<FieldType, ElementType> = {
+  [FieldType.SIGNATURE]: SignatureIcon,
+  [FieldType.FREE_SIGNATURE]: SignatureIcon,
+  [FieldType.INITIALS]: ContactIcon,
+  [FieldType.TEXT]: TypeIcon,
+  [FieldType.DATE]: CalendarDaysIcon,
+  [FieldType.EMAIL]: MailIcon,
+  [FieldType.NAME]: UserIcon,
+  [FieldType.NUMBER]: HashIcon,
+  [FieldType.RADIO]: DiscIcon,
+  [FieldType.CHECKBOX]: CheckSquareIcon,
+  [FieldType.DROPDOWN]: ChevronDownIcon,
 };
 
 /**
@@ -50,6 +63,8 @@ export function EnvelopeRecipientFieldTooltip({
 }: EnvelopeRecipientFieldTooltipProps) {
   const { t } = useLingui();
 
+  const FieldIcon = FIELD_TYPE_ICONS[field.type];
+
   const [hideField, setHideField] = useState<boolean>(!showRecipientTooltip);
 
   const [coords, setCoords] = useState({
@@ -138,54 +153,64 @@ export function EnvelopeRecipientFieldTooltip({
           </Avatar>
         }
         contentProps={{
-          className: 'relative flex mb-4 w-fit flex-col p-4 text-sm',
+          className: 'flex w-64 flex-col overflow-hidden p-0 text-sm',
+          sideOffset: 20,
+          onOpenAutoFocus: (event) => event.preventDefault(),
         }}
       >
+        <div className="flex items-center gap-2 p-3">
+          <FieldIcon className="h-4 w-4 shrink-0 text-muted-foreground" />
+
+          <p className="min-w-0 flex-1 truncate font-medium">
+            <Trans>{t(FRIENDLY_FIELD_TYPE[field.type])} field</Trans>
+          </p>
+
           {showFieldStatus && (
-          <Badge
-            className="mx-auto mb-1 py-0.5"
-            variant={
-              field?.fieldMeta?.readOnly
-                ? 'neutral'
-                : field.recipient.signingStatus === SigningStatus.SIGNED
-                  ? 'default'
-                  : 'secondary'
-            }
-          >
+            <div className="flex shrink-0 items-center gap-1.5 text-xs">
               {field?.fieldMeta?.readOnly ? (
                 <>
-                <LockIcon className="mr-1 h-3 w-3" />
+                  <LockIcon className="h-3 w-3 text-muted-foreground" />
+                  <span className="text-muted-foreground">
                     <Trans>Read Only</Trans>
+                  </span>
                 </>
               ) : field.recipient.signingStatus === SigningStatus.SIGNED ? (
                 <>
-                <SignatureIcon className="mr-1 h-3 w-3" />
+                  <span className="h-1.5 w-1.5 rounded-full bg-green-500" />
+                  <span className="text-green-600 dark:text-green-400">
                     <Trans>Signed</Trans>
+                  </span>
                 </>
               ) : (
                 <>
-                <ClockIcon className="mr-1 h-3 w-3" />
+                  <span className="h-1.5 w-1.5 rounded-full bg-amber-400" />
+                  <span className="text-amber-600 dark:text-amber-400">
                     <Trans>Pending</Trans>
+                  </span>
                 </>
               )}
-          </Badge>
+            </div>
           )}
+        </div>
 
-        <p className="text-center font-semibold">
-          <span>
-            <Trans>{t(FRIENDLY_FIELD_TYPE[field.type])} field</Trans>
-          </span>
-        </p>
+        <div className="flex items-center gap-3 border-border/50 border-t bg-muted/50 px-3 py-2.5">
+          <div className="min-w-0 flex-1">
+            <p className="truncate font-medium text-xs">{field.recipient.name || field.recipient.email}</p>
 
-        <p className="mt-1 text-center text-muted-foreground text-xs">{getRecipientDisplayText(field.recipient)}</p>
+            {!isTemplateRecipientEmailPlaceholder(field.recipient.email) && field.recipient.name && (
+              <p className="truncate text-muted-foreground text-xs">{field.recipient.email}</p>
+            )}
+          </div>
 
           <button
-          className="absolute top-0 right-0 my-1 p-2 focus:outline-none focus-visible:ring-0"
+            type="button"
+            className="-m-1 shrink-0 rounded-sm p-1 text-muted-foreground hover:bg-background hover:text-foreground"
             onClick={() => setHideField(true)}
-          title="Hide field"
+            title={t`Hide field`}
           >
-          <EyeOffIcon className="h-3 w-3" />
+            <EyeOffIcon className="h-3.5 w-3.5" />
           </button>
+        </div>
       </PopoverHover>
     </div>
   );

packages/ui/components/signing-card.tsx

@@ -35,7 +35,7 @@ export const SigningCard3D = ({ className, name, signature, signingCelebrationIm
 
   const [trackMouse, setTrackMouse] = useState(false);
 
-  const timeoutRef = useRef<number | undefined>();
+  const timeoutRef = useRef<number | undefined>(undefined);
 
   const cardX = useMotionValue(0);
   const cardY = useMotionValue(0);

packages/ui/package.json

@@ -18,59 +18,32 @@
     "@documenso/tailwind-config": "*",
     "@documenso/tsconfig": "*",
     "@types/luxon": "^3.7.1",
-    "@types/react": "18.3.27",
-    "@types/react-dom": "^18",
-    "react": "^18",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
     "typescript": "5.6.2"
   },
   "dependencies": {
     "@documenso/lib": "*",
-    "@hello-pangea/dnd": "^16.6.0",
+    "@hello-pangea/dnd": "^18.0.1",
     "@hookform/resolvers": "^3",
     "@lingui/macro": "^5.6.0",
     "@lingui/react": "^5.6.0",
-    "@radix-ui/react-accordion": "^1.2.12",
-    "@radix-ui/react-alert-dialog": "^1.1.15",
-    "@radix-ui/react-aspect-ratio": "^1.1.8",
-    "@radix-ui/react-avatar": "^1.1.11",
-    "@radix-ui/react-checkbox": "^1.3.3",
-    "@radix-ui/react-collapsible": "^1.1.12",
-    "@radix-ui/react-context-menu": "^2.2.16",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-hover-card": "^1.1.15",
-    "@radix-ui/react-label": "^2.1.8",
-    "@radix-ui/react-menubar": "^1.1.16",
-    "@radix-ui/react-navigation-menu": "^1.2.14",
-    "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-progress": "^1.1.8",
-    "@radix-ui/react-radio-group": "^1.3.8",
-    "@radix-ui/react-scroll-area": "^1.2.10",
-    "@radix-ui/react-select": "^2.2.6",
-    "@radix-ui/react-separator": "^1.1.8",
-    "@radix-ui/react-slider": "^1.3.6",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-toast": "^1.2.15",
-    "@radix-ui/react-toggle": "^1.1.10",
-    "@radix-ui/react-toggle-group": "^1.1.11",
-    "@radix-ui/react-tooltip": "^1.2.8",
     "@scure/base": "^1.2.6",
     "@tanstack/react-table": "^8.21.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^1.2.1",
-    "cmdk": "^0.2.1",
+    "cmdk": "^1.1.1",
     "colord": "^2.9.3",
     "framer-motion": "^12.43.0",
     "lucide-react": "^0.554.0",
     "luxon": "^3.7.2",
     "pdfjs-dist": "5.4.296",
     "perfect-freehand": "^1.2.2",
-    "react": "^18",
+    "react": "^19.2.7",
     "react-colorful": "^5.6.1",
     "react-day-picker": "^8.10.1",
-    "react-dom": "^18",
+    "react-dom": "^19.2.7",
     "react-hook-form": "^7.66.1",
     "react-rnd": "^10.5.2",
     "remeda": "^2.32.0",

packages/ui/primitives/command.tsx

@@ -145,7 +145,9 @@ const CommandItem = React.forwardRef<
   <CommandPrimitive.Item
     ref={ref}
     className={cn(
-      'relative flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none hover:bg-accent hover:text-accent-foreground aria-selected:bg-accent aria-selected:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      // cmdk 1.x always renders data-disabled="true|false", so the variant must
+      // check the value (bare data-[disabled] matches attribute presence).
+      'relative flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none hover:bg-accent hover:text-accent-foreground aria-selected:bg-accent aria-selected:text-accent-foreground data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50',
       className,
     )}
     {...props}

packages/ui/primitives/document-flow/field-content.tsx

@@ -103,15 +103,10 @@ export const FieldContent = ({ field, documentMeta }: FieldIconProps) => {
   ) {
     return (
       <div className="flex flex-col gap-y-2 py-0.5">
-        <RadioGroup className="gap-y-1">
+        <RadioGroup value={field.customText ?? ''} className="gap-y-1">
           {field.fieldMeta.values.map((item, index) => (
             <div key={index} className="flex items-center">
-              <RadioGroupItem
-                className="pointer-events-none h-3 w-3"
-                value={item.value}
-                id={`option-${index}`}
-                checked={item.value === field.customText}
-              />
+              <RadioGroupItem className="pointer-events-none h-3 w-3" value={item.value} id={`option-${index}`} />
               {item.value && (
                 <Label htmlFor={`option-${index}`} className="ml-1.5 font-normal text-foreground text-xs">
                   {item.value}

packages/ui/primitives/recipient-role-icons.tsx

@@ -1,5 +1,6 @@
 import type { RecipientRole } from '@prisma/client';
 import { BadgeCheck, Copy, Eye, PencilLine, User } from 'lucide-react';
+import type { JSX } from 'react';
 
 export const ROLE_ICONS: Record<RecipientRole, JSX.Element> = {
   SIGNER: <PencilLine className="h-4 w-4" />,

packages/ui/primitives/signature-pad/signature-pad-draw.tsx

@@ -13,7 +13,7 @@ import { getSvgPathFromStroke } from './helper';
 import { Point } from './point';
 import { SignaturePadColorPicker } from './signature-pad-color-picker';
 
-const checkSignatureValidity = (element: RefObject<HTMLCanvasElement>) => {
+const checkSignatureValidity = (element: RefObject<HTMLCanvasElement | null>) => {
   if (!element.current) {
     return false;
   }

scripts/create-justification.ts

@@ -1,73 +0,0 @@
-#!/usr/bin/env node
-import { mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
-
-import { generateId } from './utils/generate-id';
-
-const JUSTIFICATIONS_DIR = join(process.cwd(), '.agents', 'justifications');
-
-const main = () => {
-  const args = process.argv.slice(2);
-
-  if (args.length === 0) {
-    console.error('Usage: npx tsx scripts/create-justification.ts "file-slug" [content]');
-    console.error('  or:   npx tsx scripts/create-justification.ts "file-slug" << HEREDOC');
-    process.exit(1);
-  }
-
-  const slug = args[0];
-  let content = '';
-
-  // Check if content is provided as second argument
-  if (args.length > 1) {
-    content = args.slice(1).join(' ');
-  } else {
-    // Read from stdin (heredoc)
-    try {
-      const stdin = readFileSync(0, 'utf-8');
-      content = stdin.trim();
-    } catch (error) {
-      console.error('Error reading from stdin:', error);
-      process.exit(1);
-    }
-  }
-
-  if (!content) {
-    console.error('Error: No content provided');
-    process.exit(1);
-  }
-
-  // Generate unique ID
-  const id = generateId();
-  const filename = `${id}-${slug}.md`;
-  const filepath = join(JUSTIFICATIONS_DIR, filename);
-
-  // Format title from slug (kebab-case to Title Case)
-  const title = slug
-    .split('-')
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ');
-
-  // Get current date in ISO format
-  const date = new Date().toISOString().split('T')[0];
-
-  // Create frontmatter
-  const frontmatter = `---
-date: ${date}
-title: ${title}
----
-
-`;
-
-  // Ensure directory exists
-  mkdirSync(JUSTIFICATIONS_DIR, { recursive: true });
-
-  // Write file with frontmatter
-  writeFileSync(filepath, frontmatter + content, 'utf-8');
-
-  console.log(`Created justification: ${filepath}`);
-  console.log(`ID: ${id}`);
-  console.log(`Filename: ${filename}`);
-};
-
-main();

scripts/create-plan.ts

@@ -1,73 +0,0 @@
-#!/usr/bin/env node
-import { mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
-
-import { generateId } from './utils/generate-id';
-
-const PLANS_DIR = join(process.cwd(), '.agents', 'plans');
-
-const main = () => {
-  const args = process.argv.slice(2);
-
-  if (args.length === 0) {
-    console.error('Usage: npx tsx scripts/create-plan.ts "file-slug" [content]');
-    console.error('  or:   npx tsx scripts/create-plan.ts "file-slug" << HEREDOC');
-    process.exit(1);
-  }
-
-  const slug = args[0];
-  let content = '';
-
-  // Check if content is provided as second argument
-  if (args.length > 1) {
-    content = args.slice(1).join(' ');
-  } else {
-    // Read from stdin (heredoc)
-    try {
-      const stdin = readFileSync(0, 'utf-8');
-      content = stdin.trim();
-    } catch (error) {
-      console.error('Error reading from stdin:', error);
-      process.exit(1);
-    }
-  }
-
-  if (!content) {
-    console.error('Error: No content provided');
-    process.exit(1);
-  }
-
-  // Generate unique ID
-  const id = generateId();
-  const filename = `${id}-${slug}.md`;
-  const filepath = join(PLANS_DIR, filename);
-
-  // Format title from slug (kebab-case to Title Case)
-  const title = slug
-    .split('-')
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ');
-
-  // Get current date in ISO format
-  const date = new Date().toISOString().split('T')[0];
-
-  // Create frontmatter
-  const frontmatter = `---
-date: ${date}
-title: ${title}
----
-
-`;
-
-  // Ensure directory exists
-  mkdirSync(PLANS_DIR, { recursive: true });
-
-  // Write file with frontmatter
-  writeFileSync(filepath, frontmatter + content, 'utf-8');
-
-  console.log(`Created plan: ${filepath}`);
-  console.log(`ID: ${id}`);
-  console.log(`Filename: ${filename}`);
-};
-
-main();

scripts/create-scratch.ts

@@ -1,73 +0,0 @@
-#!/usr/bin/env node
-import { mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
-
-import { generateId } from './utils/generate-id';
-
-const SCRATCHES_DIR = join(process.cwd(), '.agents', 'scratches');
-
-const main = () => {
-  const args = process.argv.slice(2);
-
-  if (args.length === 0) {
-    console.error('Usage: npx tsx scripts/create-scratch.ts "file-slug" [content]');
-    console.error('  or:   npx tsx scripts/create-scratch.ts "file-slug" << HEREDOC');
-    process.exit(1);
-  }
-
-  const slug = args[0];
-  let content = '';
-
-  // Check if content is provided as second argument
-  if (args.length > 1) {
-    content = args.slice(1).join(' ');
-  } else {
-    // Read from stdin (heredoc)
-    try {
-      const stdin = readFileSync(0, 'utf-8');
-      content = stdin.trim();
-    } catch (error) {
-      console.error('Error reading from stdin:', error);
-      process.exit(1);
-    }
-  }
-
-  if (!content) {
-    console.error('Error: No content provided');
-    process.exit(1);
-  }
-
-  // Generate unique ID
-  const id = generateId();
-  const filename = `${id}-${slug}.md`;
-  const filepath = join(SCRATCHES_DIR, filename);
-
-  // Format title from slug (kebab-case to Title Case)
-  const title = slug
-    .split('-')
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ');
-
-  // Get current date in ISO format
-  const date = new Date().toISOString().split('T')[0];
-
-  // Create frontmatter
-  const frontmatter = `---
-date: ${date}
-title: ${title}
----
-
-`;
-
-  // Ensure directory exists
-  mkdirSync(SCRATCHES_DIR, { recursive: true });
-
-  // Write file with frontmatter
-  writeFileSync(filepath, frontmatter + content, 'utf-8');
-
-  console.log(`Created scratch: ${filepath}`);
-  console.log(`ID: ${id}`);
-  console.log(`Filename: ${filename}`);
-};
-
-main();

scripts/utils/generate-id.ts

@@ -1,84 +0,0 @@
-/**
- * Generates a unique identifier using three simple words.
- * Falls back to unix timestamp if word generation fails.
- */
-export const generateId = (): string => {
-  const adjectives = [
-    'happy',
-    'bright',
-    'swift',
-    'calm',
-    'bold',
-    'clever',
-    'gentle',
-    'quick',
-    'sharp',
-    'warm',
-    'cool',
-    'fresh',
-    'solid',
-    'clear',
-    'sweet',
-    'wild',
-    'quiet',
-    'loud',
-    'smooth',
-  ];
-
-  const nouns = [
-    'moon',
-    'star',
-    'ocean',
-    'river',
-    'forest',
-    'mountain',
-    'cloud',
-    'wave',
-    'stone',
-    'flower',
-    'bird',
-    'wind',
-    'light',
-    'shadow',
-    'fire',
-    'earth',
-    'sky',
-    'tree',
-    'leaf',
-    'rock',
-  ];
-
-  const colors = [
-    'blue',
-    'red',
-    'green',
-    'yellow',
-    'purple',
-    'orange',
-    'pink',
-    'cyan',
-    'amber',
-    'emerald',
-    'violet',
-    'indigo',
-    'coral',
-    'teal',
-    'gold',
-    'silver',
-    'copper',
-    'bronze',
-    'ivory',
-    'jade',
-  ];
-
-  try {
-    const randomAdjective = adjectives[Math.floor(Math.random() * adjectives.length)];
-    const randomColor = colors[Math.floor(Math.random() * colors.length)];
-    const randomNoun = nouns[Math.floor(Math.random() * nouns.length)];
-
-    return `${randomAdjective}-${randomColor}-${randomNoun}`;
-  } catch {
-    // Fallback to unix timestamp if something goes wrong
-    return Date.now().toString();
-  }
-};