@orkestrel/brief 0.0.6 → 0.0.7

package/dist/src/core/index.js

@@ -1,9 +1,9 @@
 import { andOf, arrayOf, arrayShape, attempt, booleanShape, boundsOf, cloneJSONRecord, createContract, integerShape, isBoolean, isInteger, isNonEmptyString, isString, literalOf, literalShape, objectShape, optionalShape, parseJSONAs, recordOf, stringShape } from "@orkestrel/contract";
 import { canonicalize, collapseWhitespace, createInterpret, digestValue, isInterpretation } from "@orkestrel/interpret";
-import { atom, compound, createLogicalReasoner, createReason, formatField, isLogicalResult, logicalDefinition, rule } from "@orkestrel/reason";
+import { createAtom, createCompound, createLogicalDefinition, createLogicalReasoner, createReason, createRule, formatField, isLogicalResult } from "@orkestrel/reason";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
-/** The twelve `TaskOperation` values, frozen. */
+/** Lists the `TaskOperation` values, frozen. */
 var TASK_OPERATIONS = Object.freeze([
 	"create",
 	"refactor",
@@ -18,7 +18,7 @@ var TASK_OPERATIONS = Object.freeze([
 	"document",
 	"plan"
 ]);
-/** The eight `TaskDomain` values, frozen. */
+/** Lists the `TaskDomain` values, frozen. */
 var TASK_DOMAINS = Object.freeze([
 	"code",
 	"writing",
@@ -29,7 +29,7 @@ var TASK_DOMAINS = Object.freeze([
 	"ops",
 	"other"
 ]);
-/** The five `OutputFormat` values, frozen. */
+/** Lists the `OutputFormat` values, frozen. */
 var OUTPUT_FORMATS = Object.freeze([
 	"markdown",
 	"json",
@@ -37,14 +37,14 @@ var OUTPUT_FORMATS = Object.freeze([
 	"diff",
 	"prose"
 ]);
-/** The three `RiskSeverity` values, frozen. */
+/** Lists the `RiskSeverity` values, frozen. */
 var RISK_SEVERITIES = Object.freeze([
 	"low",
 	"medium",
 	"high"
 ]);
 /**
-* Every published `Interpretation` member name, frozen.
+* Lists every published `Interpretation` member name, frozen.
 *
 * @remarks
 * The capture list `BriefCompiler` hands `captureValue` at each interpret door — the borrowed
@@ -69,33 +69,32 @@ var INTERPRETATION_MEMBERS = Object.freeze([
 	"prompt",
 	"stages",
 	"failures",
-	"complete",
 	"confidence",
 	"digest"
 ]);
 /**
-* `16` — the default turn cap `briefToGoal` renders.
+* Holds `16` — the default turn cap `briefToGoal` renders.
 *
 * @remarks
 * Domain-qualified so the barrel stays collision-free as sibling modules add their own
 * turn defaults.
 */
 var DEFAULT_BRIEF_TURNS = 16;
-/** `'gate'` — the id of the `gateDefinition()` logical definition. */
+/** Holds `'gate'` — the id of the `buildGateDefinition()` logical definition. */
 var GATE_ID = "gate";
 /**
-* Every line terminator a brief field refuses.
+* Matches every line terminator a brief field refuses.
 *
 * @remarks
-* The four ECMAScript line terminators, not just `\n`: a renderer that splits on any of
-* them would let the other three forge a markdown row. CRLF leads the alternation so a
-* Windows exemplar splits as ONE break rather than two, which would insert a blank line the
-* caller never wrote. Kept unanchored and stateless — no `g` flag — so `test` never carries
+* Every ECMAScript line terminator, not just `\n`: a renderer that splits on any of them
+* would let the others forge a markdown row. CRLF leads the alternation so a Windows
+* exemplar splits as ONE break rather than two, which would insert a blank line the caller
+* never wrote. Kept unanchored and stateless — no `g` flag — so `test` never carries
 * `lastIndex` between calls.
 */
 var LINE_BREAK_PATTERN = /\r\n|[\n\r\u2028\u2029]/;
 /**
-* The positive form of {@link LINE_BREAK_PATTERN}, for the shape DSL.
+* Holds the positive form of {@link LINE_BREAK_PATTERN}, for the shape DSL.
 *
 * @remarks
 * `stringShape`'s `pattern` must MATCH an accepted value, so the guard's refusal regex
@@ -104,7 +103,7 @@ var LINE_BREAK_PATTERN = /\r\n|[\n\r\u2028\u2029]/;
 */
 var SINGLE_LINE_PATTERN = /^[^\n\r\u2028\u2029]*$/;
 /**
-* A string of one or more spaces and nothing else.
+* Matches a string of one or more spaces and nothing else.
 *
 * @remarks
 * The one exemplar side `exampleToLines` must NOT pad. CommonMark strips a fully-blank code
@@ -118,7 +117,7 @@ var BLANK_PATTERN = /^ +$/;
 //#endregion
 //#region src/core/errors.ts
 /**
-* The one error class this package throws.
+* Represents the one error class this package throws.
 *
 * @remarks
 * Throws are reserved for caller misuse: `assertBrief`, `snapshotBrief`, and `pinBrief` on
@@ -148,10 +147,10 @@ var BriefError = class extends Error {
 	}
 };
 /**
-* Narrow a caught value to a {@link BriefError}.
+* Narrows a caught value to a {@link BriefError}.
 *
 * @param value - The caught value to inspect.
-* @returns `true` when `value` is a `BriefError`.
+* @returns True if `value` is a `BriefError`; false otherwise.
 *
 * @example
 * ```ts
@@ -169,82 +168,82 @@ function isBriefError(value) {
 }
 //#endregion
 //#region src/core/shapers.ts
-/** A single-line string of any length, including empty. */
+/** Describes a single-line string of any length, including empty. */
 var textShape = stringShape({ pattern: SINGLE_LINE_PATTERN });
-/** A non-empty single-line string — the shape mirror of `isLine`. */
+/** Describes a non-empty single-line string — the shape mirror of `isLine`. */
 var lineShape = stringShape({
 	min: 1,
 	pattern: SINGLE_LINE_PATTERN
 });
-/** The `Task` shape — closed operation and domain vocabularies plus a non-empty statement. */
+/** Describes the `Task` shape — closed operation and domain vocabularies plus a non-empty statement. */
 var taskShape = objectShape({
 	operation: literalShape(TASK_OPERATIONS),
 	domain: literalShape(TASK_DOMAINS),
 	statement: lineShape
 }, { description: "What the brief asks for, in one imperative sentence." });
-/** The `Reference` shape — a path and the note that justifies listing it. */
+/** Describes the `Reference` shape — a path and the note that justifies listing it. */
 var referenceShape = objectShape({
 	path: lineShape,
 	note: lineShape
 }, { description: "One referenced path and why it is listed." });
-/** The `Manifest` shape — four disjoint reference partitions. */
+/** Describes the `Manifest` shape — disjoint reference partitions. */
 var manifestShape = objectShape({
 	read: arrayShape(referenceShape),
 	edit: arrayShape(referenceShape),
 	locked: arrayShape(referenceShape),
 	forbidden: arrayShape(referenceShape)
-}, { description: "The four disjoint file partitions of a brief." });
-/** The `Outcome` shape — a one-based rank, the result text, and whether it gates done. */
+}, { description: "The disjoint file partitions of a brief." });
+/** Describes the `Outcome` shape — a one-based rank, the result text, and whether it gates done. */
 var outcomeShape = objectShape({
 	rank: integerShape({ min: 1 }),
 	text: lineShape,
 	required: booleanShape()
 }, { description: "One ranked outcome — a result, never a step." });
-/** The `Given` shape — one categorized context fact. */
+/** Describes the `Given` shape — one categorized context fact. */
 var givenShape = objectShape({
 	category: lineShape,
 	name: lineShape,
 	value: textShape
 }, { description: "One context fact handed to the executor." });
-/** The `Example` shape — one input to output exemplar. */
+/** Describes the `Example` shape — one input to output exemplar. */
 var exampleShape = objectShape({
 	input: stringShape({ min: 1 }),
 	output: stringShape({ min: 1 }),
 	note: optionalShape(lineShape)
 }, { description: "One input to output exemplar." });
-/** The `Citation` shape — a name, a locator, and why the source is cited. */
+/** Describes the `Citation` shape — a name, a locator, and why the source is cited. */
 var citationShape = objectShape({
 	name: lineShape,
 	url: lineShape,
 	note: lineShape
 }, { description: "One external source; list order is the trust order." });
-/** The `Gap` shape — an unknown, whether it blocks, and the candidates that would close it. */
+/** Describes the `Gap` shape — an unknown, whether it blocks, and the candidates that would close it. */
 var gapShape = objectShape({
 	field: lineShape,
 	question: lineShape,
 	blocking: booleanShape(),
 	candidates: optionalShape(arrayShape(lineShape))
 }, { description: "One unresolved decision; blocking means the gate fails closed." });
-/** The `Risk` shape — a closed severity, the risk, and its mitigation. */
+/** Describes the `Risk` shape — a closed severity, the risk, and its mitigation. */
 var riskShape = objectShape({
 	severity: literalShape(RISK_SEVERITIES),
 	text: lineShape,
 	mitigation: lineShape
 }, { description: "One pre-empted risk and the mitigation that answers it." });
-/** The `Output` shape — a closed format plus its optional refinements. */
+/** Describes the `Output` shape — a closed format plus its optional refinements. */
 var outputShape = objectShape({
 	format: literalShape(OUTPUT_FORMATS),
 	sections: optionalShape(arrayShape(lineShape)),
 	include: optionalShape(arrayShape(lineShape)),
 	exclude: optionalShape(arrayShape(lineShape))
 }, { description: "The closed shape of the deliverable." });
-/** The `Proof` shape — the claim and the command that settles it. */
+/** Describes the `Proof` shape — the claim and the command that settles it. */
 var proofShape = objectShape({
 	text: lineShape,
 	command: lineShape
 }, { description: "One mechanical, transcript-provable check." });
 /**
-* The whole `Brief` shape, section shapes composed.
+* Describes the whole `Brief` shape, section shapes composed.
 *
 * @remarks
 * `trace` and `hash` are optional because `pinBrief` fills them; an unpinned draft is
@@ -271,40 +270,82 @@ var briefShape = objectShape({
 //#endregion
 //#region src/core/validators.ts
 /**
-* `true` when the value is a string holding no line terminator, empty included.
+* Checks whether the value is a string holding no line terminator, empty included.
 *
 * @remarks
 * `briefToMarkdown` renders each brief field as ONE markdown row, so a field carrying a
 * line break would forge a heading or an extra manifest row — which is how a rendered
 * prompt and `briefToDispatch`'s path sets could disagree about the same brief.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a string holding no line terminator, empty included; false
+*   otherwise.
 */
 var isText = (value) => isString(value) && !LINE_BREAK_PATTERN.test(value);
-/** `true` when the value is a non-empty string holding no line terminator. */
+/**
+* Checks whether the value is a non-empty string holding no line terminator.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a non-empty string holding no line terminator; false otherwise.
+*/
 var isLine = andOf(isNonEmptyString, isText);
-/** `true` when the value is one of the twelve `TaskOperation` literals. */
+/**
+* Checks whether the value is one of the `TaskOperation` literals.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is one of the `TaskOperation` literals; false otherwise.
+*/
 var isTaskOperation = literalOf(TASK_OPERATIONS);
-/** `true` when the value is one of the eight `TaskDomain` literals. */
+/**
+* Checks whether the value is one of the `TaskDomain` literals.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is one of the `TaskDomain` literals; false otherwise.
+*/
 var isTaskDomain = literalOf(TASK_DOMAINS);
-/** `true` when the value is one of the five `OutputFormat` literals. */
+/**
+* Checks whether the value is one of the `OutputFormat` literals.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is one of the `OutputFormat` literals; false otherwise.
+*/
 var isOutputFormat = literalOf(OUTPUT_FORMATS);
-/** `true` when the value is one of the three `RiskSeverity` literals. */
+/**
+* Checks whether the value is one of the `RiskSeverity` literals.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is one of the `RiskSeverity` literals; false otherwise.
+*/
 var isRiskSeverity = literalOf(RISK_SEVERITIES);
-/** `true` when the value is a well-formed `Task` — both vocabularies closed, statement one line. */
+/**
+* Checks whether the value is a well-formed `Task` — both vocabularies closed, statement one line.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Task`; false otherwise.
+*/
 var isTask = recordOf({
 	operation: isTaskOperation,
 	domain: isTaskDomain,
 	statement: isLine
 });
-/** `true` when the value is a well-formed `Reference` — both members required, both single-line. */
+/**
+* Checks whether the value is a well-formed `Reference` — both members required, both single-line.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Reference`; false otherwise.
+*/
 var isReference = recordOf({
 	path: isLine,
 	note: isLine
 });
 /**
-* `true` when the value is a well-formed `Manifest`.
+* Checks whether the value is a well-formed `Manifest`.
 *
 * @remarks
 * Partition presence only — disjointness is `validateBrief`'s semantic pass.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Manifest`; false otherwise.
 */
 var isManifest = recordOf({
 	read: arrayOf(isReference),
@@ -312,50 +353,83 @@ var isManifest = recordOf({
 	locked: arrayOf(isReference),
 	forbidden: arrayOf(isReference)
 });
-/** `true` when the value is a well-formed `Outcome` — `rank` a positive integer. */
+/**
+* Checks whether the value is a well-formed `Outcome` — `rank` a positive integer.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Outcome`; false otherwise.
+*/
 var isOutcome = recordOf({
 	rank: andOf(isInteger, boundsOf(1)),
 	text: isLine,
 	required: isBoolean
 });
-/** `true` when the value is a well-formed `Given` — `value` may be empty but stays one line. */
+/**
+* Checks whether the value is a well-formed `Given` — its `value` may be empty but stays one line.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Given`; false otherwise.
+*/
 var isGiven = recordOf({
 	category: isLine,
 	name: isLine,
 	value: isText
 });
 /**
-* `true` when the value is a well-formed `Example`.
+* Checks whether the value is a well-formed `Example`.
 *
 * @remarks
 * An exemplar's two sides are the ONLY members a brief lets span lines, because they
 * carry code. `briefToMarkdown` fences them rather than rendering them as a row.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Example`; false otherwise.
 */
 var isExample = recordOf({
 	input: isNonEmptyString,
 	output: isNonEmptyString,
 	note: isLine
 }, ["note"]);
-/** `true` when the value is a well-formed `Citation` — all three members single-line. */
+/**
+* Checks whether the value is a well-formed `Citation` — every member single-line.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Citation`; false otherwise.
+*/
 var isCitation = recordOf({
 	name: isLine,
 	url: isLine,
 	note: isLine
 });
-/** `true` when the value is a well-formed `Gap`. */
+/**
+* Checks whether the value is a well-formed `Gap`.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Gap`; false otherwise.
+*/
 var isGap = recordOf({
 	field: isLine,
 	question: isLine,
 	blocking: isBoolean,
 	candidates: arrayOf(isLine)
 }, ["candidates"]);
-/** `true` when the value is a well-formed `Risk` — `severity` on the closed vocabulary. */
+/**
+* Checks whether the value is a well-formed `Risk` — `severity` on the closed vocabulary.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Risk`; false otherwise.
+*/
 var isRisk = recordOf({
 	severity: isRiskSeverity,
 	text: isLine,
 	mitigation: isLine
 });
-/** `true` when the value is a well-formed `Output` — `format` on the closed vocabulary. */
+/**
+* Checks whether the value is a well-formed `Output` — `format` on the closed vocabulary.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Output`; false otherwise.
+*/
 var isOutput = recordOf({
 	format: isOutputFormat,
 	sections: arrayOf(isLine),
@@ -366,17 +440,25 @@ var isOutput = recordOf({
 	"include",
 	"exclude"
 ]);
-/** `true` when the value is a well-formed `Proof`. */
+/**
+* Checks whether the value is a well-formed `Proof`.
+*
+* @param value - The value to inspect.
+* @returns True if `value` is a well-formed `Proof`; false otherwise.
+*/
 var isProof = recordOf({
 	text: isLine,
 	command: isLine
 });
 /**
-* `true` when the value satisfies the whole exact-record `Brief` contract.
+* Checks whether the value satisfies the whole exact-record `Brief` contract.
 *
 * @remarks
 * Every section must be present; an extra key fails. `trace` and `hash` are the only
 * optional members, because `pinBrief` rather than the author fills them.
+*
+* @param value - The value to inspect.
+* @returns True if `value` satisfies the whole exact-record `Brief` contract; false otherwise.
 */
 var isBrief = recordOf({
 	task: isTask,
@@ -477,7 +559,7 @@ function captureValue(source, members) {
 	return target;
 }
 /**
-* Return a deeply owned, deeply frozen copy of a brief, refusing anything off-contract.
+* Returns a deeply owned, deeply frozen copy of a brief, refusing anything off-contract.
 *
 * @remarks
 * The one reading boundary this package has, used by the pin, the registry, and every
@@ -501,10 +583,10 @@ function captureValue(source, members) {
 *
 * @example
 * ```ts
-* import { brief, outcome, snapshotBrief, task } from '@orkestrel/brief'
+* import { buildBrief, buildOutcome, buildTask, snapshotBrief } from '@orkestrel/brief'
 *
-* const outcomes = [outcome(1, 'shipped')]
-* const owned = snapshotBrief(brief(task('plan', 'ops', 'Plan the release.'), { outcomes }))
+* const outcomes = [buildOutcome(1, 'shipped')]
+* const owned = snapshotBrief(buildBrief(buildTask('plan', 'ops', 'Plan the release.'), { outcomes }))
 * owned.outcomes === outcomes // false — the alias is broken
 * Object.isFrozen(owned.outcomes) // true
 * ```
@@ -517,7 +599,7 @@ function snapshotBrief(source) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Build a `Task`.
+* Assembles a `Task` from an operation, a domain, and a statement.
 *
 * @param operation - What the brief asks for, from the closed operation vocabulary.
 * @param domain - The subject matter, from the closed domain vocabulary.
@@ -526,12 +608,12 @@ function snapshotBrief(source) {
 *
 * @example
 * ```ts
-* import { task } from '@orkestrel/brief'
+* import { buildTask } from '@orkestrel/brief'
 *
-* task('refactor', 'code', 'Refactor useForm to native browser form APIs.')
+* buildTask('refactor', 'code', 'Refactor useForm to native browser form APIs.')
 * ```
 */
-function task(operation, domain, statement) {
+function buildTask(operation, domain, statement) {
 	return {
 		operation,
 		domain,
@@ -539,7 +621,7 @@ function task(operation, domain, statement) {
 	};
 }
 /**
-* Build a `Reference`.
+* Assembles a `Reference` from a path and the note that justifies listing it.
 *
 * @param path - The referenced path or glob.
 * @param note - Why the path is listed.
@@ -547,31 +629,31 @@ function task(operation, domain, statement) {
 *
 * @example
 * ```ts
-* import { reference } from '@orkestrel/brief'
+* import { buildReference } from '@orkestrel/brief'
 *
-* reference('AGENTS.md', 'project law') // { path: 'AGENTS.md', note: 'project law' }
+* buildReference('AGENTS.md', 'project law') // { path: 'AGENTS.md', note: 'project law' }
 * ```
 */
-function reference(path, note) {
+function buildReference(path, note) {
 	return {
 		path,
 		note
 	};
 }
 /**
-* Build a `Manifest`, defaulting every absent partition to an empty list.
+* Assembles a `Manifest`, defaulting every absent partition to an empty list.
 *
 * @param partitions - The partitions to fill; a partial literal is enough.
-* @returns A fresh `Manifest` with all four partitions present.
+* @returns A fresh `Manifest` with every partition present.
 *
 * @example
 * ```ts
-* import { manifest, reference } from '@orkestrel/brief'
+* import { buildManifest, buildReference } from '@orkestrel/brief'
 *
-* manifest({ edit: [reference('src/core/helpers.ts', 'implementation')] })
+* buildManifest({ edit: [buildReference('src/core/helpers.ts', 'implementation')] })
 * ```
 */
-function manifest(partitions) {
+function buildManifest(partitions) {
 	return {
 		read: partitions?.read ?? [],
 		edit: partitions?.edit ?? [],
@@ -580,22 +662,23 @@ function manifest(partitions) {
 	};
 }
 /**
-* Build an `Outcome`.
+* Assembles an `Outcome` from a rank and its result text.
 *
 * @param rank - The one-based rank; lower ranks matter more.
 * @param text - The result, never a step.
-* @param required - Whether the outcome gates "done"; defaults to `true`.
+* @param required - If `true`, the outcome gates "done"; if `false`, it is desirable but not
+*   blocking. Default: `true`.
 * @returns A fresh `Outcome`.
 *
 * @example
 * ```ts
-* import { outcome } from '@orkestrel/brief'
+* import { buildOutcome } from '@orkestrel/brief'
 *
-* outcome(1, 'useForm uses native FormData with no behavior change') // required: true
-* outcome(2, 'the diff stays under 200 lines', false)
+* buildOutcome(1, 'useForm uses native FormData with no behavior change') // required: true
+* buildOutcome(2, 'the diff stays under 200 lines', false)
 * ```
 */
-function outcome(rank, text, required = true) {
+function buildOutcome(rank, text, required = true) {
 	return {
 		rank,
 		text,
@@ -603,7 +686,7 @@ function outcome(rank, text, required = true) {
 	};
 }
 /**
-* Build a `Given`.
+* Assembles a `Given` from a category, a name, and a value.
 *
 * @param category - The kind of fact — a convention, a version, a constraint.
 * @param name - The fact's name.
@@ -612,12 +695,12 @@ function outcome(rank, text, required = true) {
 *
 * @example
 * ```ts
-* import { given } from '@orkestrel/brief'
+* import { buildGiven } from '@orkestrel/brief'
 *
-* given('convention', 'indentation', 'tabs')
+* buildGiven('convention', 'indentation', 'tabs')
 * ```
 */
-function given(category, name, value) {
+function buildGiven(category, name, value) {
 	return {
 		category,
 		name,
@@ -625,32 +708,32 @@ function given(category, name, value) {
 	};
 }
 /**
-* Build an `Example`.
+* Assembles an `Example` from an exemplar input and its expected output.
 *
 * @param input - The exemplar input.
-* @param result - The expected output for that input.
+* @param output - The expected output for that input.
 * @param note - Optional detail; the key is OMITTED when absent.
 * @returns A fresh `Example`.
 *
 * @example
 * ```ts
-* import { example } from '@orkestrel/brief'
+* import { buildExample } from '@orkestrel/brief'
 *
-* example('<input required>', 'validity read from el.validity')
+* buildExample('<input required>', 'validity read from el.validity')
 * ```
 */
-function example(input, result, note) {
+function buildExample(input, output, note) {
 	return note === void 0 ? {
 		input,
-		output: result
+		output
 	} : {
 		input,
-		output: result,
+		output,
 		note
 	};
 }
 /**
-* Build a `Citation`.
+* Assembles a `Citation` from a name, a URL, and the note that justifies citing it.
 *
 * @param name - The source's display name.
 * @param url - Where the source lives.
@@ -659,16 +742,16 @@ function example(input, result, note) {
 *
 * @example
 * ```ts
-* import { citation } from '@orkestrel/brief'
+* import { buildCitation } from '@orkestrel/brief'
 *
-* citation(
+* buildCitation(
 * 	'MDN Constraint Validation',
 * 	'https://developer.mozilla.org/',
 * 	'the native validity behavior being adopted',
 * )
 * ```
 */
-function citation(name, url, note) {
+function buildCitation(name, url, note) {
 	return {
 		name,
 		url,
@@ -676,23 +759,23 @@ function citation(name, url, note) {
 	};
 }
 /**
-* Build a `Gap`.
+* Assembles a `Gap` from the section it belongs to and the question that would close it.
 *
 * @param field - The brief section the unknown belongs to.
 * @param question - The question that would close it.
-* @param overrides - Optional `blocking` (defaults `false`) and `candidates`; an absent
-*   `candidates` key is OMITTED entirely.
+* @param overrides - Optional `blocking` and `candidates`; an absent `candidates` key is
+*   OMITTED entirely. Default: `blocking: false`.
 * @returns A fresh `Gap`.
 *
 * @example
 * ```ts
-* import { gap } from '@orkestrel/brief'
+* import { buildGap } from '@orkestrel/brief'
 *
-* gap('rules', 'Should validation message wording change?') // blocking: false
-* gap('output', 'Diff or full files?', { blocking: true, candidates: ['diff', 'code'] })
+* buildGap('rules', 'Does validation message wording need to change?') // blocking: false
+* buildGap('output', 'Diff or full files?', { blocking: true, candidates: ['diff', 'code'] })
 * ```
 */
-function gap(field, question, overrides) {
+function buildGap(field, question, overrides) {
 	const blocking = overrides?.blocking ?? false;
 	return overrides?.candidates === void 0 ? {
 		field,
@@ -706,7 +789,7 @@ function gap(field, question, overrides) {
 	};
 }
 /**
-* Build a `Risk`.
+* Assembles a `Risk` from a severity, what could go wrong, and the mitigation that answers it.
 *
 * @param severity - The closed severity.
 * @param text - What could go wrong.
@@ -715,12 +798,12 @@ function gap(field, question, overrides) {
 *
 * @example
 * ```ts
-* import { risk } from '@orkestrel/brief'
+* import { buildRisk } from '@orkestrel/brief'
 *
-* risk('medium', 'native validation differs subtly', 'assert message and state in tests')
+* buildRisk('medium', 'native validation differs subtly', 'assert message and state in tests')
 * ```
 */
-function risk(severity, text, mitigation) {
+function buildRisk(severity, text, mitigation) {
 	return {
 		severity,
 		text,
@@ -728,7 +811,7 @@ function risk(severity, text, mitigation) {
 	};
 }
 /**
-* Build an `Output`.
+* Assembles an `Output` from a format plus its optional refinements.
 *
 * @param format - The closed deliverable format.
 * @param overrides - Optional `sections` / `include` / `exclude`; absent keys are OMITTED.
@@ -736,13 +819,13 @@ function risk(severity, text, mitigation) {
 *
 * @example
 * ```ts
-* import { output } from '@orkestrel/brief'
+* import { buildOutput } from '@orkestrel/brief'
 *
-* output('markdown') // { format: 'markdown' }
-* output('diff', { include: ['updated useForm.ts'] })
+* buildOutput('markdown') // { format: 'markdown' }
+* buildOutput('diff', { include: ['updated useForm.ts'] })
 * ```
 */
-function output(format, overrides) {
+function buildOutput(format, overrides) {
 	return {
 		format,
 		...overrides?.sections === void 0 ? {} : { sections: overrides.sections },
@@ -751,7 +834,7 @@ function output(format, overrides) {
 	};
 }
 /**
-* Build a `Proof`.
+* Assembles a `Proof` from what the check settles and the command that settles it.
 *
 * @param text - What the check settles.
 * @param command - The command whose exit signal settles it.
@@ -759,41 +842,41 @@ function output(format, overrides) {
 *
 * @example
 * ```ts
-* import { proof } from '@orkestrel/brief'
+* import { buildProof } from '@orkestrel/brief'
 *
-* proof('type-check and lint pass', 'npm run check')
+* buildProof('type-check and lint pass', 'npm run check')
 * ```
 */
-function proof(text, command) {
+function buildProof(text, command) {
 	return {
 		text,
 		command
 	};
 }
 /**
-* Build a `Brief` from a `Task` plus section overrides.
+* Assembles a `Brief` from a `Task` plus section overrides.
 *
 * @param subject - The task the brief is about.
-* @param overrides - Any sections to fill; every absent collection defaults to `[]`,
-*   `output` defaults to `output('markdown')`, and `trace` / `hash` stay OMITTED so
-*   `pinBrief` can fill them.
+* @param overrides - Any sections to fill; `trace` / `hash` stay OMITTED so `pinBrief` can
+*   fill them. Default: `[]` for every absent collection and `buildOutput('markdown')` for
+*   `output`.
 * @returns A fresh, unpinned `Brief`.
 *
 * @example
 * ```ts
-* import { brief, outcome, proof, task } from '@orkestrel/brief'
+* import { buildBrief, buildOutcome, buildProof, buildTask } from '@orkestrel/brief'
 *
-* brief(task('audit', 'code', 'Audit the barrel for undocumented exports.'), {
-* 	outcomes: [outcome(1, 'every export appears in the guide')],
-* 	proofs: [proof('parity passes', 'npm run test:guides')],
+* buildBrief(buildTask('audit', 'code', 'Audit the barrel for undocumented exports.'), {
+* 	outcomes: [buildOutcome(1, 'every export appears in the guide')],
+* 	proofs: [buildProof('parity passes', 'npm run test:guides')],
 * })
 * ```
 */
-function brief(subject, overrides) {
+function buildBrief(subject, overrides) {
 	return {
 		task: subject,
 		authority: overrides?.authority ?? [],
-		manifest: overrides?.manifest ?? manifest(),
+		manifest: overrides?.manifest ?? buildManifest(),
 		outcomes: overrides?.outcomes ?? [],
 		rules: overrides?.rules ?? [],
 		invariants: overrides?.invariants ?? [],
@@ -803,17 +886,17 @@ function brief(subject, overrides) {
 		citations: overrides?.citations ?? [],
 		gaps: overrides?.gaps ?? [],
 		risks: overrides?.risks ?? [],
-		output: overrides?.output ?? output("markdown"),
+		output: overrides?.output ?? buildOutput("markdown"),
 		proofs: overrides?.proofs ?? []
 	};
 }
 /**
-* Build the fail-closed readiness gate as a reasons `LogicalDefinition`.
+* Assembles the fail-closed readiness gate as a reasons `LogicalDefinition`.
 *
 * @remarks
-* Six readiness rules each derive one named fact from `briefToSubject`'s measures, and a
-* final `ready` rule conjoins all six. Forward chaining reports the LAST rule's
-* conclusion, so `LogicalResult.conclusion` is exactly `ready`.
+* Each readiness rule derives one named fact from `briefToSubject`'s measures, and a final
+* `ready` rule conjoins them all. Forward chaining reports the LAST rule's conclusion, so
+* `LogicalResult.conclusion` is exactly `ready`.
 *
 * The gate takes NO parameters, and that is deliberate rather than unfinished. The
 * reasoner overlays every derived fact into one flat namespace, so a caller rule named
@@ -827,50 +910,50 @@ function brief(subject, overrides) {
 *
 * @example
 * ```ts
-* import { briefToSubject, gateDefinition } from '@orkestrel/brief'
+* import { briefToSubject, buildGateDefinition } from '@orkestrel/brief'
 * import { createLogicalReasoner, createReason } from '@orkestrel/reason'
 *
 * const reason = createReason({ reasoners: [createLogicalReasoner()] })
-* const verdict = reason.reason(briefToSubject(pinned), gateDefinition())
+* const verdict = reason.reason(briefToSubject(pinned), buildGateDefinition())
 * reason.destroy()
 * ```
 */
-function gateDefinition() {
+function buildGateDefinition() {
 	const readiness = [
-		rule("specified", [atom("blocking", "equals", 0)], atom("specified", "equals", true)),
-		rule("aimed", [compound("and", [atom("outcomes", "above", 0), atom("required", "above", 0)])], atom("aimed", "equals", true)),
-		rule("proven", [atom("proofs", "above", 0)], atom("proven", "equals", true)),
-		rule("disjoint", [atom("overlaps", "equals", 0)], atom("disjoint", "equals", true)),
-		rule("granted", [atom("ungranted", "equals", 0)], atom("granted", "equals", true)),
-		rule("single", [atom("sentences", "equals", 1)], atom("single", "equals", true))
+		createRule("specified", [createAtom("blocking", "equals", 0)], createAtom("specified", "equals", true)),
+		createRule("aimed", [createCompound("and", [createAtom("outcomes", "above", 0), createAtom("required", "above", 0)])], createAtom("aimed", "equals", true)),
+		createRule("proven", [createAtom("proofs", "above", 0)], createAtom("proven", "equals", true)),
+		createRule("disjoint", [createAtom("overlaps", "equals", 0)], createAtom("disjoint", "equals", true)),
+		createRule("granted", [createAtom("ungranted", "equals", 0)], createAtom("granted", "equals", true)),
+		createRule("single", [createAtom("sentences", "equals", 1)], createAtom("single", "equals", true))
 	];
-	return logicalDefinition(GATE_ID, "Brief readiness", [...readiness, rule("ready", [compound("and", readiness.map((entry) => atom(entry.id, "equals", true)))], atom("ready", "equals", true))]);
+	return createLogicalDefinition(GATE_ID, "Brief readiness", [...readiness, createRule("ready", [createCompound("and", readiness.map((entry) => createAtom(entry.id, "equals", true)))], createAtom("ready", "equals", true))]);
 }
 /**
-* The readiness rules a brief fails, computed directly from its own measures.
+* Lists the readiness rules a brief fails, computed directly from its own measures.
 *
 * @remarks
-* The gate's decision, in code. `gateDefinition()` states the same six rules as data for a
+* The gate's decision, in code. `buildGateDefinition()` states the same rules as data for a
 * reasoner to narrate, and a narration is not a decision: `BriefCompilerOptions.reason` lets a
 * caller supply the engine, and an engine that answers "met" to everything would otherwise
 * emit a brief with no proofs. `compile` refuses on THIS and keeps the verdict for its
 * trace, so a supplied engine can add detail and never remove a refusal.
 *
-* The two must agree. `tests/src/core/helpers.test.ts` drives both over one value set, which
-* is what stops the data and the code from drifting apart.
+* The data and the code must agree. `tests/src/core/helpers.test.ts` drives both over one
+* value set, which is what stops them from drifting apart.
 *
 * @param source - The brief to measure.
 * @returns The unmet rule ids, in gate order; empty when the brief is ready.
 *
 * @example
 * ```ts
-* import { brief, findUnmetRules, outcome, proof, task } from '@orkestrel/brief'
+* import { buildBrief, buildOutcome, buildProof, buildTask, findUnmetRules } from '@orkestrel/brief'
 *
-* findUnmetRules(brief(task('plan', 'ops', 'Plan the release.'))) // ['aimed', 'proven']
+* findUnmetRules(buildBrief(buildTask('plan', 'ops', 'Plan the release.'))) // ['aimed', 'proven']
 * findUnmetRules(
-* 	brief(task('plan', 'ops', 'Plan the release.'), {
-* 		outcomes: [outcome(1, 'shipped')],
-* 		proofs: [proof('x', 'npm test')],
+* 	buildBrief(buildTask('plan', 'ops', 'Plan the release.'), {
+* 		outcomes: [buildOutcome(1, 'shipped')],
+* 		proofs: [buildProof('x', 'npm test')],
 * 	}),
 * ) // []
 * ```
@@ -886,7 +969,7 @@ function findUnmetRules(source) {
 	return unready;
 }
 /**
-* Count the sentences a statement holds.
+* Counts the sentences a statement holds.
 *
 * @remarks
 * A terminator run (`.`, `!`, `?`) followed by whitespace or the end of the text closes one
@@ -924,17 +1007,17 @@ function countSentences(statement) {
 	return /[.!?]$/u.test(text) ? matches.length : matches.length + 1;
 }
 /**
-* The gaps that block emission.
+* Lists the gaps that block emission.
 *
 * @param source - The brief to inspect.
 * @returns Every gap carrying `blocking: true`, in declaration order.
 *
 * @example
 * ```ts
-* import { brief, findBlockingGaps, gap, task } from '@orkestrel/brief'
+* import { buildBrief, buildGap, buildTask, findBlockingGaps } from '@orkestrel/brief'
 *
-* const draft = brief(task('plan', 'ops', 'Plan the release.'), {
-* 	gaps: [gap('output', 'Diff or files?', { blocking: true })],
+* const draft = buildBrief(buildTask('plan', 'ops', 'Plan the release.'), {
+* 	gaps: [buildGap('output', 'Diff or files?', { blocking: true })],
 * })
 * findBlockingGaps(draft).length // 1
 * ```
@@ -943,18 +1026,18 @@ function findBlockingGaps(source) {
 	return source.gaps.filter((entry) => entry.blocking);
 }
 /**
-* The authority paths the manifest never grants access to.
+* Lists the authority paths the manifest never grants access to.
 *
 * @remarks
 * An authority the executor cannot open is an instruction it cannot follow, so every ranked
-* path must appear in `read`, `edit`, or `locked`. Those three are the grants: `locked` is a
+* path must appear in `read`, `edit`, or `locked`. Those are the grants: `locked` is a
 * grant, because read-only is exactly what obeying a file requires.
 *
-* This subsumes the narrower question of an authority sitting in `forbidden`. The four
-* partitions are disjoint — `findManifestOverlaps` and the `disjoint` rule enforce it — so a
-* forbidden path is in none of the three grants and is reported here. An authority named in
-* NO partition at all is reported for the same reason, and that is the case a forbidden-only
-* check misses entirely: the brief simply never says the executor may open what it must obey.
+* This subsumes the narrower question of an authority sitting in `forbidden`. The partitions
+* are disjoint — `findManifestOverlaps` and the `disjoint` rule enforce it — so a forbidden
+* path is in none of the grants and is reported here. An authority named in NO partition at
+* all is reported for the same reason, and that is the case a forbidden-only check misses
+* entirely: the brief simply never says the executor may open what it must obey.
 *
 * Paths are compared as EXACT strings, matching `findManifestOverlaps`. A glob is never
 * expanded, so `read: 'guides/**'` does not grant `authority: 'guides/brief.md'`. State a
@@ -965,11 +1048,17 @@ function findBlockingGaps(source) {
 *
 * @example
 * ```ts
-* import { brief, findUngrantedAuthority, manifest, reference, task } from '@orkestrel/brief'
-*
-* const draft = brief(task('debug', 'code', 'Fix the leak.'), {
-* 	authority: [reference('AGENTS.md', 'project law')],
-* 	manifest: manifest(),
+* import {
+* 	buildBrief,
+* 	buildManifest,
+* 	buildReference,
+* 	buildTask,
+* 	findUngrantedAuthority,
+* } from '@orkestrel/brief'
+*
+* const draft = buildBrief(buildTask('debug', 'code', 'Fix the leak.'), {
+* 	authority: [buildReference('AGENTS.md', 'project law')],
+* 	manifest: buildManifest(),
 * })
 * findUngrantedAuthority(draft) // ['AGENTS.md'] — ranked, but no partition opens it
 * ```
@@ -985,10 +1074,10 @@ function findUngrantedAuthority(source) {
 	return ungranted;
 }
 /**
-* The paths appearing in more than one manifest partition.
+* Lists the paths appearing in more than one manifest partition.
 *
 * @remarks
-* Duplicates WITHIN one partition are not an overlap; the four partitions must be
+* Duplicates WITHIN one partition are not an overlap; the partitions must be
 * mutually disjoint, which is what `validateBrief` errors on.
 *
 * Paths are compared as EXACT strings. A glob is never expanded, so `edit: 'app/file.ts'`
@@ -1000,12 +1089,18 @@ function findUngrantedAuthority(source) {
 *
 * @example
 * ```ts
-* import { brief, findManifestOverlaps, manifest, reference, task } from '@orkestrel/brief'
-*
-* const draft = brief(task('debug', 'code', 'Fix the leak.'), {
-* 	manifest: manifest({
-* 		edit: [reference('src/core/BriefCompiler.ts', 'the leaking pipeline')],
-* 		locked: [reference('src/core/BriefCompiler.ts', 'the published contract')],
+* import {
+* 	buildBrief,
+* 	buildManifest,
+* 	buildReference,
+* 	buildTask,
+* 	findManifestOverlaps,
+* } from '@orkestrel/brief'
+*
+* const draft = buildBrief(buildTask('debug', 'code', 'Fix the leak.'), {
+* 	manifest: buildManifest({
+* 		edit: [buildReference('src/core/BriefCompiler.ts', 'the leaking pipeline')],
+* 		locked: [buildReference('src/core/BriefCompiler.ts', 'the published contract')],
 * 	}),
 * })
 * findManifestOverlaps(draft) // ['src/core/BriefCompiler.ts']
@@ -1025,7 +1120,7 @@ function findManifestOverlaps(source) {
 	return overlaps;
 }
 /**
-* The open gaps with no assumption to stand on.
+* Lists the open gaps with no assumption to stand on.
 *
 * @remarks
 * The discipline is exactly one recorded assumption per open gap, so the open gaps past
@@ -1037,10 +1132,10 @@ function findManifestOverlaps(source) {
 *
 * @example
 * ```ts
-* import { brief, findUnpairedGaps, gap, task } from '@orkestrel/brief'
+* import { buildBrief, buildGap, buildTask, findUnpairedGaps } from '@orkestrel/brief'
 *
-* const draft = brief(task('plan', 'ops', 'Plan the release.'), {
-* 	gaps: [gap('rules', 'Keep the wording?'), gap('output', 'Diff or files?')],
+* const draft = buildBrief(buildTask('plan', 'ops', 'Plan the release.'), {
+* 	gaps: [buildGap('rules', 'Keep the wording?'), buildGap('output', 'Diff or files?')],
 * 	assumptions: ['Wording is preserved.'],
 * })
 * findUnpairedGaps(draft).length // 1
@@ -1050,16 +1145,16 @@ function findUnpairedGaps(source) {
 	return source.gaps.filter((entry) => !entry.blocking).slice(source.assumptions.length);
 }
 /**
-* Project a brief into the reasons `Subject` of readiness measures the gate reads.
+* Projects a brief into the reasons `Subject` of readiness measures the gate reads.
 *
 * @param source - The brief to measure.
-* @returns A flat record of counts plus the task's two vocabulary values.
+* @returns A flat record of counts plus the task's vocabulary values.
 *
 * @example
 * ```ts
-* import { brief, briefToSubject, proof, task } from '@orkestrel/brief'
+* import { briefToSubject, buildBrief, buildProof, buildTask } from '@orkestrel/brief'
 *
-* briefToSubject(brief(task('test', 'code', 'Cover the gate.'), { proofs: [proof('x', 'y')] }))
+* briefToSubject(buildBrief(buildTask('test', 'code', 'Cover the gate.'), { proofs: [buildProof('x', 'y')] }))
 * // { operation: 'test', domain: 'code', sentences: 1, proofs: 1, … }
 * ```
 */
@@ -1086,7 +1181,7 @@ function briefToSubject(source) {
 	};
 }
 /**
-* The semantic pass over an already-shape-valid brief.
+* Runs the semantic pass over an already-shape-valid brief.
 *
 * @remarks
 * ERRORS are the structural violations no assumption can paper over: a manifest
@@ -1100,11 +1195,11 @@ function briefToSubject(source) {
 *
 * @example
 * ```ts
-* import { brief, proof, task, validateBrief } from '@orkestrel/brief'
+* import { buildBrief, buildProof, buildTask, validateBrief } from '@orkestrel/brief'
 *
-* validateBrief(brief(task('plan', 'ops', 'Plan the release.'))) // valid: false — no proofs
+* validateBrief(buildBrief(buildTask('plan', 'ops', 'Plan the release.'))) // valid: false — no proofs
 * validateBrief(
-* 	brief(task('plan', 'ops', 'Plan the release.'), { proofs: [proof('ok', 'npm test')] }),
+* 	buildBrief(buildTask('plan', 'ops', 'Plan the release.'), { proofs: [buildProof('ok', 'npm test')] }),
 * ) // valid: true
 * ```
 */
@@ -1132,7 +1227,7 @@ function validateBrief(source) {
 	};
 }
 /**
-* The canonical structural digest of a brief's content.
+* Computes the canonical structural digest of a brief's content.
 *
 * @remarks
 * `trace` and `hash` are stripped before digesting, so the value is the identity of what
@@ -1144,9 +1239,9 @@ function validateBrief(source) {
 *
 * @example
 * ```ts
-* import { brief, briefToHash, pinBrief, task } from '@orkestrel/brief'
+* import { briefToHash, buildBrief, buildTask, pinBrief } from '@orkestrel/brief'
 *
-* const draft = brief(task('plan', 'ops', 'Plan the release.'))
+* const draft = buildBrief(buildTask('plan', 'ops', 'Plan the release.'))
 * briefToHash(draft) === briefToHash(pinBrief(draft)) // true — pinning does not move it
 * ```
 */
@@ -1154,7 +1249,7 @@ function briefToHash(source) {
 	return digestValue(briefToContent(source));
 }
 /**
-* The canonical text of exactly what a brief's hash describes.
+* Renders the canonical text of exactly what a brief's hash describes.
 *
 * @remarks
 * `trace` and `hash` are stripped, then interprets `canonicalize` renders the rest in a
@@ -1166,9 +1261,9 @@ function briefToHash(source) {
 *
 * @example
 * ```ts
-* import { brief, briefToContent, pinBrief, task } from '@orkestrel/brief'
+* import { briefToContent, buildBrief, buildTask, pinBrief } from '@orkestrel/brief'
 *
-* const draft = brief(task('plan', 'ops', 'Plan the release.'))
+* const draft = buildBrief(buildTask('plan', 'ops', 'Plan the release.'))
 * briefToContent(draft) === briefToContent(pinBrief(draft)) // true — pinning adds no content
 * ```
 */
@@ -1177,7 +1272,7 @@ function briefToContent(source) {
 	return canonicalize(content);
 }
 /**
-* Freeze a value and everything reachable from it.
+* Freezes a value and everything reachable from it.
 *
 * @remarks
 * `Object.freeze` is SHALLOW, so freezing a record leaves every nested array and object
@@ -1191,7 +1286,7 @@ function briefToContent(source) {
 * Reaches PLAIN objects and arrays, which is the whole of a `Brief` — it is JSON-serializable
 * by contract. A `Map`, `Set`, or typed array is frozen as an object and its CONTENTS are left
 * writable, and `Object.isFrozen` reports `true` for it either way. Nothing this package
-* produces contains one; a caller freezing their own value should know the limit.
+* produces contains one; the limit lands on a caller freezing their own value.
 *
 * @param value - The value to freeze in place; returned for convenience.
 * @returns The same value, now deeply frozen.
@@ -1208,7 +1303,7 @@ function freezeDeep(value) {
 	return freezeBranch(value, /* @__PURE__ */ new WeakSet());
 }
 /**
-* Freeze one branch of a value graph, skipping what the visited set already holds.
+* Freezes one branch of a value graph, skipping what the visited set already holds.
 *
 * @param value - The branch to freeze.
 * @param seen - The objects already frozen on this walk; what makes a cycle terminate.
@@ -1230,7 +1325,7 @@ function freezeBranch(value, seen) {
 	return value;
 }
 /**
-* Render a value thrown by a stage into a message.
+* Renders a value thrown by a stage into a message.
 *
 * @remarks
 * TOTAL: it never throws, for any input. That is load-bearing rather than tidy, because this
@@ -1239,7 +1334,7 @@ function freezeBranch(value, seen) {
 * falsifies the package's central promise that a failing stage yields an incomplete
 * `Briefing` rather than an exception.
 *
-* Three real inputs used to throw: an `Error` subclass whose `message` getter throws, a value
+* Real inputs used to throw: an `Error` subclass whose `message` getter throws, a value
 * whose string conversion throws, and a null-prototype object, which has no inherited
 * conversion for String() to reach. Each is wrapped, and an unreadable value degrades to its
 * type rather than propagating.
@@ -1263,10 +1358,10 @@ function errorToMessage(error) {
 	return `an unreadable ${typeof error} was thrown`;
 }
 /**
-* Narrow unknown data to a `Brief`, throwing when it is off-contract.
+* Narrows unknown data to a `Brief`, throwing when it is off-contract.
 *
 * @remarks
-* The throwing half of the intake pair: this returns its argument by IDENTITY once the
+* The throwing half of the intake pair: this returns its argument by IDENTITY after the
 * guard passes, while `parseBrief` returns `undefined` for bad input. It constructs
 * nothing, so it is an assertion rather than a factory. Reserve it for programmer-error
 * contexts where invalidity is a bug.
@@ -1280,24 +1375,24 @@ function errorToMessage(error) {
 * `briefToTrace` read the value they are handed instead, so a caller reaching one of those
 * directly owns that reading. Pass `assertBrief` a value you already own.
 *
-* @param data - The candidate brief data.
+* @param value - The candidate brief value.
 * @returns The same value, now known to satisfy {@link Brief}.
-* @throws {@link BriefError} `INVALID` when `data` fails `isBrief`.
+* @throws {@link BriefError} `INVALID` when `value` fails `isBrief`.
 *
 * @example
 * ```ts
-* import { assertBrief, brief, proof, task } from '@orkestrel/brief'
+* import { assertBrief, buildBrief, buildProof, buildTask } from '@orkestrel/brief'
 *
-* assertBrief(brief(task('plan', 'ops', 'Plan the release.'), { proofs: [proof('x', 'y')] }))
+* assertBrief(buildBrief(buildTask('plan', 'ops', 'Plan the release.'), { proofs: [buildProof('x', 'y')] }))
 * assertBrief({ task: { operation: 'plan', domain: 'ops', statement: 'x.' } }) // throws INVALID
 * ```
 */
-function assertBrief(data) {
-	if (!isBrief(data)) throw new BriefError("INVALID", "Brief failed the exact-record contract", { field: "brief" });
-	return data;
+function assertBrief(value) {
+	if (!isBrief(value)) throw new BriefError("INVALID", "Brief failed the exact-record contract", { field: "brief" });
+	return value;
 }
 /**
-* Return a fresh brief with `trace` and `hash` derived from its own content.
+* Returns a fresh brief with `trace` and `hash` derived from its own content.
 *
 * @remarks
 * Deterministic: no clock, no randomness, no run-specific data. Any existing `trace` /
@@ -1313,9 +1408,9 @@ function assertBrief(data) {
 *
 * @example
 * ```ts
-* import { brief, pinBrief, task } from '@orkestrel/brief'
+* import { buildBrief, buildTask, pinBrief } from '@orkestrel/brief'
 *
-* const pinned = pinBrief(brief(task('document', 'writing', 'Write the brief guide.')))
+* const pinned = pinBrief(buildBrief(buildTask('document', 'writing', 'Write the brief guide.')))
 * pinned.hash // an 8-hex-digit structural digest
 * pinned.trace // 'document/writing · outcomes:0 · gaps:0/0 · proofs:0'
 * ```
@@ -1330,7 +1425,7 @@ function pinBrief(source) {
 	});
 }
 /**
-* The one-line census `pinBrief` stamps onto a brief.
+* Renders the one-line census `pinBrief` stamps onto a brief.
 *
 * @remarks
 * Extracted so it has ONE implementation. `pinBrief` derives it and `BriefManager` re-derives
@@ -1343,9 +1438,9 @@ function pinBrief(source) {
 *
 * @example
 * ```ts
-* import { brief, briefToTrace, task } from '@orkestrel/brief'
+* import { briefToTrace, buildBrief, buildTask } from '@orkestrel/brief'
 *
-* briefToTrace(brief(task('document', 'writing', 'Write the guide.')))
+* briefToTrace(buildBrief(buildTask('document', 'writing', 'Write the guide.')))
 * // 'document/writing · outcomes:0 · gaps:0/0 · proofs:0'
 * ```
 */
@@ -1358,7 +1453,7 @@ function briefToTrace(source) {
 	].join(" · ");
 }
 /**
-* Render one exemplar as markdown lines.
+* Renders one exemplar as markdown lines.
 *
 * @remarks
 * An `Example`'s two sides are the only brief members permitted to span lines, so a
@@ -1370,9 +1465,9 @@ function briefToTrace(source) {
 *
 * @example
 * ```ts
-* import { example, exampleToLines } from '@orkestrel/brief'
+* import { buildExample, exampleToLines } from '@orkestrel/brief'
 *
-* exampleToLines(example('<input required>', 'el.validity')) // ['- ` <input required> ` → ` el.validity `']
+* exampleToLines(buildExample('<input required>', 'el.validity')) // ['- ` <input required> ` → ` el.validity `']
 * ```
 */
 function exampleToLines(entry) {
@@ -1403,20 +1498,20 @@ function exampleToLines(entry) {
 	];
 }
 /**
-* Project a brief into the copy-ready agent prompt.
+* Projects a brief into the copy-ready agent prompt.
 *
 * @remarks
 * Paths are REFERENCED, never inlined — the executor retrieves them. An empty section is
 * omitted entirely, so the rendering carries no filler an executor must read past.
 *
-* @param source - The brief to render.
+* @param input - The brief to render.
 * @returns The markdown prompt.
 *
 * @example
 * ```ts
-* import { brief, briefToMarkdown, task } from '@orkestrel/brief'
+* import { briefToMarkdown, buildBrief, buildTask } from '@orkestrel/brief'
 *
-* briefToMarkdown(brief(task('review', 'code', 'Review the gate rules.')))
+* briefToMarkdown(buildBrief(buildTask('review', 'code', 'Review the gate rules.')))
 * // '# Brief: Review the gate rules.\n\nreview · code\n\n## Output\n\n- format: markdown\n'
 * ```
 */
@@ -1510,21 +1605,21 @@ function briefToMarkdown(input) {
 	return lines.join("\n");
 }
 /**
-* Project a brief into a `/goal` completion condition.
+* Projects a brief into a `/goal` completion condition.
 *
 * @remarks
 * The proofs' commands VERBATIM plus a turn cap — the goal never adds a condition the
 * brief does not carry.
 *
-* @param source - The brief to render.
-* @param turns - The turn cap; defaults to `DEFAULT_BRIEF_TURNS`.
+* @param input - The brief to render.
+* @param turns - The turn cap. Default: `DEFAULT_BRIEF_TURNS`.
 * @returns The one-line completion condition.
 *
 * @example
 * ```ts
-* import { brief, briefToGoal, proof, task } from '@orkestrel/brief'
+* import { briefToGoal, buildBrief, buildProof, buildTask } from '@orkestrel/brief'
 *
-* briefToGoal(brief(task('test', 'code', 'Cover the gate.'), { proofs: [proof('x', 'npm test')] }))
+* briefToGoal(buildBrief(buildTask('test', 'code', 'Cover the gate.'), { proofs: [buildProof('x', 'npm test')] }))
 * // 'Done when every proof passes: npm test exits 0. Cap: 16 turns.'
 * ```
 */
@@ -1533,27 +1628,33 @@ function briefToGoal(input, turns = 16) {
 	return `Done when every proof passes: ${source.proofs.length === 0 ? "no proofs recorded" : source.proofs.map((entry) => `${entry.command} exits 0`).join("; ")}. Cap: ${String(turns)} turns.`;
 }
 /**
-* Project a brief into a subagent `Dispatch`.
+* Projects a brief into a subagent `Dispatch`.
 *
 * @remarks
 * `edit` is exactly `manifest.edit`, so two dispatches whose `edit` sets do not intersect
 * can run concurrently under the same brief without conflict.
 *
 * `authority` is exactly `brief.authority` in rank order, and it is a SEPARATE axis from the
-* four permission sets rather than a fifth partition — a ranked path normally also appears in
+* permission sets rather than a further partition — a ranked path normally also appears in
 * `read` or `locked`, because the executor has to open what it obeys. It is projected as
 * paths so a machine consumer never has to parse `prompt`, which is written for a model.
 *
-* @param source - The brief to project.
-* @returns The dispatch — the rendered prompt, the ranked authority, and the four path sets.
+* @param input - The brief to project.
+* @returns The dispatch — the rendered prompt, the ranked authority, and the path sets.
 *
 * @example
 * ```ts
-* import { brief, briefToDispatch, manifest, reference, task } from '@orkestrel/brief'
-*
-* const draft = brief(task('migrate', 'code', 'Migrate the stores.'), {
-* 	authority: [reference('AGENTS.md', 'project law')],
-* 	manifest: manifest({ edit: [reference('src/core/stores/**', 'the legacy stores')] }),
+* import {
+* 	briefToDispatch,
+* 	buildBrief,
+* 	buildManifest,
+* 	buildReference,
+* 	buildTask,
+* } from '@orkestrel/brief'
+*
+* const draft = buildBrief(buildTask('migrate', 'code', 'Migrate the stores.'), {
+* 	authority: [buildReference('AGENTS.md', 'project law')],
+* 	manifest: buildManifest({ edit: [buildReference('src/core/stores/**', 'the legacy stores')] }),
 * })
 * briefToDispatch(draft).edit // ['src/core/stores/**']
 * briefToDispatch(draft).authority // ['AGENTS.md']
@@ -1571,36 +1672,39 @@ function briefToDispatch(input) {
 	};
 }
 /**
-* Derive one imperative statement from free text.
+* Derives one imperative statement from free text.
 *
 * @remarks
 * Whitespace collapses, the first character uppercases, and a terminator is appended
 * when the text carries none. Nothing else is invented.
 *
 * @param text - The raw request text.
-* @returns The statement, or `''` for empty or whitespace-only text.
+* @returns The statement, or `undefined` for empty or whitespace-only text.
 *
 * @example
 * ```ts
 * import { deriveStatement } from '@orkestrel/brief'
 *
 * deriveStatement('  clean up   useForm ') // 'Clean up useForm.'
-* deriveStatement('') // ''
+* deriveStatement('') // undefined
 * ```
 */
 function deriveStatement(text) {
 	const collapsed = collapseWhitespace(text);
-	if (collapsed.length === 0) return "";
+	if (collapsed.length === 0) return void 0;
 	const capitalized = collapsed.charAt(0).toUpperCase() + collapsed.slice(1);
 	return /[.!?]$/u.test(capitalized) ? capitalized : `${capitalized}.`;
 }
 /**
-* Derive a `Task` from an interprets `Intent` through the caller's vocabularies.
+* Derives a `Task` from an interprets `Intent` through the caller's vocabularies.
 *
 * @remarks
 * The vocabularies are the CALLER's policy: this maps and never guesses. An action or
 * domain the caller did not map — or mapped to an off-vocabulary value — yields
-* `undefined` rather than an invented task. Inherited keys never resolve.
+* `undefined` rather than an invented task. Inherited keys never resolve. `Intent.action`
+* and `Intent.domain` are optional, because `classifyIntent` leaves an unmatched axis
+* absent, and an absent axis is unmapped by definition: it yields `undefined` before
+* either vocabulary is read.
 *
 * @param intent - The classified intent from an interpret pipeline.
 * @param text - The text the statement derives from.
@@ -1619,16 +1723,17 @@ function deriveStatement(text) {
 * ```
 */
 function deriveTask(intent, text, actions, domains) {
+	if (intent.action === void 0 || intent.domain === void 0) return void 0;
 	const operationDescriptor = Object.getOwnPropertyDescriptor(actions, intent.action);
 	const domainDescriptor = Object.getOwnPropertyDescriptor(domains, intent.domain);
 	const operation = operationDescriptor === void 0 ? void 0 : "value" in operationDescriptor ? operationDescriptor.value : operationDescriptor.get === void 0 ? void 0 : Reflect.apply(operationDescriptor.get, actions, []);
 	const domain = domainDescriptor === void 0 ? void 0 : "value" in domainDescriptor ? domainDescriptor.value : domainDescriptor.get === void 0 ? void 0 : Reflect.apply(domainDescriptor.get, domains, []);
 	if (!isTaskOperation(operation) || !isTaskDomain(domain)) return void 0;
 	const statement = deriveStatement(text);
-	return statement.length === 0 ? void 0 : task(operation, domain, statement);
+	return statement === void 0 ? void 0 : buildTask(operation, domain, statement);
 }
 /**
-* Derive `Given[]` from an interprets `Entity[]`.
+* Derives `Given[]` from an interprets `Entity[]`.
 *
 * @remarks
 * Every extracted entity becomes one `extracted` fact. A nameless entity is dropped; an
@@ -1647,10 +1752,10 @@ function deriveTask(intent, text, actions, domains) {
 * ```
 */
 function deriveGivens(entities) {
-	return entities.filter((entity) => entity.name.length > 0).map((entity) => given("extracted", entity.name, typeof entity.value === "string" ? entity.value : typeof entity.value === "object" && entity.value !== null ? canonicalize(entity.value) : String(entity.value)));
+	return entities.filter((entity) => entity.name.length > 0).map((entity) => buildGiven("extracted", entity.name, typeof entity.value === "string" ? entity.value : typeof entity.value === "object" && entity.value !== null ? canonicalize(entity.value) : String(entity.value)));
 }
 /**
-* Derive `Gap[]` from an interprets `Ambiguity[]`.
+* Derives `Gap[]` from an interprets `Ambiguity[]`.
 *
 * @remarks
 * A REQUIRED ambiguity becomes a BLOCKING gap — the gate must fail closed on it. The
@@ -1671,7 +1776,7 @@ function deriveGivens(entities) {
 function deriveGaps(ambiguities) {
 	return ambiguities.map((ambiguity) => {
 		const candidates = ambiguity.candidates.filter((candidate) => candidate.length > 0);
-		return gap(formatField(ambiguity.field), ambiguity.question, {
+		return buildGap(formatField(ambiguity.field), ambiguity.question, {
 			blocking: ambiguity.required,
 			...candidates.length === 0 ? {} : { candidates }
 		});
@@ -1680,7 +1785,7 @@ function deriveGaps(ambiguities) {
 //#endregion
 //#region src/core/parsers.ts
 /**
-* Parse a JSON string into a `Brief`.
+* Parses a JSON string into a `Brief`.
 *
 * @remarks
 * The parse-then-trust boundary for a stored brief, a tool argument, or an agent's
@@ -1714,7 +1819,7 @@ function parseBrief(value) {
 //#endregion
 //#region src/core/BriefManager.ts
 /**
-* The self-owning, versioned and content-hashed brief registry.
+* Implements the self-owning, versioned and content-hashed brief registry.
 *
 * @remarks
 * Record ids are MINTED from each brief's own content hash unless the caller names one,
@@ -1724,10 +1829,10 @@ function parseBrief(value) {
 *
 * @example
 * ```ts
-* import { BriefManager, brief, task } from '@orkestrel/brief'
+* import { BriefManager, buildBrief, buildTask } from '@orkestrel/brief'
 *
 * const briefs = new BriefManager()
-* const record = briefs.add(brief(task('document', 'writing', 'Write the brief guide.')))
+* const record = briefs.add(buildBrief(buildTask('document', 'writing', 'Write the brief guide.')))
 * record.id === record.hash // true
 * briefs.destroy()
 * ```
@@ -1754,7 +1859,7 @@ var BriefManager = class {
 	get emitter() {
 		return this.#emitter;
 	}
-	get size() {
+	get count() {
 		return this.#records.size;
 	}
 	has(id) {
@@ -1769,9 +1874,9 @@ var BriefManager = class {
 		this.#refuseDestroyed();
 		return [...this.#records.values()];
 	}
-	add(source, options) {
+	add(brief, options) {
 		this.#refuseDestroyed();
-		const record = this.#stage(source, this.#records, options);
+		const record = this.#stage(brief, this.#records, options);
 		this.#commit(record);
 		return record;
 	}
@@ -1838,7 +1943,7 @@ var BriefManager = class {
 //#endregion
 //#region src/core/BriefCompiler.ts
 /**
-* The compilation orchestrator — the four-stage `[interpret, draft, gate, pin]` pipeline.
+* Implements the compilation orchestrator — the `[interpret, draft, gate, pin]` pipeline.
 *
 * @remarks
 * `compile` is genuinely SYNCHRONOUS and never throws for a brief it cannot emit: a
@@ -1848,13 +1953,13 @@ var BriefManager = class {
 *
 * @example
 * ```ts
-* import { BriefCompiler, proof, task } from '@orkestrel/brief'
+* import { BriefCompiler, buildProof, buildTask } from '@orkestrel/brief'
 *
 * const compiler = new BriefCompiler()
 * const briefing = compiler.compile({
-* 	task: task('audit', 'code', 'Audit the barrel for undocumented exports.'),
+* 	task: buildTask('audit', 'code', 'Audit the barrel for undocumented exports.'),
 * 	outcomes: [{ rank: 1, text: 'every export appears in the guide', required: true }],
-* 	proofs: [proof('parity passes', 'npm run test:guides')],
+* 	proofs: [buildProof('parity passes', 'npm run test:guides')],
 * })
 * briefing.brief !== undefined // true — the presence of the brief IS the completeness test
 * compiler.destroy()
@@ -2005,9 +2110,9 @@ var BriefCompiler = class {
 		this.#emitter.emit("compile", briefing);
 		return briefing;
 	}
-	gate(source) {
+	gate(brief) {
 		this.#refuseDestroyed();
-		const ruled = attempt(() => this.#own(this.#reason.reason(briefToSubject(source), gateDefinition()), [
+		const ruled = attempt(() => this.#own(this.#reason.reason(briefToSubject(brief), buildGateDefinition()), [
 			"reasoning",
 			"conclusion",
 			"rules",
@@ -2096,7 +2201,7 @@ var BriefCompiler = class {
 			message: `Gate refused: ${unready.join(", ")}`
 		};
 		if (verdict === void 0) return void 0;
-		const refused = verdict.rules.filter((entry) => !entry.conclusion).map((entry) => entry.id).join(", ");
+		const refused = verdict.rules.filter((entry) => !entry.applied).map((entry) => entry.id).join(", ");
 		if (refused.length === 0) return {
 			stage: "gate",
 			code: "BLOCKED",
@@ -2111,7 +2216,7 @@ var BriefCompiler = class {
 	#unresolved(interpretation, failures) {
 		if (interpretation !== void 0) return [];
 		if (!failures.some((entry) => entry.stage === "interpret")) return [];
-		return [gap("gaps", "The interpret stage failed, so the request is unread and its unknowns are unknown", { blocking: true })];
+		return [buildGap("gaps", "The interpret stage failed, so the request is unread and its unknowns are unknown", { blocking: true })];
 	}
 	#draft(input, interpretation, unresolved) {
 		const derived = interpretation === void 0 ? void 0 : deriveTask(interpretation.intent, interpretation.text, this.#actions, this.#domains);
@@ -2120,9 +2225,9 @@ var BriefCompiler = class {
 			stage: "draft",
 			field: "task"
 		});
-		return snapshotBrief(brief(subject, {
+		return snapshotBrief(buildBrief(subject, {
 			authority: input.authority ?? [],
-			manifest: input.manifest ?? manifest(),
+			manifest: input.manifest ?? buildManifest(),
 			outcomes: input.outcomes ?? [],
 			rules: input.rules ?? [],
 			invariants: input.invariants ?? [],
@@ -2136,7 +2241,7 @@ var BriefCompiler = class {
 				...input.gaps ?? []
 			],
 			risks: input.risks ?? [],
-			output: input.output ?? output("markdown"),
+			output: input.output ?? buildOutput("markdown"),
 			proofs: input.proofs ?? []
 		}));
 	}
@@ -2164,7 +2269,7 @@ var BriefCompiler = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a compilation orchestrator.
+* Creates a compilation orchestrator.
 *
 * @remarks
 * With no engines supplied the compiler wires its own: a default `createInterpret()`
@@ -2172,7 +2277,8 @@ var BriefCompiler = class {
 * `createReason` carrying one `LogicalReasoner` for the gate. Pass your own to share
 * instances or observe their emitters — the compiler destroys ONLY what it created.
 *
-* @param options - Engines to borrow, the two intent vocabularies, and emitter hooks.
+* @param options - Engines to borrow, the `actions` and `domains` intent vocabularies, and
+* emitter hooks.
 * @returns A working {@link BriefCompilerInterface}.
 *
 * @example
@@ -2187,7 +2293,7 @@ function createBriefCompiler(options) {
 	return new BriefCompiler(options);
 }
 /**
-* Create a brief registry.
+* Creates a brief registry.
 *
 * @param options - An optional seed collection plus emitter hooks.
 * @returns A working {@link BriefManagerInterface}.
@@ -2197,7 +2303,7 @@ function createBriefCompiler(options) {
 * import { createBriefManager } from '@orkestrel/brief'
 *
 * const briefs = createBriefManager()
-* briefs.size // 0
+* briefs.count // 0
 * briefs.destroy()
 * ```
 */
@@ -2205,7 +2311,7 @@ function createBriefManager(options) {
 	return new BriefManager(options);
 }
 /**
-* Compile `briefShape` into a guard, parser, JSON Schema, and seeded generator bundle.
+* Compiles `briefShape` into a guard, parser, JSON Schema, and seeded generator bundle.
 *
 * @remarks
 * The schema is what a tool boundary needs — hand it to `schemaToParameters` — and
@@ -2229,6 +2335,6 @@ function createBriefContract() {
 	return createContract(briefShape);
 }
 //#endregion
-export { BLANK_PATTERN, BriefCompiler, BriefError, BriefManager, DEFAULT_BRIEF_TURNS, GATE_ID, INTERPRETATION_MEMBERS, LINE_BREAK_PATTERN, OUTPUT_FORMATS, RISK_SEVERITIES, SINGLE_LINE_PATTERN, TASK_DOMAINS, TASK_OPERATIONS, assertBrief, brief, briefShape, briefToContent, briefToDispatch, briefToGoal, briefToHash, briefToMarkdown, briefToSubject, briefToTrace, captureValue, citation, citationShape, countSentences, createBriefCompiler, createBriefContract, createBriefManager, deriveGaps, deriveGivens, deriveStatement, deriveTask, errorToMessage, example, exampleShape, exampleToLines, findBlockingGaps, findManifestOverlaps, findUngrantedAuthority, findUnmetRules, findUnpairedGaps, freezeBranch, freezeDeep, gap, gapShape, gateDefinition, given, givenShape, isBrief, isBriefError, isCitation, isExample, isGap, isGiven, isLine, isManifest, isOutcome, isOutput, isOutputFormat, isProof, isReference, isRisk, isRiskSeverity, isTask, isTaskDomain, isTaskOperation, isText, lineShape, manifest, manifestShape, outcome, outcomeShape, output, outputShape, parseBrief, pinBrief, proof, proofShape, reference, referenceShape, risk, riskShape, snapshotBrief, task, taskShape, textShape, validateBrief };
+export { BLANK_PATTERN, BriefCompiler, BriefError, BriefManager, DEFAULT_BRIEF_TURNS, GATE_ID, INTERPRETATION_MEMBERS, LINE_BREAK_PATTERN, OUTPUT_FORMATS, RISK_SEVERITIES, SINGLE_LINE_PATTERN, TASK_DOMAINS, TASK_OPERATIONS, assertBrief, briefShape, briefToContent, briefToDispatch, briefToGoal, briefToHash, briefToMarkdown, briefToSubject, briefToTrace, buildBrief, buildCitation, buildExample, buildGap, buildGateDefinition, buildGiven, buildManifest, buildOutcome, buildOutput, buildProof, buildReference, buildRisk, buildTask, captureValue, citationShape, countSentences, createBriefCompiler, createBriefContract, createBriefManager, deriveGaps, deriveGivens, deriveStatement, deriveTask, errorToMessage, exampleShape, exampleToLines, findBlockingGaps, findManifestOverlaps, findUngrantedAuthority, findUnmetRules, findUnpairedGaps, freezeBranch, freezeDeep, gapShape, givenShape, isBrief, isBriefError, isCitation, isExample, isGap, isGiven, isLine, isManifest, isOutcome, isOutput, isOutputFormat, isProof, isReference, isRisk, isRiskSeverity, isTask, isTaskDomain, isTaskOperation, isText, lineShape, manifestShape, outcomeShape, outputShape, parseBrief, pinBrief, proofShape, referenceShape, riskShape, snapshotBrief, taskShape, textShape, validateBrief };
 
 //# sourceMappingURL=index.js.map