@optique/core 1.4.0-dev.2631 → 1.4.0-dev.2634

package/dist/constructs.cjs

@@ -859,6 +859,14 @@ function applyHiddenToDocEntry(entry, hidden) {
 		term: mergedTerm
 	};
 }
+function sourceDocumentation(children, hidden) {
+	if (require_usage.isDocHidden(hidden)) return {};
+	const environmentBindings = children.flatMap((docs) => docs.environmentBindings ?? []);
+	return {
+		...environmentBindings.length > 0 && { environmentBindings },
+		...children.length > 0 && children.every((docs) => docs.sourceOnly === true) && { sourceOnly: true }
+	};
+}
 function applyHiddenToDocFragments(fragments, hidden) {
 	if (hidden == null) return fragments;
 	const result = [];
@@ -1835,11 +1843,16 @@ function or(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, combinedMode),
 		getDocFragments(state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			let brief;
 			let description;
 			let footer;
 			let fragments;
-			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }, void 0).fragments);
+			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => collect(p.getDocFragments({ kind: "unavailable" }, void 0)));
 			else {
 				const [index, parserResult] = state.state;
 				const innerState = parserResult.success ? {
@@ -1850,10 +1863,11 @@ function or(...args) {
 				brief = docFragments.brief;
 				description = docFragments.description;
 				footer = docFragments.footer;
-				fragments = docFragments.fragments;
+				fragments = collect(docFragments);
 			}
 			if (state.kind === "unavailable" || state.state == null) fragments = require_doc.deduplicateDocFragments(fragments);
 			return {
+				...sourceDocumentation(children),
 				brief,
 				description,
 				footer,
@@ -2044,13 +2058,18 @@ function createLongestMatch(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, combinedMode),
 		getDocFragments(state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			let brief;
 			let description;
 			let footer;
 			let fragments;
 			let shouldDeduplicate;
 			if (state.kind === "unavailable" || state.state == null) {
-				fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+				fragments = parsers.flatMap((p) => collect(p.getDocFragments({ kind: "unavailable" })));
 				shouldDeduplicate = true;
 			} else {
 				const [i, result] = state.state;
@@ -2062,14 +2081,15 @@ function createLongestMatch(...args) {
 					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
-					fragments = docResult.fragments;
+					fragments = collect(docResult);
 					shouldDeduplicate = false;
 				} else {
-					fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+					fragments = parsers.flatMap((p) => collect(p.getDocFragments({ kind: "unavailable" })));
 					shouldDeduplicate = true;
 				}
 			}
 			return {
+				...sourceDocumentation(children),
 				brief,
 				description,
 				fragments: shouldDeduplicate ? require_doc.deduplicateDocFragments(fragments) : fragments,
@@ -3051,12 +3071,17 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			}, () => suggestObjectAsync(context, prefix, parserPairs));
 		},
 		getDocFragments(state, defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = parserPairs.flatMap(([field, p]) => {
 				const fieldState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[field]
 				};
-				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
+				return collect(p.getDocFragments(fieldState, defaultValue?.[field]));
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const entries = hiddenAwareFragments.filter((d) => d.type === "entry");
@@ -3071,10 +3096,13 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				entries
 			};
 			sections.push(section);
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return {
+				...sourceDocumentation(children, options.hidden),
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			};
 		}
 	};
 	const fieldNormalizers = [];
@@ -4064,12 +4092,17 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return require_mode_dispatch.dispatchIterableByMode(combinedMode, () => suggestTupleSync(context, prefix, syncParsers), () => suggestTupleAsync(context, prefix, parsers));
 		},
 		getDocFragments(state, defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = syncParsers.flatMap((p, i) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[i]
 				};
-				return p.getDocFragments(indexState, defaultValue?.[i]).fragments;
+				return collect(p.getDocFragments(indexState, defaultValue?.[i]));
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
@@ -4083,10 +4116,13 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				entries
 			};
 			sections.push(section);
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return {
+				...sourceDocumentation(children),
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			};
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			const parsersStr = parsers.length === 1 ? `[1 parser]` : `[${parsers.length} parsers]`;
@@ -4422,12 +4458,17 @@ function seq(...rawArgs) {
 			});
 		},
 		getDocFragments(state, defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = syncParsers.flatMap((parser, index) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state.states[index]
 				};
-				return parser.getDocFragments(indexState, defaultValue?.[index]).fragments;
+				return collect(parser.getDocFragments(indexState, defaultValue?.[index]));
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
@@ -4440,10 +4481,13 @@ function seq(...rawArgs) {
 				title: label,
 				entries
 			});
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return {
+				...sourceDocumentation(children),
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			};
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			const parsersStr = parsers.length === 1 ? "1 parser" : `${parsers.length} parsers`;
@@ -5414,6 +5458,11 @@ function merge(...args) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			let brief;
 			let description;
 			let footer;
@@ -5434,7 +5483,7 @@ function merge(...args) {
 				brief ??= docFragments.brief;
 				description ??= docFragments.description;
 				footer ??= docFragments.footer;
-				return docFragments.fragments;
+				return collect(docFragments);
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const entries = hiddenAwareFragments.filter((f) => f.type === "entry");
@@ -5451,6 +5500,7 @@ function merge(...args) {
 				};
 				sections.push(labeledSection);
 				return {
+					...sourceDocumentation(children, options.hidden),
 					brief,
 					description,
 					footer,
@@ -5461,6 +5511,7 @@ function merge(...args) {
 				};
 			}
 			return {
+				...sourceDocumentation(children, options.hidden),
 				brief,
 				description,
 				footer,
@@ -6077,12 +6128,17 @@ function concat(...parsers) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = syncParsers.flatMap((p, index) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[index]
 				};
-				return p.getDocFragments(indexState, void 0).fragments;
+				return collect(p.getDocFragments(indexState, void 0));
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
@@ -6099,7 +6155,10 @@ function concat(...parsers) {
 				type: "section",
 				entries
 			});
-			return { fragments: result };
+			return {
+				...sourceDocumentation(children),
+				fragments: result
+			};
 		}
 	};
 	require_internal_parser.defineInheritedAnnotationParser(concatParser);
@@ -6136,7 +6195,14 @@ function group(label, parser, options = {}) {
 			return parser.suggest(context, prefix);
 		},
 		getDocFragments: (state, defaultValue) => {
-			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
+			const children = [];
+			const collect = (docs$1) => {
+				children.push(docs$1);
+				return docs$1.fragments;
+			};
+			const docs = parser.getDocFragments(state, defaultValue);
+			const { brief, description, footer } = docs;
+			const fragments = collect(docs);
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const allEntries = [];
 			const titledSections = [];
@@ -6160,6 +6226,7 @@ function group(label, parser, options = {}) {
 				entries: allEntries
 			} : { entries: allEntries };
 			return {
+				...sourceDocumentation(children, options.hidden),
 				brief,
 				description,
 				footer,
@@ -7521,11 +7588,17 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			return suggestSync(context, prefix);
 		},
 		getDocFragments(_state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = [];
 			const discriminatorFragments = discriminator.getDocFragments({ kind: "unavailable" }, void 0);
-			fragments.push(...discriminatorFragments.fragments);
+			fragments.push(...collect(discriminatorFragments));
 			for (const [key, branchParser] of branchParsers) {
 				const branchFragments = branchParser.getDocFragments({ kind: "unavailable" }, void 0);
+				children.push(branchFragments);
 				const entries = branchFragments.fragments.filter((f) => f.type === "entry");
 				for (const fragment of branchFragments.fragments) if (fragment.type === "section") entries.push(...fragment.entries);
 				if (entries.length > 0) fragments.push({
@@ -7536,6 +7609,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			}
 			if (defaultBranch !== void 0) {
 				const defaultFragments = defaultBranch.getDocFragments({ kind: "unavailable" }, void 0);
+				children.push(defaultFragments);
 				const entries = defaultFragments.fragments.filter((f) => f.type === "entry");
 				for (const fragment of defaultFragments.fragments) if (fragment.type === "section") entries.push(...fragment.entries);
 				if (entries.length > 0) fragments.push({
@@ -7544,7 +7618,10 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					entries
 				});
 			}
-			return { fragments };
+			return {
+				...sourceDocumentation(children),
+				fragments
+			};
 		}
 	};
 	require_internal_parser.defineInheritedAnnotationParser(conditionalParser);

package/dist/constructs.js

@@ -859,6 +859,14 @@ function applyHiddenToDocEntry(entry, hidden) {
 		term: mergedTerm
 	};
 }
+function sourceDocumentation(children, hidden) {
+	if (isDocHidden(hidden)) return {};
+	const environmentBindings = children.flatMap((docs) => docs.environmentBindings ?? []);
+	return {
+		...environmentBindings.length > 0 && { environmentBindings },
+		...children.length > 0 && children.every((docs) => docs.sourceOnly === true) && { sourceOnly: true }
+	};
+}
 function applyHiddenToDocFragments(fragments, hidden) {
 	if (hidden == null) return fragments;
 	const result = [];
@@ -1835,11 +1843,16 @@ function or(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, combinedMode),
 		getDocFragments(state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			let brief;
 			let description;
 			let footer;
 			let fragments;
-			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }, void 0).fragments);
+			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => collect(p.getDocFragments({ kind: "unavailable" }, void 0)));
 			else {
 				const [index, parserResult] = state.state;
 				const innerState = parserResult.success ? {
@@ -1850,10 +1863,11 @@ function or(...args) {
 				brief = docFragments.brief;
 				description = docFragments.description;
 				footer = docFragments.footer;
-				fragments = docFragments.fragments;
+				fragments = collect(docFragments);
 			}
 			if (state.kind === "unavailable" || state.state == null) fragments = deduplicateDocFragments(fragments);
 			return {
+				...sourceDocumentation(children),
 				brief,
 				description,
 				footer,
@@ -2044,13 +2058,18 @@ function createLongestMatch(...args) {
 		},
 		suggest: createExclusiveSuggest(parsers, combinedMode),
 		getDocFragments(state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			let brief;
 			let description;
 			let footer;
 			let fragments;
 			let shouldDeduplicate;
 			if (state.kind === "unavailable" || state.state == null) {
-				fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+				fragments = parsers.flatMap((p) => collect(p.getDocFragments({ kind: "unavailable" })));
 				shouldDeduplicate = true;
 			} else {
 				const [i, result] = state.state;
@@ -2062,14 +2081,15 @@ function createLongestMatch(...args) {
 					brief = docResult.brief;
 					description = docResult.description;
 					footer = docResult.footer;
-					fragments = docResult.fragments;
+					fragments = collect(docResult);
 					shouldDeduplicate = false;
 				} else {
-					fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+					fragments = parsers.flatMap((p) => collect(p.getDocFragments({ kind: "unavailable" })));
 					shouldDeduplicate = true;
 				}
 			}
 			return {
+				...sourceDocumentation(children),
 				brief,
 				description,
 				fragments: shouldDeduplicate ? deduplicateDocFragments(fragments) : fragments,
@@ -3051,12 +3071,17 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			}, () => suggestObjectAsync(context, prefix, parserPairs));
 		},
 		getDocFragments(state, defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = parserPairs.flatMap(([field, p]) => {
 				const fieldState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[field]
 				};
-				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
+				return collect(p.getDocFragments(fieldState, defaultValue?.[field]));
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const entries = hiddenAwareFragments.filter((d) => d.type === "entry");
@@ -3071,10 +3096,13 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				entries
 			};
 			sections.push(section);
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return {
+				...sourceDocumentation(children, options.hidden),
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			};
 		}
 	};
 	const fieldNormalizers = [];
@@ -4064,12 +4092,17 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return dispatchIterableByMode(combinedMode, () => suggestTupleSync(context, prefix, syncParsers), () => suggestTupleAsync(context, prefix, parsers));
 		},
 		getDocFragments(state, defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = syncParsers.flatMap((p, i) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[i]
 				};
-				return p.getDocFragments(indexState, defaultValue?.[i]).fragments;
+				return collect(p.getDocFragments(indexState, defaultValue?.[i]));
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
@@ -4083,10 +4116,13 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				entries
 			};
 			sections.push(section);
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return {
+				...sourceDocumentation(children),
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			};
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			const parsersStr = parsers.length === 1 ? `[1 parser]` : `[${parsers.length} parsers]`;
@@ -4422,12 +4458,17 @@ function seq(...rawArgs) {
 			});
 		},
 		getDocFragments(state, defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = syncParsers.flatMap((parser, index) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state.states[index]
 				};
-				return parser.getDocFragments(indexState, defaultValue?.[index]).fragments;
+				return collect(parser.getDocFragments(indexState, defaultValue?.[index]));
 			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
@@ -4440,10 +4481,13 @@ function seq(...rawArgs) {
 				title: label,
 				entries
 			});
-			return { fragments: sections.map((s) => ({
-				...s,
-				type: "section"
-			})) };
+			return {
+				...sourceDocumentation(children),
+				fragments: sections.map((s) => ({
+					...s,
+					type: "section"
+				}))
+			};
 		},
 		[Symbol.for("Deno.customInspect")]() {
 			const parsersStr = parsers.length === 1 ? "1 parser" : `${parsers.length} parsers`;
@@ -5414,6 +5458,11 @@ function merge(...args) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			let brief;
 			let description;
 			let footer;
@@ -5434,7 +5483,7 @@ function merge(...args) {
 				brief ??= docFragments.brief;
 				description ??= docFragments.description;
 				footer ??= docFragments.footer;
-				return docFragments.fragments;
+				return collect(docFragments);
 			});
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const entries = hiddenAwareFragments.filter((f) => f.type === "entry");
@@ -5451,6 +5500,7 @@ function merge(...args) {
 				};
 				sections.push(labeledSection);
 				return {
+					...sourceDocumentation(children, options.hidden),
 					brief,
 					description,
 					footer,
@@ -5461,6 +5511,7 @@ function merge(...args) {
 				};
 			}
 			return {
+				...sourceDocumentation(children, options.hidden),
 				brief,
 				description,
 				footer,
@@ -6077,12 +6128,17 @@ function concat(...parsers) {
 			}();
 		},
 		getDocFragments(state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = syncParsers.flatMap((p, index) => {
 				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
 					kind: "available",
 					state: state.state[index]
 				};
-				return p.getDocFragments(indexState, void 0).fragments;
+				return collect(p.getDocFragments(indexState, void 0));
 			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
@@ -6099,7 +6155,10 @@ function concat(...parsers) {
 				type: "section",
 				entries
 			});
-			return { fragments: result };
+			return {
+				...sourceDocumentation(children),
+				fragments: result
+			};
 		}
 	};
 	defineInheritedAnnotationParser(concatParser);
@@ -6136,7 +6195,14 @@ function group(label, parser, options = {}) {
 			return parser.suggest(context, prefix);
 		},
 		getDocFragments: (state, defaultValue) => {
-			const { brief, description, footer, fragments } = parser.getDocFragments(state, defaultValue);
+			const children = [];
+			const collect = (docs$1) => {
+				children.push(docs$1);
+				return docs$1.fragments;
+			};
+			const docs = parser.getDocFragments(state, defaultValue);
+			const { brief, description, footer } = docs;
+			const fragments = collect(docs);
 			const hiddenAwareFragments = applyHiddenToDocFragments(fragments, options.hidden);
 			const allEntries = [];
 			const titledSections = [];
@@ -6160,6 +6226,7 @@ function group(label, parser, options = {}) {
 				entries: allEntries
 			} : { entries: allEntries };
 			return {
+				...sourceDocumentation(children, options.hidden),
 				brief,
 				description,
 				footer,
@@ -7521,11 +7588,17 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			return suggestSync(context, prefix);
 		},
 		getDocFragments(_state, _defaultValue) {
+			const children = [];
+			const collect = (docs) => {
+				children.push(docs);
+				return docs.fragments;
+			};
 			const fragments = [];
 			const discriminatorFragments = discriminator.getDocFragments({ kind: "unavailable" }, void 0);
-			fragments.push(...discriminatorFragments.fragments);
+			fragments.push(...collect(discriminatorFragments));
 			for (const [key, branchParser] of branchParsers) {
 				const branchFragments = branchParser.getDocFragments({ kind: "unavailable" }, void 0);
+				children.push(branchFragments);
 				const entries = branchFragments.fragments.filter((f) => f.type === "entry");
 				for (const fragment of branchFragments.fragments) if (fragment.type === "section") entries.push(...fragment.entries);
 				if (entries.length > 0) fragments.push({
@@ -7536,6 +7609,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			}
 			if (defaultBranch !== void 0) {
 				const defaultFragments = defaultBranch.getDocFragments({ kind: "unavailable" }, void 0);
+				children.push(defaultFragments);
 				const entries = defaultFragments.fragments.filter((f) => f.type === "entry");
 				for (const fragment of defaultFragments.fragments) if (fragment.type === "section") entries.push(...fragment.entries);
 				if (entries.length > 0) fragments.push({
@@ -7544,7 +7618,10 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					entries
 				});
 			}
-			return { fragments };
+			return {
+				...sourceDocumentation(children),
+				fragments
+			};
 		}
 	};
 	defineInheritedAnnotationParser(conditionalParser);

package/dist/doc.cjs

@@ -149,16 +149,17 @@ function cloneDocEntry(entry) {
 * Names are grouped in first-appearance order with references to their
 * associated entries. Empty names and hidden or empty terms are ignored.
 * This does not read environment values or modify the page. Entries without
-* CLI documentation, such as `bindEnv(fail(), ...)`, are not collected.
+* CLI documentation are collected through `environmentBindings`.
 *
 * @param page The documentation page to inspect.
-* @param options An optional heading for the generated section.
+* @param options A heading and optional filter for names without CLI references.
 * @returns A new section, or `undefined` when there are no visible names.
 * @throws {TypeError} If a used title is empty or contains control characters.
 * @since 1.4.0
 */
 function deriveEnvironmentSection(page, options = {}) {
 	const bindings = /* @__PURE__ */ new Map();
+	const purposes = /* @__PURE__ */ new Map();
 	for (const section of page.sections) for (const entry of section.entries) {
 		if (isDocEntryHidden(entry)) continue;
 		const rendered = require_usage.formatUsageTerm(entry.term, { context: "doc" });
@@ -175,18 +176,55 @@ function deriveEnvironmentSection(page, options = {}) {
 			references.set(rendered, reference);
 		}
 	}
-	if (bindings.size === 0) return void 0;
+	for (const binding of page.environmentBindings ?? []) {
+		if (binding.name === "" || require_usage.isDocHidden(binding.hidden)) continue;
+		if (!bindings.has(binding.name)) bindings.set(binding.name, /* @__PURE__ */ new Map());
+		const description = binding.description;
+		if (description == null || description.length === 0) continue;
+		let descriptions = purposes.get(binding.name);
+		if (descriptions == null) {
+			descriptions = /* @__PURE__ */ new Map();
+			purposes.set(binding.name, descriptions);
+		}
+		const key = JSON.stringify(description.map((term) => {
+			switch (term.type) {
+				case "text": return [term.type, term.text];
+				case "optionName": return [term.type, term.optionName];
+				case "optionNames": return [term.type, term.optionNames];
+				case "metavar": return [term.type, term.metavar];
+				case "value": return [term.type, term.value];
+				case "values": return [term.type, term.values];
+				case "envVar": return [term.type, term.envVar];
+				case "commandLine": return [term.type, term.commandLine];
+				case "lineBreak": return [term.type];
+				case "url": return [term.type, term.url.href];
+			}
+		}));
+		descriptions.set(key, description);
+	}
+	const collected = Array.from(bindings).filter(([, references]) => !options.onlyUnreferenced || references.size === 0);
+	if (collected.length === 0) return void 0;
 	const title = options.title ?? "Environment";
 	require_validate.validateLabel(title);
 	return {
 		title,
-		entries: Array.from(bindings, ([name, references]) => ({
-			term: {
-				type: "literal",
-				value: name
-			},
-			description: Array.from(references.values()).flatMap((reference, i) => i === 0 ? reference : [require_message.text(", "), ...reference])
-		}))
+		entries: collected.map(([name, references]) => {
+			const purpose = Array.from(purposes.get(name)?.values() ?? []).flatMap((description$1, i) => i === 0 ? description$1 : [{ type: "lineBreak" }, ...description$1]);
+			const refs = Array.from(references.values()).flatMap((ref, i) => i === 0 ? ref : [require_message.text(", "), ...ref]);
+			const description = purpose.length === 0 ? refs : refs.length === 0 ? purpose : [
+				...purpose,
+				{ type: "lineBreak" },
+				require_message.text("CLI: "),
+				...refs
+			];
+			return {
+				term: {
+					type: "literal",
+					value: name
+				},
+				...description.length > 0 && { description }
+			};
+		})
 	};
 }
 /**
@@ -318,10 +356,13 @@ function formatDocPage(programName, page, options = {}) {
 			return rendered.trim() !== "";
 		})
 	}));
-	const environmentSection = environmentPlacement === "section" || environmentPlacement === "both" ? deriveEnvironmentSection({
+	const environmentSection = environmentPlacement != null ? deriveEnvironmentSection({
 		...page,
 		sections: filteredSections
-	}, { title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0 }) : void 0;
+	}, {
+		onlyUnreferenced: environmentPlacement === "inline",
+		title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0
+	}) : void 0;
 	page = {
 		...page,
 		sections: environmentSection == null ? filteredSections : [...filteredSections, environmentSection]

package/dist/doc.d.cts

@@ -1,6 +1,6 @@
 import { Message, MessageFormatter } from "./message.cjs";
 import { TerminalTheme } from "./terminal.cjs";
-import { Usage, UsageTerm } from "./usage.cjs";
+import { HiddenVisibility, Usage, UsageTerm } from "./usage.cjs";
 
 //#region src/doc.d.ts
 
@@ -49,12 +49,27 @@ interface DocSection {
   readonly title?: string;
   readonly entries: readonly DocEntry[];
 }
+/**
+ * A declared environment binding, independent of CLI documentation entries.
+ * Names describe possible sources, not whether they are read during parsing.
+ * @since 1.4.0
+ */
+interface EnvironmentBindingDoc {
+  /** The full variable name, including any prefix. */
+  readonly name: string;
+  /** Purpose text supplied by the binding author, without inferred values. */
+  readonly description?: Message;
+  /** Visibility in documentation; `"usage"` remains visible. */
+  readonly hidden?: HiddenVisibility;
+}
 /**
  * A document page that contains multiple sections, each with its own brief
  * and a list of entries. This structure is used to organize documentation
  * for commands, options, and other related information.
  */
 interface DocPage {
+  /** Independent environment documentation in this page's scope. @since 1.4.0 */
+  readonly environmentBindings?: readonly EnvironmentBindingDoc[];
   readonly brief?: Message;
   readonly usage?: Usage;
   readonly description?: Message;
@@ -91,6 +106,15 @@ type DocFragment = {
  * a final document page.
  */
 interface DocFragments {
+  /** Independent environment documentation in this scope. @since 1.4.0 */
+  readonly environmentBindings?: readonly EnvironmentBindingDoc[];
+  /**
+   * Positive permission for source-only bindings to document this scope.
+   * Empty fragments alone do not imply this capability. Custom combinators
+   * must preserve it deliberately, respecting scope and hidden parents.
+   * @since 1.4.0
+   */
+  readonly sourceOnly?: true;
   /**
    * An optional brief that provides a short summary for the collection
    * of fragments.
@@ -173,16 +197,17 @@ interface ShowEnvironmentOptions {
  * Names are grouped in first-appearance order with references to their
  * associated entries. Empty names and hidden or empty terms are ignored.
  * This does not read environment values or modify the page. Entries without
- * CLI documentation, such as `bindEnv(fail(), ...)`, are not collected.
+ * CLI documentation are collected through `environmentBindings`.
  *
  * @param page The documentation page to inspect.
- * @param options An optional heading for the generated section.
+ * @param options A heading and optional filter for names without CLI references.
  * @returns A new section, or `undefined` when there are no visible names.
  * @throws {TypeError} If a used title is empty or contains control characters.
  * @since 1.4.0
  */
 declare function deriveEnvironmentSection(page: DocPage, options?: {
   readonly title?: string;
+  readonly onlyUnreferenced?: boolean;
 }): DocSection | undefined;
 /**
  * Configuration for customizing default value display formatting.
@@ -242,7 +267,8 @@ interface ShowChoicesOptions {
 interface DocPageFormatOptions {
   /**
    * Displays declared environment bindings. `true` or `{}` selects inline
-   * annotations; `placement` can select a section or both. Defaults to `false`.
+   * annotations; `placement` can select a section or both. Unreferenced names
+   * get a fallback section in inline mode. Defaults to `false`.
    * Generated sections follow the regular sections, before examples, and are
    * not passed to `sectionOrder`. The original page is not modified.
    * @since 1.4.0
@@ -403,4 +429,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };

package/dist/doc.d.ts

@@ -1,6 +1,6 @@
 import { Message, MessageFormatter } from "./message.js";
 import { TerminalTheme } from "./terminal.js";
-import { Usage, UsageTerm } from "./usage.js";
+import { HiddenVisibility, Usage, UsageTerm } from "./usage.js";
 
 //#region src/doc.d.ts
 
@@ -49,12 +49,27 @@ interface DocSection {
   readonly title?: string;
   readonly entries: readonly DocEntry[];
 }
+/**
+ * A declared environment binding, independent of CLI documentation entries.
+ * Names describe possible sources, not whether they are read during parsing.
+ * @since 1.4.0
+ */
+interface EnvironmentBindingDoc {
+  /** The full variable name, including any prefix. */
+  readonly name: string;
+  /** Purpose text supplied by the binding author, without inferred values. */
+  readonly description?: Message;
+  /** Visibility in documentation; `"usage"` remains visible. */
+  readonly hidden?: HiddenVisibility;
+}
 /**
  * A document page that contains multiple sections, each with its own brief
  * and a list of entries. This structure is used to organize documentation
  * for commands, options, and other related information.
  */
 interface DocPage {
+  /** Independent environment documentation in this page's scope. @since 1.4.0 */
+  readonly environmentBindings?: readonly EnvironmentBindingDoc[];
   readonly brief?: Message;
   readonly usage?: Usage;
   readonly description?: Message;
@@ -91,6 +106,15 @@ type DocFragment = {
  * a final document page.
  */
 interface DocFragments {
+  /** Independent environment documentation in this scope. @since 1.4.0 */
+  readonly environmentBindings?: readonly EnvironmentBindingDoc[];
+  /**
+   * Positive permission for source-only bindings to document this scope.
+   * Empty fragments alone do not imply this capability. Custom combinators
+   * must preserve it deliberately, respecting scope and hidden parents.
+   * @since 1.4.0
+   */
+  readonly sourceOnly?: true;
   /**
    * An optional brief that provides a short summary for the collection
    * of fragments.
@@ -173,16 +197,17 @@ interface ShowEnvironmentOptions {
  * Names are grouped in first-appearance order with references to their
  * associated entries. Empty names and hidden or empty terms are ignored.
  * This does not read environment values or modify the page. Entries without
- * CLI documentation, such as `bindEnv(fail(), ...)`, are not collected.
+ * CLI documentation are collected through `environmentBindings`.
  *
  * @param page The documentation page to inspect.
- * @param options An optional heading for the generated section.
+ * @param options A heading and optional filter for names without CLI references.
  * @returns A new section, or `undefined` when there are no visible names.
  * @throws {TypeError} If a used title is empty or contains control characters.
  * @since 1.4.0
  */
 declare function deriveEnvironmentSection(page: DocPage, options?: {
   readonly title?: string;
+  readonly onlyUnreferenced?: boolean;
 }): DocSection | undefined;
 /**
  * Configuration for customizing default value display formatting.
@@ -242,7 +267,8 @@ interface ShowChoicesOptions {
 interface DocPageFormatOptions {
   /**
    * Displays declared environment bindings. `true` or `{}` selects inline
-   * annotations; `placement` can select a section or both. Defaults to `false`.
+   * annotations; `placement` can select a section or both. Unreferenced names
+   * get a fallback section in inline mode. Defaults to `false`.
    * Generated sections follow the regular sections, before examples, and are
    * not passed to `sectionOrder`. The original page is not modified.
    * @since 1.4.0
@@ -403,4 +429,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden };

package/dist/doc.js

@@ -149,16 +149,17 @@ function cloneDocEntry(entry) {
 * Names are grouped in first-appearance order with references to their
 * associated entries. Empty names and hidden or empty terms are ignored.
 * This does not read environment values or modify the page. Entries without
-* CLI documentation, such as `bindEnv(fail(), ...)`, are not collected.
+* CLI documentation are collected through `environmentBindings`.
 *
 * @param page The documentation page to inspect.
-* @param options An optional heading for the generated section.
+* @param options A heading and optional filter for names without CLI references.
 * @returns A new section, or `undefined` when there are no visible names.
 * @throws {TypeError} If a used title is empty or contains control characters.
 * @since 1.4.0
 */
 function deriveEnvironmentSection(page, options = {}) {
 	const bindings = /* @__PURE__ */ new Map();
+	const purposes = /* @__PURE__ */ new Map();
 	for (const section of page.sections) for (const entry of section.entries) {
 		if (isDocEntryHidden(entry)) continue;
 		const rendered = formatUsageTerm(entry.term, { context: "doc" });
@@ -175,18 +176,55 @@ function deriveEnvironmentSection(page, options = {}) {
 			references.set(rendered, reference);
 		}
 	}
-	if (bindings.size === 0) return void 0;
+	for (const binding of page.environmentBindings ?? []) {
+		if (binding.name === "" || isDocHidden(binding.hidden)) continue;
+		if (!bindings.has(binding.name)) bindings.set(binding.name, /* @__PURE__ */ new Map());
+		const description = binding.description;
+		if (description == null || description.length === 0) continue;
+		let descriptions = purposes.get(binding.name);
+		if (descriptions == null) {
+			descriptions = /* @__PURE__ */ new Map();
+			purposes.set(binding.name, descriptions);
+		}
+		const key = JSON.stringify(description.map((term) => {
+			switch (term.type) {
+				case "text": return [term.type, term.text];
+				case "optionName": return [term.type, term.optionName];
+				case "optionNames": return [term.type, term.optionNames];
+				case "metavar": return [term.type, term.metavar];
+				case "value": return [term.type, term.value];
+				case "values": return [term.type, term.values];
+				case "envVar": return [term.type, term.envVar];
+				case "commandLine": return [term.type, term.commandLine];
+				case "lineBreak": return [term.type];
+				case "url": return [term.type, term.url.href];
+			}
+		}));
+		descriptions.set(key, description);
+	}
+	const collected = Array.from(bindings).filter(([, references]) => !options.onlyUnreferenced || references.size === 0);
+	if (collected.length === 0) return void 0;
 	const title = options.title ?? "Environment";
 	validateLabel(title);
 	return {
 		title,
-		entries: Array.from(bindings, ([name, references]) => ({
-			term: {
-				type: "literal",
-				value: name
-			},
-			description: Array.from(references.values()).flatMap((reference, i) => i === 0 ? reference : [text(", "), ...reference])
-		}))
+		entries: collected.map(([name, references]) => {
+			const purpose = Array.from(purposes.get(name)?.values() ?? []).flatMap((description$1, i) => i === 0 ? description$1 : [{ type: "lineBreak" }, ...description$1]);
+			const refs = Array.from(references.values()).flatMap((ref, i) => i === 0 ? ref : [text(", "), ...ref]);
+			const description = purpose.length === 0 ? refs : refs.length === 0 ? purpose : [
+				...purpose,
+				{ type: "lineBreak" },
+				text("CLI: "),
+				...refs
+			];
+			return {
+				term: {
+					type: "literal",
+					value: name
+				},
+				...description.length > 0 && { description }
+			};
+		})
 	};
 }
 /**
@@ -318,10 +356,13 @@ function formatDocPage(programName, page, options = {}) {
 			return rendered.trim() !== "";
 		})
 	}));
-	const environmentSection = environmentPlacement === "section" || environmentPlacement === "both" ? deriveEnvironmentSection({
+	const environmentSection = environmentPlacement != null ? deriveEnvironmentSection({
 		...page,
 		sections: filteredSections
-	}, { title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0 }) : void 0;
+	}, {
+		onlyUnreferenced: environmentPlacement === "inline",
+		title: typeof options.showEnvironment === "object" ? options.showEnvironment.sectionTitle : void 0
+	}) : void 0;
 	page = {
 		...page,
 		sections: environmentSection == null ? filteredSections : [...filteredSections, environmentSection]

package/dist/facade.d.cts

@@ -150,7 +150,8 @@ interface RunOptions<THelp, TError> {
   readonly showChoices?: boolean | ShowChoicesOptions;
   /**
    * Displays declared environment bindings in help. `true` selects inline
-   * annotations; an object can select a section or both. Defaults to `false`.
+   * annotations; an object can select a section or both. Names without visible
+   * CLI references get a fallback section even in inline mode. Defaults to `false`.
    * Also applies to full help above errors. @since 1.4.0
    */
   readonly showEnvironment?: boolean | ShowEnvironmentOptions;

package/dist/facade.d.ts

@@ -150,7 +150,8 @@ interface RunOptions<THelp, TError> {
   readonly showChoices?: boolean | ShowChoicesOptions;
   /**
    * Displays declared environment bindings in help. `true` selects inline
-   * annotations; an object can select a section or both. Defaults to `false`.
+   * annotations; an object can select a section or both. Names without visible
+   * CLI references get a fallback section even in inline mode. Defaults to `false`.
    * Also applies to full help above errors. @since 1.4.0
    */
   readonly showEnvironment?: boolean | ShowEnvironmentOptions;

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.cjs";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOptions, MessageTerm, ValueSetOptions, commandLine, createMessageFormatter, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.js";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, EnvironmentBindingDoc, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/internal/parser.cjs

@@ -859,7 +859,7 @@ async function getDocPageAsyncImpl(parser, args, options) {
 */
 function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	let effectiveArgs = args;
-	let { brief, description, fragments, footer } = parser.getDocFragments({
+	let { brief, description, fragments, footer, environmentBindings } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
@@ -870,7 +870,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 			kind: "available",
 			state: matchedState
 		}, void 0);
-		({brief, description, fragments, footer} = matched);
+		({brief, description, fragments, footer, environmentBindings} = matched);
 		effectiveArgs = [cmdName];
 	}
 	const buildingSections = [];
@@ -944,7 +944,12 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 			usage.splice(1, usage.length - 1, ...normalizedCustomUsageLine);
 		}
 	}
+	const visibleBindings = environmentBindings?.filter((binding) => !require_usage.isDocHidden(binding.hidden)).map((binding) => ({
+		...binding,
+		...binding.description != null && { description: require_message.cloneMessage(binding.description) }
+	}));
 	return {
+		...visibleBindings != null && visibleBindings.length > 0 && { environmentBindings: visibleBindings },
 		usage: revealMatchedCommandUsage(usage, effectiveArgs, commandArgIndices ?? null),
 		sections,
 		...brief != null && { brief: require_message.cloneMessage(brief) },

package/dist/internal/parser.js

@@ -1,5 +1,5 @@
 import { hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
-import { cloneUsage, normalizeUsage } from "../usage.js";
+import { cloneUsage, isDocHidden, normalizeUsage } from "../usage.js";
 import { cloneMessage, message } from "../message.js";
 import { cloneDocEntry, isDocEntryHidden } from "../doc.js";
 import { dispatchByMode, dispatchParserByMode } from "./mode-dispatch.js";
@@ -859,7 +859,7 @@ async function getDocPageAsyncImpl(parser, args, options) {
 */
 function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 	let effectiveArgs = args;
-	let { brief, description, fragments, footer } = parser.getDocFragments({
+	let { brief, description, fragments, footer, environmentBindings } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
@@ -870,7 +870,7 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 			kind: "available",
 			state: matchedState
 		}, void 0);
-		({brief, description, fragments, footer} = matched);
+		({brief, description, fragments, footer, environmentBindings} = matched);
 		effectiveArgs = [cmdName];
 	}
 	const buildingSections = [];
@@ -944,7 +944,12 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 			usage.splice(1, usage.length - 1, ...normalizedCustomUsageLine);
 		}
 	}
+	const visibleBindings = environmentBindings?.filter((binding) => !isDocHidden(binding.hidden)).map((binding) => ({
+		...binding,
+		...binding.description != null && { description: cloneMessage(binding.description) }
+	}));
 	return {
+		...visibleBindings != null && visibleBindings.length > 0 && { environmentBindings: visibleBindings },
 		usage: revealMatchedCommandUsage(usage, effectiveArgs, commandArgIndices ?? null),
 		sections,
 		...brief != null && { brief: cloneMessage(brief) },

package/dist/primitives.cjs

@@ -149,7 +149,10 @@ function constant(value) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			return { fragments: [] };
+			return {
+				fragments: [],
+				sourceOnly: true
+			};
 		}
 	};
 	Object.defineProperty(result, "placeholder", {
@@ -209,7 +212,10 @@ function fail() {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			return { fragments: [] };
+			return {
+				fragments: [],
+				sourceOnly: true
+			};
 		}
 	});
 }

package/dist/primitives.js

@@ -149,7 +149,10 @@ function constant(value) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			return { fragments: [] };
+			return {
+				fragments: [],
+				sourceOnly: true
+			};
 		}
 	};
 	Object.defineProperty(result, "placeholder", {
@@ -209,7 +212,10 @@ function fail() {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
-			return { fragments: [] };
+			return {
+				fragments: [],
+				sourceOnly: true
+			};
 		}
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2631",
+  "version": "1.4.0-dev.2634",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2631+0f2bd6a0",
+    "@optique/env": "1.4.0-dev.2634+1d7c26e6",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -248,7 +248,7 @@ Common mistakes checklist
  -  Use structured `message` values for errors and descriptions.
  -  Register contexts for `bindEnv()`, `bindConfig()`, `bindDerivedDefault()`,
     and `bindKeyring()` in the runner's `contexts` option.
- -  Show `bindEnv()` names in help with `showEnvironment: true`.
+ -  Enable `showEnvironment` for env-only help; set `documentation.description`.
  -  Do not flatten a multi-level dependency graph into duplicated one-level
     factories. Wrap each derived value that becomes a later source with
     `dependency()` and derive the next parser from it.