Environment variable docs

The JSDoc above every @Env('...') property is exported almost verbatim into the environment variables reference on docs.n8n.io. The generated table has four columns: variable name, description, data type, default. Your JSDoc is the description column. The reader is a self-hosting operator, not an n8n developer.

Follow the n8n docs style guide for these comments. It overrides the ASD-STE100 rule in AGENTS.md for this one case. The rules below are the parts of that guide that matter for a one-paragraph description.

Rules

• Every @Env property has a JSDoc. No exceptions. A missing comment ships as an empty description cell.
• Write for the operator. Say what the setting does, when to change it, and what happens when it's unset or wrong. Don't explain why the code is written the way it is.
• No code references. No file names, class names, function names, constants, license keys, or other internals the reader can't open. Values the operator types into the variable are fine and often needed, for example a credential type ID like googleOAuth2Api or a mode like postgresdb. The test: would the operator paste this into a config file, or would they need the source to know what it means? Details for developers go in a regular // comment on the implementation, not in the JSDoc.
• No attack scenarios. Say what the setting protects, not how an attacker would exploit it. This is a public page.
• Don't repeat the default. The default renders in its own column. Don't write "Defaults to true" or "Default: 1 hour". Do say what the unset state means when it's not obvious, for example "When unset, n8n uses the Redis host".
• State units and formats. Say "in milliseconds", "in bytes", "a comma-separated list", "a JSON object". The data type column only says Number or String.
• Use allowed values when the set is small. "One of sqlite, postgresdb." For a list, show one inline example in the sentence.
• No JSDoc tags. No @example, @default, @see, @deprecated. The exporter copies the tag name into the docs. Put the example or the deprecation notice in a sentence instead.
• Product names: "Gateway credits", not "n8n Connect" or "AI Gateway". "Publish a workflow", not "activate". n8n is always lowercase.
• Style: present tense, active voice, second person. Use contractions. No em dashes, use a comma or a new sentence. No "e.g." or "i.e.", write "for example" and "that is". Spell out zero to nine, numerals from 10. Values the operator types stay numerals, for example "Set to 0". Sentence case. One idea per sentence. End every sentence with a period.
• Plain words: "use" not "utilize", "lets you" not "allows you to", cut "powerful", "seamless", "simply", "it's important to note".
• Length: one to three sentences. If the setting needs more, the extra belongs in a docs page the comment can't link to yet; keep the comment to what fits a table cell.

Examples

Bad, as found in the generated docs:

/**
 * Instance-level enablement for n8n Connect (AI Gateway). Licensed instances
 * are enabled by default; false opts out. Budget / free allowance still comes
 * from the license (`quota:aiGatewayBudget`).
 */

Wrong product name, a restated default, and an internal license key. Good:

/**
 * Whether Gateway credits are available on this instance. Set to false to
 * turn them off on a licensed instance. The credit allowance comes from your
 * license.
 */

Bad:

/**
 * Time to live in milliseconds for Redis cache entries. Set to 0 to disable
 * expiry. Default: 1 hour.
 */

The default is already in the table. Good:

/**
 * Time to live in milliseconds for Redis cache entries. Set to 0 to keep
 * entries until Redis evicts them.
 */

Bad:

/**
 * Comma-separated list of credential types for which overwrites are skipped
 * when the credential has been customized.
 * @example `N8N_SKIP_CREDENTIAL_OVERWRITE=zohoOAuth2Api,salesforceOAuth2Api`
 */

The @example tag lands in the description as literal text. Good:

/**
 * Comma-separated list of credential types to skip when applying credential
 * overwrites, for example `zohoOAuth2Api,salesforceOAuth2Api`. n8n skips an
 * overwrite only when a user has already changed one of its fields.
 */

Bad:

/**
 * Bind OAuth credential callbacks to the browser that initiated the flow.
 * When enabled, a session-scoped `n8n-oauth-binding` cookie is set on flow
 * initiation and verified on callback. Defeats phishing attacks where an
 * attacker injects an OAuth authorize URL into a victim's browser to land
 * tokens on the attacker's credential.
 */

Attack narrative and an internal cookie name on a public page. Good:

/**
 * Whether an OAuth credential connection must finish in the same browser
 * that started it. When enabled, n8n rejects the callback if it arrives
 * from a different browser.
 */

Review checklist

When you review a PR that adds or changes an @Env property, check each comment against this list and quote the fix in the review:

1. JSDoc present.
2. No code identifiers, file names, or internal keys.
3. No default restated.
4. Units, format, or allowed values stated.
5. No JSDoc tags.
6. No em dashes, Latin abbreviations, or filler words.
7. Reads correctly as a sentence in a table cell with no surrounding context.