Skip to content

The Open Source DocuSign Alternative.

chore: add embed envelope docs (#2576)

David Nguyen58f0c98038fd
diff --git a/.agents/skills/create-documentation/SKILL.md b/.agents/skills/create-documentation/SKILL.md
new file mode 100644
index 000000000..0524ae691
--- /dev/null
+++ b/.agents/skills/create-documentation/SKILL.md
@@ -0,0 +1,337 @@
+---
+name: create-documentation
+description: Generate markdown documentation for a module or feature
+---
+
+You are creating proper markdown documentation for a feature or guide in the Documenso documentation site.
+
+**Read [WRITING_STYLE.md](../../../WRITING_STYLE.md) first** for tone, formatting conventions, and anti-patterns to avoid.
+
+## Your Task
+
+1. **Identify the scope** - Based on the conversation context, determine what feature or topic needs documentation. Ask the user if unclear.
+2. **Identify the audience** - Is this for Users, Developers, or Self-Hosters?
+3. **Read the source code** - Understand the feature, API, or configuration being documented.
+4. **Read existing docs** - Check `apps/docs/content/docs/` for documentation to update.
+5. **Write comprehensive documentation** - Create or update MDX docs following the patterns below.
+6. **Update navigation** - Add to the relevant `meta.json` if creating a new page.
+
+## Documentation Framework
+
+This project uses [Fumadocs](https://fumadocs.dev). All documentation lives in `apps/docs/content/docs/` as MDX files. The docs app is a Next.js app at `apps/docs/`.
+
+## Documentation Structure
+
+```
+apps/docs/content/docs/
+├── index.mdx # Landing page with audience navigation
+├── meta.json # Root navigation: guides + resources
+├── users/ # Application usage guides
+│ ├── meta.json # { "root": true, "pages": [...] }
+│ ├── getting-started/ # Account creation, first document
+│ ├── documents/ # Upload, recipients, fields, send
+│ │ └── advanced/ # AI detection, visibility, placeholders
+│ ├── templates/ # Create and use templates
+│ ├── organisations/ # Overview, members, groups, SSO, billing
+│ │ ├── single-sign-on/
+│ │ └── preferences/
+│ └── settings/ # Profile, security, API tokens
+├── developers/ # API and integration docs
+│ ├── meta.json # { "root": true, "pages": [...] }
+│ ├── getting-started/ # Authentication, first API call
+│ ├── api/ # Documents, recipients, fields, templates, teams
+│ ├── webhooks/ # Setup, events, verification
+│ ├── embedding/ # Authoring, direct links, CSS vars, SDKs
+│ │ └── sdks/ # React, Vue, Svelte, Solid, Preact, Angular
+│ ├── examples/ # Common workflows
+│ ├── local-development/ # Quickstart, manual, translations
+│ └── contributing/ # Contributing translations
+├── self-hosting/ # Self-hosting documentation
+│ ├── meta.json # { "root": true, "pages": [...] }
+│ ├── getting-started/ # Quick start, requirements, tips
+│ ├── deployment/ # Docker, docker-compose, Kubernetes, Railway
+│ ├── configuration/ # Environment, database, email, storage
+│ │ ├── signing-certificate/ # Local, Google Cloud HSM, timestamp
+│ │ └── advanced/ # OAuth providers, AI features
+│ └── maintenance/ # Upgrades, backups, troubleshooting
+├── concepts/ # Shared across audiences
+│ └── ... # Document lifecycle, field types, signing
+├── compliance/ # eSign, GDPR, standards, certifications
+└── policies/ # Terms, privacy, security, licenses
+```
+
+### Where to Put Documentation
+
+| Type | Location | When to use |
+| ------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| **User Guide** | `apps/docs/content/docs/users/<section>/` | UI workflows for using the Documenso web app |
+| **Developer Guide** | `apps/docs/content/docs/developers/<section>/` | API reference, SDK guides, webhooks, embedding |
+| **Self-Hosting** | `apps/docs/content/docs/self-hosting/<section>/` | Deployment, configuration, environment variables |
+| **Concept** | `apps/docs/content/docs/concepts/` | Cross-audience concepts (document lifecycle, etc.) |
+| **Compliance** | `apps/docs/content/docs/compliance/` | Legal and regulatory documentation |
+
+### Navigation (meta.json)
+
+Each directory has a `meta.json` controlling navigation order:
+
+```json
+{
+ "title": "Section Title",
+ "pages": ["getting-started", "documents", "templates"]
+}
+```
+
+Top-level audience sections use `"root": true`:
+
+```json
+{
+ "title": "Users",
+ "description": "Send and sign documents",
+ "root": true,
+ "pages": ["getting-started", "documents", "templates", "organisations", "settings"]
+}
+```
+
+Root `meta.json` uses `---Label---` for section dividers:
+
+```json
+{
+ "title": "Documentation",
+ "pages": [
+ "---Guides---",
+ "users",
+ "developers",
+ "self-hosting",
+ "---Resources---",
+ "concepts",
+ "compliance",
+ "policies"
+ ]
+}
+```
+
+## MDX File Format
+
+### Frontmatter
+
+Every page needs frontmatter:
+
+```yaml
+---
+title: Upload Documents
+description: Upload documents to Documenso to prepare them for signing. Covers supported formats, file size limits, and upload methods.
+---
+```
+
+### Fumadocs Components
+
+Import components at the top of the file (after frontmatter):
+
+```mdx
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+;
+```
+
+Callouts (use sparingly for warnings, beta features, security):
+
+```mdx
+<Callout type="info">Informational note about behavior.</Callout>
+
+<Callout type="warn">Warning about potential issues or breaking changes.</Callout>
+
+<Callout type="error">Critical warning about data loss or security.</Callout>
+```
+
+Steps (for sequential UI instructions):
+
+```mdx
+{/* prettier-ignore */}
+<Steps>
+ <Step>
+ ### Step title
+
+ Step description.
+
+ </Step>
+ <Step>
+ ### Next step
+
+ Next description.
+
+ </Step>
+</Steps>
+```
+
+Tabs (for multiple approaches or platforms):
+
+````mdx
+<Tabs items={['cURL', 'JavaScript', 'Python']}>
+ <Tab value="cURL">```bash curl -X POST ... ```</Tab>
+ <Tab value="JavaScript">```typescript const response = await fetch(...) ```</Tab>
+</Tabs>
+````
+
+## Page Structure by Audience
+
+### User Documentation
+
+```mdx
+---
+title: Feature Name
+description: Brief description for SEO and previews.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+
+## Limitations
+
+| Limitation | Value |
+| ----------------- | -------- |
+| Supported format | PDF only |
+| Maximum file size | 50MB |
+
+## How to Do the Thing
+
+{/* prettier-ignore */}
+<Steps>
+ <Step>
+ ### Navigate to the page
+
+ Open **Settings > Feature**.
+
+ </Step>
+ <Step>
+ ### Configure the setting
+
+ Fill in the required fields and click **Save**.
+
+ </Step>
+</Steps>
+
+---
+
+## See Also
+
+- [Related Guide](/docs/users/related)
+```
+
+### Developer Documentation
+
+````mdx
+---
+title: Documents API
+description: Create, manage, and send documents for signing via the API.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+<Callout type="warn">
+ This guide may not reflect the latest endpoints. For an always up-to-date reference, see the
+ [OpenAPI Reference](https://openapi.documenso.com).
+</Callout>
+
+## Overview
+
+Brief description of the resource and what you can do with it.
+
+## Resource Object
+
+| Property | Type | Description |
+| -------- | ------ | ----------------- |
+| `id` | string | Unique identifier |
+| `status` | string | Current status |
+
+## Create a Resource
+
+```typescript
+const response = await fetch('https://app.documenso.com/api/v2/document', {
+ method: 'POST',
+ headers: {
+ Authorization: 'Bearer YOUR_API_TOKEN',
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify({
+ title: 'Service Agreement',
+ }),
+});
+```
+````
+
+---
+
+## See Also
+
+- [Related Guide](/docs/developers/related)
+
+````
+
+### Self-Hosting Documentation
+
+```mdx
+---
+title: Environment Variables
+description: Complete reference for all environment variables used to configure Documenso.
+---
+
+## Required Variables
+
+| Variable | Description |
+| ------------------ | ------------------------------------------------ |
+| `NEXTAUTH_SECRET` | Secret key for session encryption (min 32 chars) |
+| `DATABASE_URL` | PostgreSQL connection URL |
+
+---
+
+## Optional Variables
+
+| Variable | Default | Description |
+| -------------- | ------- | ---------------------- |
+| `PORT` | `3000` | Port the server runs on |
+
+---
+
+## See Also
+
+- [Database Configuration](/docs/self-hosting/configuration/database)
+````
+
+## Documentation Audiences
+
+Tailor content to the audience:
+
+- **User docs**: Focus on UI workflows, bold UI elements (**Settings**, **Save**), use `>` for navigation paths (**Settings > Team > Members**), number sequential steps, no code required
+- **Developer docs**: API/SDK examples, authentication, webhooks, code samples in TypeScript, link to OpenAPI reference
+- **Self-hosting docs**: Deployment guides, environment variables, Docker/non-Docker approaches, system requirements, troubleshooting
+
+## Guidelines
+
+See [WRITING_STYLE.md](../../../WRITING_STYLE.md) for complete guidelines. Key points:
+
+- **Tone**: Direct, second-person, no emojis, no excessive personality
+- **Examples**: Progressive complexity, all must be valid TypeScript
+- **Tables**: Use Sharp-style nested parameter tables for API docs
+- **Callouts**: Use sparingly for warnings, beta features, security
+- **Cross-references**: Link related docs, add "See Also" sections
+- **Navigation**: Update `meta.json` when adding new pages
+- **Limitations**: Explicitly list what is NOT supported
+- **Images**: Use `.webp` format, store in `apps/docs/public/`
+
+## Process
+
+1. **Identify the audience** - Users, Developers, or Self-Hosters?
+2. **Explore the code** - Read source files to understand the feature
+3. **Check existing docs** - Look in `apps/docs/content/docs/` for related pages
+4. **Draft the structure** - Outline sections before writing
+5. **Write content** - Fill in each section following audience-specific patterns
+6. **Update navigation** - Add to relevant `meta.json` if creating a new page
+7. **Add cross-references** - Link from related docs, add "See Also" section
+
+## Begin
+
+Analyze the conversation context to determine the documentation scope, read the relevant source code, and create comprehensive MDX documentation in `apps/docs/content/docs/`.
diff --git a/.opencode/skill/create-justification/SKILL.md b/.agents/skills/create-justification/SKILL.md
similarity index 100%
rename from .opencode/skill/create-justification/SKILL.md
rename to .agents/skills/create-justification/SKILL.md
diff --git a/.opencode/skill/create-plan/SKILL.md b/.agents/skills/create-plan/SKILL.md
similarity index 100%
rename from .opencode/skill/create-plan/SKILL.md
rename to .agents/skills/create-plan/SKILL.md
diff --git a/.opencode/skill/create-scratch/SKILL.md b/.agents/skills/create-scratch/SKILL.md
similarity index 100%
rename from .opencode/skill/create-scratch/SKILL.md
rename to .agents/skills/create-scratch/SKILL.md
diff --git a/.opencode/skills/envelope-editor-v2-e2e/SKILL.md b/.agents/skills/envelope-editor-v2-e2e/SKILL.md
similarity index 100%
rename from .opencode/skills/envelope-editor-v2-e2e/SKILL.md
rename to .agents/skills/envelope-editor-v2-e2e/SKILL.md
diff --git a/.opencode/commands/create-documentation.md b/.opencode/commands/create-documentation.md
new file mode 100644
index 000000000..03fa54bf3
--- /dev/null
+++ b/.opencode/commands/create-documentation.md
@@ -0,0 +1,27 @@
+---
+description: Generate markdown documentation for a module or feature
+argument-hint: <topic-or-feature>
+---
+
+You are generating documentation for the Documenso project.
+
+## Your Task
+
+Load and follow the skill at `.agents/skills/create-documentation/SKILL.md`. It contains the complete instructions for writing documentation including:
+
+- Documentation structure and file locations
+- MDX format and Fumadocs components
+- Audience-specific patterns (Users, Developers, Self-Hosters)
+- Navigation (`meta.json`) updates
+- Writing style guidelines
+
+## Context
+
+The topic or feature to document is: `$ARGUMENTS`
+
+## Begin
+
+1. **Read the skill** at `.agents/skills/create-documentation/SKILL.md`
+2. **Read WRITING_STYLE.md** for tone and formatting conventions
+3. **Follow the skill instructions** to create comprehensive documentation
+4. **Use TodoWrite** to track your progress throughout
diff --git a/.opencode/commands/create-justification.md b/.opencode/commands/create-justification.md
index f36a04f15..72f10d23b 100644
--- a/.opencode/commands/create-justification.md
+++ b/.opencode/commands/create-justification.md
@@ -7,69 +7,17 @@ You are creating a new justification file in the `.agents/justifications/` direc
## Your Task
-1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended)
-2. **Gather content** - Collect or generate the justification content
-3. **Create the file** - Use the create-justification script to generate the file
+Load and follow the skill at `.agents/skills/create-justification/SKILL.md`. It contains the complete instructions for creating justification files including:
-## Usage
+- Unique three-word ID generation
+- Frontmatter format with date and title
+- Script usage (`scripts/create-justification.ts`)
-The script will automatically:
-- Generate a unique three-word ID (e.g., `swift-emerald-river`)
-- Create frontmatter with current date and formatted title
-- Save the file as `{id}-{slug}.md` in `.agents/justifications/`
+## Context
-## Creating the File
-
-### Option 1: Direct Content
-
-If you have the content ready, run:
-
-```bash
-npx tsx scripts/create-justification.ts "$ARGUMENTS" "Your justification content here"
-```
-
-### Option 2: Multi-line Content (Heredoc)
-
-For multi-line content, use heredoc:
-
-```bash
-npx tsx scripts/create-justification.ts "$ARGUMENTS" << HEREDOC
-Your multi-line
-justification content
-goes here
-HEREDOC
-```
-
-### Option 3: Pipe Content
-
-You can also pipe content:
-
-```bash
-echo "Your content" | npx tsx scripts/create-justification.ts "$ARGUMENTS"
-```
-
-## File Format
-
-The created file will have:
-
-```markdown
----
-date: 2026-01-13
-title: Justification Title
----
-
-Your content here
-```
-
-The title is automatically formatted from the slug (e.g., `architecture-decision` → `Architecture Decision`).
-
-## Guidelines
-
-- Use descriptive slugs in kebab-case (e.g., `tech-stack-choice`, `api-design-rationale`)
-- Include clear reasoning and context for the decision
-- The unique ID ensures no filename conflicts
-- Files are automatically dated for organization
+The justification slug and optional content: `$ARGUMENTS`
## Begin
-Create a justification file using the slug from `$ARGUMENTS` and appropriate content documenting the reasoning or justification.
+1. **Read the skill** at `.agents/skills/create-justification/SKILL.md`
+2. **Create the justification file** using the slug from `$ARGUMENTS` and appropriate content documenting the reasoning or justification
diff --git a/.opencode/commands/create-plan.md b/.opencode/commands/create-plan.md
index cde144440..215ab83a2 100644
--- a/.opencode/commands/create-plan.md
+++ b/.opencode/commands/create-plan.md
@@ -7,70 +7,17 @@ You are creating a new plan file in the `.agents/plans/` directory.
## Your Task
-1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended)
-2. **Gather content** - Collect or generate the plan content
-3. **Create the file** - Use the create-plan script to generate the file
+Load and follow the skill at `.agents/skills/create-plan/SKILL.md`. It contains the complete instructions for creating plan files including:
-## Usage
+- Unique three-word ID generation
+- Frontmatter format with date and title
+- Script usage (`scripts/create-plan.ts`)
-The script will automatically:
+## Context
-- Generate a unique three-word ID (e.g., `happy-blue-moon`)
-- Create frontmatter with current date and formatted title
-- Save the file as `{id}-{slug}.md` in `.agents/plans/`
-
-## Creating the File
-
-### Option 1: Direct Content
-
-If you have the content ready, run:
-
-```bash
-npx tsx scripts/create-plan.ts "$ARGUMENTS" "Your plan content here"
-```
-
-### Option 2: Multi-line Content (Heredoc)
-
-For multi-line content, use heredoc:
-
-```bash
-npx tsx scripts/create-plan.ts "$ARGUMENTS" << HEREDOC
-Your multi-line
-plan content
-goes here
-HEREDOC
-```
-
-### Option 3: Pipe Content
-
-You can also pipe content:
-
-```bash
-echo "Your content" | npx tsx scripts/create-plan.ts "$ARGUMENTS"
-```
-
-## File Format
-
-The created file will have:
-
-```markdown
----
-date: 2026-01-13
-title: Plan Title
----
-
-Your content here
-```
-
-The title is automatically formatted from the slug (e.g., `my-feature` → `My Feature`).
-
-## Guidelines
-
-- Use descriptive slugs in kebab-case (e.g., `user-authentication`, `api-integration`)
-- Include clear, actionable plan content
-- The unique ID ensures no filename conflicts
-- Files are automatically dated for organization
+The plan slug and optional content: `$ARGUMENTS`
## Begin
-Create a plan file using the slug from `$ARGUMENTS` and appropriate content for the planning task.
+1. **Read the skill** at `.agents/skills/create-plan/SKILL.md`
+2. **Create the plan file** using the slug from `$ARGUMENTS` and appropriate content
diff --git a/.opencode/commands/create-scratch.md b/.opencode/commands/create-scratch.md
index 1f4138944..abf06d340 100644
--- a/.opencode/commands/create-scratch.md
+++ b/.opencode/commands/create-scratch.md
@@ -7,69 +7,17 @@ You are creating a new scratch file in the `.agents/scratches/` directory.
## Your Task
-1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended)
-2. **Gather content** - Collect or generate the scratch content
-3. **Create the file** - Use the create-scratch script to generate the file
+Load and follow the skill at `.agents/skills/create-scratch/SKILL.md`. It contains the complete instructions for creating scratch files including:
-## Usage
+- Unique three-word ID generation
+- Frontmatter format with date and title
+- Script usage (`scripts/create-scratch.ts`)
-The script will automatically:
-- Generate a unique three-word ID (e.g., `calm-teal-cloud`)
-- Create frontmatter with current date and formatted title
-- Save the file as `{id}-{slug}.md` in `.agents/scratches/`
+## Context
-## Creating the File
-
-### Option 1: Direct Content
-
-If you have the content ready, run:
-
-```bash
-npx tsx scripts/create-scratch.ts "$ARGUMENTS" "Your scratch content here"
-```
-
-### Option 2: Multi-line Content (Heredoc)
-
-For multi-line content, use heredoc:
-
-```bash
-npx tsx scripts/create-scratch.ts "$ARGUMENTS" << HEREDOC
-Your multi-line
-scratch content
-goes here
-HEREDOC
-```
-
-### Option 3: Pipe Content
-
-You can also pipe content:
-
-```bash
-echo "Your content" | npx tsx scripts/create-scratch.ts "$ARGUMENTS"
-```
-
-## File Format
-
-The created file will have:
-
-```markdown
----
-date: 2026-01-13
-title: Scratch Title
----
-
-Your content here
-```
-
-The title is automatically formatted from the slug (e.g., `quick-notes` → `Quick Notes`).
-
-## Guidelines
-
-- Use descriptive slugs in kebab-case (e.g., `exploration-ideas`, `temporary-notes`)
-- Scratch files are for temporary notes, explorations, or ideas
-- The unique ID ensures no filename conflicts
-- Files are automatically dated for organization
+The scratch slug and optional content: `$ARGUMENTS`
## Begin
-Create a scratch file using the slug from `$ARGUMENTS` and appropriate content for notes or exploration.
+1. **Read the skill** at `.agents/skills/create-scratch/SKILL.md`
+2. **Create the scratch file** using the slug from `$ARGUMENTS` and appropriate content for notes or exploration
diff --git a/.opencode/commands/document.md b/.opencode/commands/document.md
deleted file mode 100644
index 72ca40259..000000000
--- a/.opencode/commands/document.md
+++ /dev/null
@@ -1,201 +0,0 @@
----
-description: Generate MDX documentation for a module or feature
-argument-hint: <module-path-or-feature>
----
-
-You are creating proper MDX documentation for a module or feature in Documenso using Nextra.
-
-## Your Task
-
-1. **Identify the scope** - What does `$ARGUMENTS` refer to? (file, directory, or feature name)
-2. **Read the source code** - Understand the public API, types, and behavior
-3. **Read existing docs** - Check if there's documentation to update or reference
-4. **Write comprehensive documentation** - Create or update MDX docs in the appropriate location
-5. **Update navigation** - Add entry to `_meta.js` if creating a new page
-
-## Documentation Structure
-
-Create documentation in the appropriate location:
-
-- **Developer docs**: `apps/documentation/pages/developers/`
-- **User docs**: `apps/documentation/pages/users/`
-
-### File Format
-
-All documentation files must be `.mdx` files with frontmatter:
-
-```mdx
----
-title: Page Title
-description: Brief description for SEO and meta tags
----
-
-# Page Title
-
-Content starts here...
-```
-
-### Navigation
-
-Each directory should have a `_meta.js` file that defines the navigation structure:
-
-```javascript
-export default {
- index: 'Introduction',
- 'feature-name': 'Feature Name',
- 'another-feature': 'Another Feature',
-};
-```
-
-If creating a new page, add it to the appropriate `_meta.js` file.
-
-### Documentation Format
-
-````mdx
----
-title: <Module|Feature Name>
-description: Brief description of what this does and when to use it
----
-
-# <Module|Feature Name>
-
-Brief description of what this module/feature does and when to use it.
-
-## Installation
-
-If there are specific packages or imports needed:
-
-```bash
-npm install @documenso/package-name
-```
-
-## Quick Start
-
-```jsx
-// Minimal working example
-import { Component } from '@documenso/package';
-
-const Example = () => {
- return <Component />;
-};
-```
-
-## API Reference
-
-### Component/Function Name
-
-Description of what it does.
-
-#### Props/Parameters
-
-| Prop/Param | Type | Description |
-| ---------- | -------------------- | ------------------------- |
-| prop | `string` | Description of the prop |
-| optional | `boolean` (optional) | Optional prop description |
-
-#### Example
-
-```jsx
-import { Component } from '@documenso/package';
-
-<Component prop="value" optional={true} />;
-```
-
-### Types
-
-#### `TypeName`
-
-```typescript
-type TypeName = {
- property: string;
- optional?: boolean;
-};
-```
-
-## Examples
-
-### Common Use Case
-
-```jsx
-// Full working example
-```
-
-### Advanced Usage
-
-```jsx
-// More complex example
-```
-
-## Related
-
-- [Link to related documentation](/developers/path)
-- [Another related page](/users/path)
-````
-
-## Guidelines
-
-### Content Quality
-
-- **Be accurate** - Verify behavior by reading the code
-- **Be complete** - Document all public API surface
-- **Be practical** - Include real, working examples
-- **Be concise** - Don't over-explain obvious things
-- **Be user-focused** - Write for the target audience (developers or users)
-
-### Code Examples
-
-- Use appropriate language tags: `jsx`, `tsx`, `typescript`, `bash`, `json`
-- Show imports when not obvious
-- Include expected output in comments where helpful
-- Progress from simple to complex
-- Use real examples from the codebase when possible
-
-### Formatting
-
-- Always include frontmatter with `title` and `description`
-- Use proper markdown headers (h1 for title, h2 for sections)
-- Use tables for props/parameters documentation (matching existing style)
-- Use code fences with appropriate language tags
-- Use Nextra components when appropriate:
- - `<Callout type="info">` for notes
- - `<Steps>` for step-by-step instructions
-- Use relative links for internal documentation (e.g., `/developers/embedding/react`)
-
-### Nextra Components
-
-You can import and use Nextra components:
-
-```jsx
-import { Callout, Steps } from 'nextra/components';
-
-<Callout type="info">
- This is an informational note.
-</Callout>
-
-<Steps>
- <Steps.Step>First step</Steps.Step>
- <Steps.Step>Second step</Steps.Step>
-</Steps>
-```
-
-### Maintenance
-
-- Include types inline so docs don't get stale
-- Reference source file locations for complex behavior
-- Keep examples up-to-date with the codebase
-- Update `_meta.js` when adding new pages
-
-## Process
-
-1. **Explore the code** - Read source files to understand the API
-2. **Identify the audience** - Is this for developers or users?
-3. **Check existing docs** - Look for similar pages to match style
-4. **Draft the structure** - Outline sections before writing
-5. **Write content** - Fill in each section with frontmatter
-6. **Add examples** - Create working code samples
-7. **Update navigation** - Add to `_meta.js` if needed
-8. **Review** - Read through for clarity and accuracy
-
-## Begin
-
-Analyze `$ARGUMENTS`, read the relevant source code, check existing documentation patterns, and create comprehensive MDX documentation following the Documenso documentation style.
diff --git a/.opencode/skills/agent-browser b/.opencode/skills/agent-browser
deleted file mode 120000
index e298b7be3..000000000
--- a/.opencode/skills/agent-browser
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/agent-browser
\ No newline at end of file
diff --git a/apps/docs/content/docs/developers/embedding/authoring/index.mdx b/apps/docs/content/docs/developers/embedding/authoring/index.mdx
new file mode 100644
index 000000000..834d3cc71
--- /dev/null
+++ b/apps/docs/content/docs/developers/embedding/authoring/index.mdx
@@ -0,0 +1,56 @@
+---
+title: Authoring
+description: Embed document, template, and envelope creation directly in your application.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+In addition to embedding signing, Documenso supports embedded authoring. It allows your users to create and edit documents, templates, and envelopes without leaving your application.
+
+<Callout type="warn">
+ Embedded authoring is included with [Enterprise](https://documen.so/enterprise-cta) plans. It is
+ also available as a paid add-on for the [Platform Plan](https://documen.so/platform-cta-pricing).
+ Contact sales for access.
+</Callout>
+
+## Versions
+
+Embedded authoring is available in two versions:
+
+- **[V1 Authoring](/docs/developers/embedding/authoring/v1)** — Works with V1 Documents and Templates.
+- **[V2 Authoring](/docs/developers/embedding/authoring/v2)** — Works with Envelopes, which are the unified model for documents and templates.
+
+### Comparison
+
+| Aspect | V1 | V2 |
+| --- | --- | --- |
+| Entity model | Documents and Templates (separate) | Envelopes (unified, can be documents or templates) |
+| API compatibility | V1 Documents/Templates API | V2 Envelopes API |
+| Customization | 6 simple boolean flags | Rich structured settings with sections (general, settings, actions, envelope items, recipients) |
+
+---
+
+## Presign Tokens
+
+Before using any authoring component, obtain a presign token from your backend:
+
+```
+POST /api/v2/embedding/create-presign-token
+```
+
+This endpoint requires your Documenso API key. The token has a default expiration of 1 hour.
+
+See the [API documentation](https://openapi.documenso.com/reference#tag/embedding) for full details.
+
+<Callout type="warn">
+ Presign tokens should be created server-side. Never expose your API key in client-side code.
+</Callout>
+
+---
+
+## Next Steps
+
+- [V1 Authoring](/docs/developers/embedding/authoring/v1) — Create and edit documents and templates using V1 components
+- [V2 Authoring](/docs/developers/embedding/authoring/v2) — Create and edit envelopes using V2 components
+- [CSS Variables](/docs/developers/embedding/css-variables) — Customize the appearance of embedded components
+- [SDKs](/docs/developers/embedding/sdks) — Framework-specific SDK documentation
diff --git a/apps/docs/content/docs/developers/embedding/authoring/meta.json b/apps/docs/content/docs/developers/embedding/authoring/meta.json
new file mode 100644
index 000000000..45cb7a47b
--- /dev/null
+++ b/apps/docs/content/docs/developers/embedding/authoring/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Authoring",
+ "pages": ["v1", "v2"]
+}
diff --git a/apps/docs/content/docs/developers/embedding/authoring.mdx b/apps/docs/content/docs/developers/embedding/authoring/v1.mdx
similarity index 89%
rename from apps/docs/content/docs/developers/embedding/authoring.mdx
rename to apps/docs/content/docs/developers/embedding/authoring/v1.mdx
index 030f9ae93..9d33e57e9 100644
--- a/apps/docs/content/docs/developers/embedding/authoring.mdx
+++ b/apps/docs/content/docs/developers/embedding/authoring/v1.mdx
@@ -1,11 +1,11 @@
---
-title: Authoring
-description: Embed document and template creation directly in your application.
+title: V1 Authoring
+description: Embed V1 document and template creation directly in your application.
---
import { Callout } from 'fumadocs-ui/components/callout';
-In addition to embedding signing, Documenso supports embedded authoring. It allows your users to create and edit documents and templates without leaving your application.
+V1 authoring components allow your users to create and edit documents and templates using the V1 Documents and Templates API without leaving your application.
<Callout type="warn">
Embedded authoring is included with [Enterprise](https://documen.so/enterprise-cta) plans. It is
@@ -15,7 +15,7 @@ In addition to embedding signing, Documenso supports embedded authoring. It allo
## Components
-The SDK provides four authoring components:
+The SDK provides four V1 authoring components:
| Component | Purpose |
| ----------------------- | ----------------------- |
@@ -24,24 +24,16 @@ The SDK provides four authoring components:
| `EmbedUpdateDocumentV1` | Edit existing documents |
| `EmbedUpdateTemplateV1` | Edit existing templates |
-All authoring components require a **presign token** for authentication instead of a regular token.
---
## Presign Tokens
-Before using any authoring component, obtain a presign token from your backend:
+All authoring components require a **presign token** for authentication. See the [Authoring overview](/docs/developers/embedding/authoring) for details on obtaining presign tokens.
-```
-POST /api/v2/embedding/create-presign-token
-```
-
-This endpoint requires your Documenso API key. The token has a default expiration of 1 hour.
-
-See the [API documentation](https://openapi.documenso.com/reference#tag/embedding) for full details.
<Callout type="warn">
- Presign tokens should be created server-side. Never expose your API key in client-side code.
+ A presigned token is NOT an API token
</Callout>
---
@@ -147,7 +139,7 @@ const TemplateEditor = ({ presignToken, templateId }) => {
| `externalId` | `string` | No | Your reference ID to link with the document or template |
| `host` | `string` | No | Custom host URL. Defaults to `https://app.documenso.com` |
| `css` | `string` | No | Custom CSS string (Platform Plan) |
-| `cssVars` | `object` | No | CSS variable overrides (Platform Plan) |
+| `cssVars` | `object` | No | [CSS variable](/docs/developers/embedding/css-variables) overrides (Platform Plan) |
| `darkModeDisabled` | `boolean` | No | Disable dark mode (Platform Plan) |
| `className` | `string` | No | CSS class for the iframe |
| `features` | `object` | No | Feature toggles for the authoring experience |
@@ -301,6 +293,7 @@ Pass extra props to the iframe for testing experimental features:
## See Also
- [Embedding Overview](/docs/developers/embedding) - Signing embed concepts and props
+- [V2 Authoring](/docs/developers/embedding/authoring/v2) - V2 envelope authoring
- [CSS Variables](/docs/developers/embedding/css-variables) - Customize appearance
- [Documents API](/docs/developers/api/documents) - Create documents via API
- [Templates API](/docs/developers/api/templates) - Create templates via API
diff --git a/apps/docs/content/docs/developers/embedding/authoring/v2.mdx b/apps/docs/content/docs/developers/embedding/authoring/v2.mdx
new file mode 100644
index 000000000..deaabd542
--- /dev/null
+++ b/apps/docs/content/docs/developers/embedding/authoring/v2.mdx
@@ -0,0 +1,340 @@
+---
+title: V2 Authoring
+description: Embed envelope creation and editing directly in your application.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+V2 authoring components allow your users to create and edit envelopes without leaving your application. Envelopes are the unified model for documents and templates in the V2 API.
+
+<Callout type="warn">
+ Embedded authoring is included with [Enterprise](https://documen.so/enterprise-cta) plans. It is
+ also available as a paid add-on for the [Platform Plan](https://documen.so/platform-cta-pricing).
+ Contact sales for access.
+</Callout>
+
+## Components
+
+The SDK provides two V2 authoring components:
+
+| Component | Purpose |
+| ---------------------- | ------------------------ |
+| `EmbedCreateEnvelope` | Create new envelopes |
+| `EmbedUpdateEnvelope` | Edit existing envelopes |
+
+---
+
+## Presign Tokens
+
+All authoring components require a **presign token** for authentication. See the [Authoring overview](/docs/developers/embedding/authoring) for details on obtaining presign tokens.
+
+<Callout type="warn">
+ A presigned token is NOT an API token
+</Callout>
+
+---
+
+## Creating Envelopes
+
+Use `EmbedCreateEnvelope` to embed envelope creation. The `type` prop determines whether the envelope is created as a document or template.
+
+```jsx
+import { EmbedCreateEnvelope } from '@documenso/embed-react';
+
+const EnvelopeCreator = ({ presignToken }) => {
+ return (
+ <div style={{ height: '800px', width: '100%' }}>
+ <EmbedCreateEnvelope
+ presignToken={presignToken}
+ type="DOCUMENT"
+ externalId="order-12345"
+ onEnvelopeCreated={(data) => {
+ console.log('Envelope created:', data.envelopeId);
+ console.log('External ID:', data.externalId);
+ }}
+ />
+ </div>
+ );
+};
+```
+
+To create a template instead of a document, set `type` to `"TEMPLATE"`:
+
+```jsx
+<EmbedCreateEnvelope
+ presignToken={presignToken}
+ type="TEMPLATE"
+ externalId="template-12345"
+ onEnvelopeCreated={(data) => {
+ console.log('Template envelope created:', data.envelopeId);
+ }}
+/>
+```
+
+---
+
+## Editing Envelopes
+
+Use `EmbedUpdateEnvelope` to embed envelope editing:
+
+```jsx
+import { EmbedUpdateEnvelope } from '@documenso/embed-react';
+
+const EnvelopeEditor = ({ presignToken, envelopeId }) => {
+ return (
+ <div style={{ height: '800px', width: '100%' }}>
+ <EmbedUpdateEnvelope
+ presignToken={presignToken}
+ envelopeId={envelopeId}
+ externalId="order-12345"
+ onEnvelopeUpdated={(data) => {
+ console.log('Envelope updated:', data.envelopeId);
+ }}
+ />
+ </div>
+ );
+};
+```
+
+---
+
+## Props
+
+### All V2 Authoring Components
+
+| Prop | Type | Required | Description |
+| ------------------ | --------- | -------- | -------------------------------------------------------- |
+| `presignToken` | `string` | Yes | Authentication token from your backend |
+| `externalId` | `string` | No | Your reference ID to link with the envelope |
+| `host` | `string` | No | Custom host URL. Defaults to `https://app.documenso.com` |
+| `css` | `string` | No | Custom CSS string (Platform Plan) |
+| `cssVars` | `object` | No | [CSS variable](/docs/developers/embedding/css-variables) overrides (Platform Plan) |
+| `darkModeDisabled` | `boolean` | No | Disable dark mode (Platform Plan) |
+| `className` | `string` | No | CSS class for the iframe |
+| `features` | `object` | No | Feature toggles for the authoring experience |
+
+### Create Component Only
+
+| Prop | Type | Required | Description |
+| ------ | ------------------------------ | -------- | --------------------------------------------------- |
+| `type` | `"DOCUMENT"` \| `"TEMPLATE"` | Yes | Whether to create a document or template envelope |
+
+### Update Component Only
+
+| Prop | Type | Required | Description |
+| ------------ | -------- | -------- | ---------------------------- |
+| `envelopeId` | `string` | Yes | The envelope ID to edit |
+
+---
+
+## Feature Toggles
+
+V2 authoring provides rich, structured feature toggles organized into sections. Pass a partial configuration to customize the authoring experience — any omitted fields will use their defaults.
+
+```jsx
+<EmbedCreateEnvelope
+ presignToken={presignToken}
+ type="DOCUMENT"
+ features={{
+ general: {
+ allowConfigureEnvelopeTitle: false,
+ allowUploadAndRecipientStep: false,
+ allowAddFieldsStep: false,
+ allowPreviewStep: false,
+ },
+ settings: {
+ allowConfigureSignatureTypes: false,
+ allowConfigureLanguage: false,
+ allowConfigureDateFormat: false,
+ },
+ recipients: {
+ allowApproverRole: false,
+ allowViewerRole: false,
+ },
+ }}
+/>
+```
+
+### General
+
+Controls the overall authoring flow and UI:
+
+| Property | Type | Default | Description |
+| ------------------------------- | --------- | ------- | ------------------------------------------------ |
+| `allowConfigureEnvelopeTitle` | `boolean` | `true` | Allow editing the envelope title |
+| `allowUploadAndRecipientStep` | `boolean` | `true` | Show the upload and recipient configuration step |
+| `allowAddFieldsStep` | `boolean` | `true` | Show the add fields step |
+| `allowPreviewStep` | `boolean` | `true` | Show the preview step |
+| `minimizeLeftSidebar` | `boolean` | `true` | Minimize the left sidebar by default |
+
+### Settings
+
+Controls envelope configuration options. Set to `null` to hide envelope settings entirely.
+
+| Property | Type | Default | Description |
+| ----------------------------------- | --------- | ------- | ----------------------------------------- |
+| `allowConfigureSignatureTypes` | `boolean` | `true` | Allow configuring signature types |
+| `allowConfigureLanguage` | `boolean` | `true` | Allow configuring the language |
+| `allowConfigureDateFormat` | `boolean` | `true` | Allow configuring the date format |
+| `allowConfigureTimezone` | `boolean` | `true` | Allow configuring the timezone |
+| `allowConfigureRedirectUrl` | `boolean` | `true` | Allow configuring a redirect URL |
+| `allowConfigureDistribution` | `boolean` | `true` | Allow configuring distribution settings |
+| `allowConfigureExpirationPeriod` | `boolean` | `true` | Allow configuring the expiration period |
+| `allowConfigureEmailSender` | `boolean` | `true` | Allow configuring the email sender |
+| `allowConfigureEmailReplyTo` | `boolean` | `true` | Allow configuring the email reply-to |
+
+### Actions
+
+Controls available actions during authoring:
+
+| Property | Type | Default | Description |
+| ------------------ | --------- | ------- | ------------------------ |
+| `allowAttachments` | `boolean` | `true` | Allow adding attachments |
+
+### Envelope Items
+
+Controls how envelope items (individual files within the envelope) can be managed. Set to `null` to prevent any item modifications.
+
+| Property | Type | Default | Description |
+| --------------------- | --------- | ------- | ------------------------------------ |
+| `allowConfigureTitle` | `boolean` | `true` | Allow editing item titles |
+| `allowConfigureOrder` | `boolean` | `true` | Allow reordering items |
+| `allowUpload` | `boolean` | `true` | Allow uploading new items |
+| `allowDelete` | `boolean` | `true` | Allow deleting items |
+
+### Recipients
+
+Controls recipient configuration options. Set to `null` to prevent any recipient modifications.
+
+| Property | Type | Default | Description |
+| --------------------------------- | --------- | ------- | ---------------------------------------- |
+| `allowConfigureSigningOrder` | `boolean` | `true` | Allow configuring the signing order |
+| `allowConfigureDictateNextSigner` | `boolean` | `true` | Allow configuring dictate next signer |
+| `allowApproverRole` | `boolean` | `true` | Allow the approver recipient role |
+| `allowViewerRole` | `boolean` | `true` | Allow the viewer recipient role |
+| `allowCCerRole` | `boolean` | `true` | Allow the CC recipient role |
+| `allowAssistantRole` | `boolean` | `true` | Allow the assistant recipient role |
+
+### Disabling Steps
+
+You can also disable entire steps of the authoring flow. This allows you to skip steps that are not relevant to your use case:
+
+```jsx
+<EmbedCreateEnvelope
+ presignToken={presignToken}
+ type="DOCUMENT"
+ features={{
+ general: {
+ allowUploadAndRecipientStep: false, // Skip the upload and recipient step
+ allowAddFieldsStep: false, // Skip the add fields step
+ allowPreviewStep: false, // Skip the preview step
+ },
+ settings: null, // Hide all envelope settings
+ envelopeItems: null, // Prevent item modifications
+ recipients: null, // Prevent recipient modifications
+ }}
+/>
+```
+
+---
+
+## Event Callbacks
+
+### `onEnvelopeCreated`
+
+Fired when an envelope is successfully created:
+
+| Field | Type | Description |
+| ------------ | ---------------- | --------------------------------------- |
+| `envelopeId` | `string` | The ID of the created envelope |
+| `externalId` | `string \| null` | Your external reference ID, if provided |
+
+### `onEnvelopeUpdated`
+
+Fired when an envelope is successfully updated:
+
+| Field | Type | Description |
+| ------------ | ---------------- | --------------------------------------- |
+| `envelopeId` | `string` | The ID of the updated envelope |
+| `externalId` | `string \| null` | Your external reference ID, if provided |
+
+---
+
+## Complete Integration Example
+
+This example shows a full workflow where users create an envelope and then edit it:
+
+```tsx
+import { useState } from 'react';
+
+import { EmbedCreateEnvelope, EmbedUpdateEnvelope } from '@documenso/embed-react';
+
+const EnvelopeManager = ({ presignToken }) => {
+ const [envelopeId, setEnvelopeId] = useState(null);
+ const [mode, setMode] = useState('create');
+
+ if (mode === 'success') {
+ return (
+ <div>
+ <h2>Envelope updated successfully</h2>
+ <button
+ onClick={() => {
+ setEnvelopeId(null);
+ setMode('create');
+ }}
+ >
+ Create Another Envelope
+ </button>
+ </div>
+ );
+ }
+
+ if (mode === 'edit' && envelopeId) {
+ return (
+ <div style={{ height: '800px', width: '100%' }}>
+ <button onClick={() => setMode('create')}>Back to Create</button>
+ <EmbedUpdateEnvelope
+ presignToken={presignToken}
+ envelopeId={envelopeId}
+ onEnvelopeUpdated={(data) => {
+ console.log('Envelope updated:', data.envelopeId);
+ setMode('success');
+ }}
+ />
+ </div>
+ );
+ }
+
+ return (
+ <div style={{ height: '800px', width: '100%' }}>
+ <EmbedCreateEnvelope
+ presignToken={presignToken}
+ type="DOCUMENT"
+ features={{
+ general: {
+ allowConfigureEnvelopeTitle: false,
+ },
+ settings: {
+ allowConfigureSignatureTypes: false,
+ allowConfigureLanguage: false,
+ },
+ }}
+ onEnvelopeCreated={(data) => {
+ console.log('Envelope created:', data.envelopeId);
+ setEnvelopeId(data.envelopeId);
+ setMode('edit');
+ }}
+ />
+ </div>
+ );
+};
+```
+
+---
+
+## See Also
+
+- [Authoring Overview](/docs/developers/embedding/authoring) - V1 vs V2 comparison and presign tokens
+- [V1 Authoring](/docs/developers/embedding/authoring/v1) - V1 document and template authoring
+- [Embedding Overview](/docs/developers/embedding) - Signing embed concepts and props
+- [CSS Variables](/docs/developers/embedding/css-variables) - Customize appearance
diff --git a/apps/docs/content/docs/developers/embedding/css-variables.mdx b/apps/docs/content/docs/developers/embedding/css-variables.mdx
index e95b0fda4..ae7185964 100644
--- a/apps/docs/content/docs/developers/embedding/css-variables.mdx
+++ b/apps/docs/content/docs/developers/embedding/css-variables.mdx
@@ -59,6 +59,7 @@ Use the `cssVars` prop on any embed component to override default colors, spacin
| `destructiveForeground` | Destructive/danger text color |
| `ring` | Focus ring color |
| `warning` | Warning/alert color |
+| `envelopeEditorBackground` | Envelope editor background color. _V2 Envelope Editor only._ |
### Spacing