Payload Tone of Voice Plugin

AI-assisted tone-of-voice audits for Payload CMS admin editors.

This plugin adds a Tone audit action next to the Payload save button for configured collections. Editors can extract text from the current document, split longer rich text into reviewable sections, stream feedback, compare suggested edits, accept suggestions into the audit workspace, and export a PDF report.

Status

MVP release. The plugin is intended for Payload 3 projects and currently uses Vercel AI Gateway by default. You can also provide a custom audit provider for another model gateway or an internal service.

Install

pnpm add @extravirgin/payload-plugin-tone-of-voice

Peer dependencies expected in the host app:

pnpm add payload @payloadcms/ui @payloadcms/richtext-lexical react react-dom

Payload package peers support Payload ^3.24.0.

Configuration

import { toneOfVoice } from '@extravirgin/payload-plugin-tone-of-voice'
import { buildConfig } from 'payload'

export default buildConfig({
  plugins: [
    toneOfVoice({
      collections: {
        posts: {
          excludeFields: ['slug', 'seo.*', 'legalDisclaimer'],
          fields: 'auto',
        },
      },
      rules: `
# Tone of voice

- Write clearly and concretely.
- Avoid inflated claims.
- Preserve legal, official, and factual wording.
      `,
    }),
  ],
})

Vercel AI Gateway

The default provider requires one of these environment variables:

AI_GATEWAY_API_KEY=...
# or
VERCEL_OIDC_TOKEN=...

Optional model settings:

toneOfVoice({
  collections: {
    posts: true,
  },
  model: 'anthropic/claude-sonnet-4.6',
  rules: toneGuide,
  temperature: 0.2,
  timeoutMs: 120_000,
})

Options

type ToneOfVoiceConfig = {
  auditProvider?: ToneOfVoiceAuditProvider
  collections: Partial<Record<CollectionSlug, boolean | ToneOfVoiceCollectionOptions>>
  disabled?: boolean
  maxInputChars?: number
  model?: string
  rules: string
  temperature?: number
  timeoutMs?: number
}

Collection options:

type ToneOfVoiceCollectionOptions = {
  excludeFields?: string[]
  fields?: 'auto' | string[]
  rules?: string
}

• collections: collection slugs to enable. Use true for auto field extraction or pass collection-specific options.
• fields: auto extracts supported text, textarea, and rich text fields. A string array limits extraction to specific paths.
• excludeFields: paths to skip when extracting fields. Simple names match anywhere (slug), nested paths match descendants (seo), and * matches one path segment (layout.*.legalText).
• rules: global tone guide in Markdown. Collection-level rules override this value.
• auditProvider: custom provider for testing or non-Vercel AI backends.
• maxInputChars: max characters per section sent to the model. Defaults to 24000.
• disabled: keeps plugin configuration present while disabling the admin UI and endpoint.

Custom Provider

import type { ToneOfVoiceAuditProvider } from '@extravirgin/payload-plugin-tone-of-voice'

const auditProvider: ToneOfVoiceAuditProvider = async (input) => {
  return {
    issues: [],
    score: 100,
    suggestions: [],
    summary: 'No changes needed.',
  }
}

Streaming providers can add a stream method:

const auditProvider: ToneOfVoiceAuditProvider = Object.assign(runAudit, {
  async *stream(input, options) {
    yield {
      type: 'result',
      value: await runAudit(input, options),
    }
  },
})

Rich Text Behavior

Long rich text fields are split into topical audit sections before being sent to the model. Heading nodes and short heading-like paragraphs start new sections; long unheaded content is chunked by paragraph. Structured rich text containing blocks or inline blocks is marked for manual review to avoid overwriting embedded content.

The model prompt asks for narrow sentence or paragraph suggestions instead of full-section replacements, and it treats legal, regulatory, official decision, permit, procurement, citation, amount, date, and named-party passages conservatively.

Development

pnpm install
pnpm dev
pnpm test:int
pnpm build

Before publishing:

pnpm clean
pnpm build
npm pack --dry-run
npm publish --access public