@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/src/spec.js

@@ -1,13 +1,16 @@
+import { callableResult, callableErrors } from "./contracts.js";
 import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fieldsOf, typeName } from "./ast.js";
-import { builtinFunctions, builtinProperties, collectionOperations, operationType } from "./builtins.js";
+import { builtinFunctions, builtinProperties, builtinTypes, collectionOperations, operationType } from "./builtins.js";
 import { callableDocumentation } from "./documentation.js";
 import { javadocBefore } from "./javadoc.js";
 import { libraryChild, libraryRelative } from "./libraries.js";
 import { compilerVersion } from "./package-manager.js";
 import { tyName } from "./types.js";
+import { action, attempt, branch, choice, coordinate, flow, loop, paragraph, renderSpecTree, scope, section, sequence, step } from "./spec-tree.js";
+import { specHint } from "./spec-hints.js";
 const generated = '<!-- Generated by aug spec. Edit the August source, then regenerate. -->';
 const copied = '// Generated by aug spec. This is a copy of the installed dependency source.\n';
 const code = (value) => { const text = value.replaceAll('\n', '\\n'); const fence = '`'.repeat(1 + Math.max(0, ...(text.match(/`+/g) ?? []).map(part => part.length))); return fence + (text.startsWith('`') ? ' ' : '') + text + (text.endsWith('`') ? ' ' : '') + fence; };
@@ -16,13 +19,15 @@ const anchor = (name) => 'symbol-' + name;
 const hash = (text) => createHash('sha256').update(text).digest('hex');
 const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 const unreachable = (node) => { throw new Error(`No specification renderer for ${node.kind}`); };
-/** Render checked code, never execute it. All paths and ordering are reproducible. */
+const plain = (text) => text.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replaceAll('`', '');
+/** Plan prose, managed source pointers, and versioned dependency copies without writes or execution. */
 export function generateSpecs(checked, options = {}) {
     if (checked.diagnostics.some(issue => issue.severity !== 'warning'))
         throw new Error('Fix compiler errors before generating specifications');
     const project = checked.project;
     const owned = options.files ?? [...project.files.values()].filter(file => !file.builtin && !file.package);
     const own = new Set(owned.map(file => file.path));
+    const hints = owned.map(specHint), offsets = new Map(hints.map(hint => [hint.file.path, hint.lineOffset]));
     const docs = new Map(), sources = new Map();
     for (const file of project.files.values()) {
         if (own.has(file.path)) {
@@ -38,13 +43,13 @@ export function generateSpecs(checked, options = {}) {
         sources.set(file.path, source);
     }
     const queue = [...owned].sort((a, b) => compare(a.path, b.path));
-    const seen = new Set(), outputs = [];
+    const seen = new Set(), outputs = hints.map(hint => ({ path: hint.file.path, text: hint.text, source: hint.file.path, kind: 'source-hint' }));
     for (let index = 0; index < queue.length; index++) {
         const file = queue[index];
         if (seen.has(file.path))
             continue;
         seen.add(file.path);
-        const writer = new SpecWriter(checked, file, docs, sources, own, path => {
+        const writer = new SpecWriter(checked, file, docs, sources, own, offsets, path => {
             const dependency = project.files.get(path);
             if (dependency && !seen.has(path))
                 queue.push(dependency);
@@ -61,17 +66,19 @@ class SpecWriter {
     docs;
     sources;
     own;
+    offsets;
     enqueue;
     used = new Map();
     builtins = new Map();
     properties = new Map();
     locals = new Map();
-    constructor(checked, file, docs, sources, own, enqueue) {
+    constructor(checked, file, docs, sources, own, offsets, enqueue) {
         this.checked = checked;
         this.file = file;
         this.docs = docs;
         this.sources = sources;
         this.own = own;
+        this.offsets = offsets;
         this.enqueue = enqueue;
     }
     definition(name) { return this.checked.project.scopes.get(this.file.path)?.get(name); }
@@ -99,95 +106,166 @@ class SpecWriter {
         return `[${code(label)}](${url(relative(dirname(this.docs.get(this.file.path)), this.docs.get(def.file)))}#${encodeURIComponent(anchor(name))})`;
     }
     source(span) {
-        return `[source](${url(relative(dirname(this.docs.get(this.file.path)), this.sources.get(span.file)))}#L${span.line + (this.own.has(span.file) ? 0 : 1)})`;
+        return `[source](${url(relative(dirname(this.docs.get(this.file.path)), this.sources.get(span.file)))}#L${span.line + (this.own.has(span.file) ? this.offsets.get(span.file) ?? 0 : 1)})`;
     }
-    heading(name, span, level = 2) {
-        return `<a id="${anchor(name)}"></a>\n\n${'#'.repeat(level)} ${code(name)}\n\n${this.source(span)}\n\n`;
+    heading(name, span, level, children, role) {
+        return section(code(name) + (role ? ' · ' + role : ''), level, children, anchor(name), this.source(span));
     }
     type(type, file = this.file.path) {
-        const def = this.checked.project.scopes.get(file)?.get(type.name);
+        const enclosing = this.checked.project.files.get(file)?.items.filter(item => 'typeParams' in item && item.span.start <= type.span.start && item.span.end >= type.span.end) ?? [];
+        const parameter = enclosing.some(item => 'typeParams' in item && (item.typeParams.includes(type.name) || 'methods' in item && item.methods.some(method => method.span.start <= type.span.start && method.span.end >= type.span.end && method.typeParams.includes(type.name))));
+        const def = parameter ? undefined : this.checked.project.scopes.get(file)?.get(type.name);
         this.use(def);
         type.args.forEach(arg => this.type(arg, file));
         return def ? this.link(def, def.name, typeName(type)) : code(typeName(type));
     }
-    notes(span, method, owner) {
-        const doc = method ? callableDocumentation(this.checked.project, method, owner) : javadocBefore(this.file.source, span.start);
-        return doc ? `**Author documentation**\n\n${doc.markdown}\n\n` : '';
+    notes(doc) {
+        if (!doc)
+            return '';
+        const prose = doc.markdown.split(/(?:^|\n\n)\*\*(?:Returns|Parameters|Throws|Deprecated:|See also:)/)[0].trim();
+        const extra = (doc.tags ?? []).filter(tag => tag.name === 'deprecated' || tag.name === 'see').map(tag => tag.name === 'deprecated' ? `Deprecated: ${tag.value}` : `See also: ${tag.value}`);
+        return [prose, ...extra].filter(Boolean).join(' ');
     }
-    generics(node) {
-        return node.typeParams.length ? 'Type parameters: ' + node.typeParams.map(name => code(name) +
+    generics(node, file = this.file.path) {
+        return node.typeParams.length ? 'The type parameters are ' + coordinate(node.typeParams.map(name => code(name) +
             (node.typeVariance?.[name] ? ` (${node.typeVariance[name] === 'out' ? 'produces values' : 'accepts values'})` : '') +
-            (node.typeConstraints?.[name]?.length ? ` must satisfy ${node.typeConstraints[name].map(type => this.type(type)).join(' and ')}` : '')).join('; ') + '.\n\n' : '';
+            (node.typeConstraints?.[name]?.length ? ` which must satisfy ${coordinate(node.typeConstraints[name].map(type => this.type(type, file)))}` : ''))) + '.' : '';
     }
-    inputs(params, fields = false, file = this.file.path) {
+    inputs(params, fields = false, file = this.file.path, descriptions = new Map()) {
         if (!params.length)
             return '';
-        return '**Inputs**\n\n' + params.map(param => {
+        if (fields && params.length === 1 && params[0].injected) {
+            const param = params[0];
             this.locals.set(param.name, param.type);
-            const parts = [`${code(param.label ?? param.name)} (${this.type(param.type, file)})`];
-            if (param.injected)
-                parts.push('injected; callers omit it');
-            else if (param.source)
-                parts.push(`read from the HTTP ${param.source.kind}${param.source.name ? ' named ' + code(param.source.name) : ''}${param.type.optional ? '; absent value becomes null' : ''}`);
-            else
-                parts.push(param.type.optional ? 'optional labeled input; omission becomes null' : 'required labeled input');
+            return 'The ' + code(param.name) + ' dependency is injected as ' + this.type(param.type, file) + ' and stored ' + (param.mutable ? 'mutably' : 'read-only') +
+                (param.name.startsWith('_') ? ' and privately' : '') + (param.ownership === 'own' ? ' with ownership transferred' : param.ownership === 'borrow' ? ' with permission to mutate it' : '') +
+                (descriptions.has(param.name) ? ' (' + descriptions.get(param.name).replace(/[.!?]$/, '') + ')' : '') + '.';
+        }
+        const describe = (group) => {
+            const param = group[0];
+            group.forEach(param => this.locals.set(param.name, param.type));
+            const name = coordinate(group.map(param => code(param.label ?? param.name))), type = this.type(param.type, file);
+            const simple = { int: group.length === 1 ? 'an integer' : 'integers', float: group.length === 1 ? 'a number' : 'numbers', string: group.length === 1 ? 'a string' : 'strings', bool: group.length === 1 ? 'a boolean' : 'booleans' };
+            let sentence = param.injected ? coordinate(group.map(param => code(param.name))) + ' (' + type + ')' : name + ' as ' + (simple[param.type.name] && !param.type.optional ? simple[param.type.name] : type);
+            if (param.source)
+                sentence += ` from the HTTP ${param.source.kind}${param.source.name ? ' ' + code(param.source.name) : ''}`;
             if (param.ownership === 'own')
-                parts.push('transfers ownership');
+                sentence += ' with ownership transferred';
             else if (param.ownership === 'borrow')
-                parts.push('allows exclusive mutation during the call');
+                sentence += ' with permission to mutate it during the call';
             if (fields)
-                parts.push(`stored as ${code(param.name)}${param.name.startsWith('_') ? ' (private)' : ''}${param.mutable ? ' and mutable' : ' and read-only after initialization'}`);
-            return '- ' + parts.join(' — ') + '.';
-        }).join('\n') + '\n\n';
+                sentence += `, kept ${param.mutable ? 'mutable' : 'read-only'}${param.name.startsWith('_') ? ' and private' : ''}${param.label && param.label !== param.name ? ' as ' + code(param.name) : ''}`;
+            const description = descriptions.get(param.name);
+            if (description)
+                sentence += ' (' + description.replace(/[.!?]$/, '').replace(/^The /, 'the ') + ')';
+            return sentence;
+        };
+        const groups = (injected) => this.parameterGroups(params.filter(param => param.injected === injected), fields, descriptions).map(describe);
+        const supplied = groups(false), injected = groups(true);
+        const queries = params.filter(param => !param.injected && param.source?.kind === 'query');
+        const onlyQueries = queries.length && queries.length === params.filter(param => !param.injected).length;
+        const aliases = queries.filter(param => param.source?.name && param.source.name !== param.name);
+        const typedQueries = queries.filter(param => param.type.name !== 'string');
+        const suppliedText = onlyQueries ? 'It reads ' + coordinate(queries.map(param => code(param.source?.name ?? param.label ?? param.name))) + ' from the HTTP query.' +
+            (aliases.length ? ' ' + coordinate(aliases.map(param => code(param.source.name) + ' is called ' + code(param.name) + ' here')) + '.' : '') +
+            (typedQueries.length ? ' It parses ' + coordinate(typedQueries.map(param => code(param.name) + ' as ' + this.type(param.type, file))) + '.' : '') :
+            supplied.length ? 'It takes ' + coordinate(supplied) + '.' : '';
+        return [suppliedText, injected.length ? 'It gets ' + coordinate(injected) + ' from dependency injection.' : '',
+            params.some(param => param.type.optional) ? 'Omitted optional inputs are null.' : ''].filter(Boolean).join(' ');
+    }
+    parameterGroups(params, fields = false, descriptions = new Map()) {
+        const groups = [];
+        const key = (value) => JSON.stringify([typeName(value.type), value.source, value.ownership, fields && value.mutable, fields && value.name.startsWith('_')]);
+        const alias = (value) => fields && value.label && value.label !== value.name;
+        for (const param of params) {
+            const previous = groups.at(-1)?.[0];
+            if (previous && key(previous) === key(param) && !descriptions.has(param.name) && !descriptions.has(previous.name) && !alias(param) && !alias(previous))
+                groups.at(-1).push(param);
+            else
+                groups.push([param]);
+        }
+        return groups;
     }
-    contract(method) {
+    contract(method, documentation) {
         const effects = this.checked.effectContracts.get(method);
         const layers = this.checked.interceptorPlans.get(method) ?? [];
-        const errors = [...new Set([...method.throws.map(type => { this.type(type, method.span.file); return typeName(type); }), ...layers.flatMap(layer => layer.errors.map(tyName))])];
+        for (const type of method.throws)
+            this.type(type, method.span.file);
+        const errors = callableErrors(this.checked, method);
+        for (const error of this.checked.callableContracts.get(method)?.errors ?? [])
+            this.use(error.def);
         const changes = effects?.changes ?? method.changes ?? [];
         const uses = [...(effects?.uses.values() ?? method.uses ?? [])];
-        let text = this.generics(method) + this.inputs(method.params, false, method.span.file);
-        text += `Returns: ${method.returns.name === 'void' ? 'no value' : (method.returnOwnership === 'own' ? 'ownership of ' : '') + this.type(method.returns, method.span.file)}.\n\n`;
+        const result = [];
+        const generics = this.generics(method), inputs = this.inputs(method.params, false, method.span.file, documentation?.parameters);
+        if (generics)
+            result.push(paragraph(generics));
+        if (inputs)
+            result.push(paragraph(inputs));
+        const facts = [];
+        const returnNote = documentation?.tags?.find(tag => tag.name === 'return' || tag.name === 'returns')?.value ??
+            documentation?.markdown.match(/\*\*Returns\*\* ([^\n]+)/)?.[1];
+        // Implementations explain their actual returns below. Contracts need the
+        // result type; repeating it before every return adds noise to the narrative.
+        const resultType = callableResult(this.checked, method);
+        const reference = (type) => ({ name: type.name, args: type.args.map(reference), nullable: type.nullable, optional: type.optional, span: method.returns.span });
+        const returns = reference(resultType);
+        this.use(resultType.def);
+        this.type(returns, method.span.file);
+        if (returns.name !== 'void' && (!method.body || returnNote || method.returnOwnership === 'own'))
+            facts.push(`It returns ${(method.returnOwnership === 'own' ? 'ownership of ' : '') + this.type(returns, method.span.file)}` +
+                (returnNote ? ` — ${returnNote.replace(/[.!?]$/, '')}` : '') + '.');
         if (changes.length)
-            text += 'May change: ' + changes.map(code).join(', ') + '.\n\n';
-        if (uses.length)
-            text += 'Capabilities: ' + uses.map(effect => {
-                const def = 'capability' in effect ? effect.capability?.def : undefined;
-                const target = def ?? this.definition(effect.source);
-                const operation = target && 'methods' in target.node ? target.node.methods.find(method => method.name === effect.operation) : undefined;
-                this.use(target, operation);
-                return target ? this.link(target, operation ? `${target.name}.${operation.name}` : target.name, `${effect.source}.${effect.operation}`) : code(`${effect.source}.${effect.operation}`);
-            }).join(', ') + '.\n\n';
-        if (errors.length)
-            text += 'Can fail with ' + errors.map(code).join(', ') + '. Callers must catch or propagate these errors.\n\n';
+            facts.push('It may change ' + coordinate(changes.map(code)) + '.');
+        const capabilities = uses.map(effect => {
+            const def = 'capability' in effect ? effect.capability?.def : undefined;
+            const target = def ?? this.definition(effect.source);
+            const operation = target && 'methods' in target.node ? target.node.methods.find(method => method.name === effect.operation) : undefined;
+            this.use(target, operation);
+            return target ? this.link(target, operation ? `${target.name}.${operation.name}` : target.name, `${effect.source}.${effect.operation}`) : code(`${effect.source}.${effect.operation}`);
+        });
+        if (capabilities.length && !method.body)
+            facts.push('It can call ' + coordinate(capabilities) + '.');
+        if (errors.length && !method.endpoint)
+            facts.push('Failures can raise ' + coordinate(errors.map(name => {
+                const note = documentation?.tags?.find(tag => (tag.name === 'throws' || tag.name === 'exception') && tag.value.startsWith(name + ' '))?.value.slice(name.length).trim() ??
+                    documentation?.markdown.split('**Throws**\n')[1]?.split('\n\n')[0]?.split('\n').find(line => line.startsWith('- ' + code(name) + ': '))?.slice(('- ' + code(name) + ': ').length);
+                const def = this.checked.project.scopes.get(method.span.file)?.get(name);
+                return (def ? this.link(def) : code(name)) + (note ? ` (${note.replace(/[.!?]$/, '').replace(/^When\b/, 'when')})` : '');
+            })) + '.');
+        if (facts.length)
+            result.push(paragraph(facts.join(' ')));
         if (method.endpoint) {
             const endpoint = method.endpoint;
-            text += `HTTP route: ${code(endpoint.method)} ${code(endpoint.path)}. ` +
-                (endpoint.streams ? `Stream ${this.type(method.returns)} items. ` : `Use status ${endpoint.status} when the handler returns a body; a returned HttpResponse can set its own status. `) +
-                'An unhandled request failure returns status 500 and cancels its request tasks.\n\n';
+            if (endpoint.streams)
+                result.push(paragraph(`It streams ${this.type(method.returns)} items.`));
+            else if (endpoint.status !== 200)
+                result.push(paragraph(`A plain response body uses HTTP status ${endpoint.status}.`));
             if (endpoint.errors.length)
-                text += 'Declared HTTP failures: ' + endpoint.errors.map(error => `${this.type(error.type)} returns status ${error.status}`).join('; ') + '.\n\n';
+                result.push(paragraph('The handler responds with ' + coordinate(endpoint.errors.map(error => `HTTP ${error.status} for ${this.type(error.type)}`)) + '.'));
+            const unmapped = errors.filter(name => !endpoint.errors.some(error => typeName(error.type) === name));
+            if (unmapped.length)
+                result.push(paragraph('It can also raise ' + coordinate(unmapped.map(code)) + '.'));
         }
-        return text;
+        return result;
     }
     layers(node) {
         const layers = this.checked.interceptorPlans.get(node) ?? [];
         const policies = node.kind === 'function' ? this.checked.httpPolicies.get(node) ?? [] : [];
         if (!layers.length && !policies.length)
-            return '';
-        let text = '**Interceptors, in execution order**\n\n';
-        policies.forEach((policy, index) => {
-            text += `${index + 1}. ${this.policy(policy)}` +
-                (node.kind === 'function' && policy.dependencies.length ? ' Use ' + policy.dependencies.map(index => code(node.params[index].name)).join(', ') + '.' : '') + '\n';
+            return [];
+        const steps = [];
+        policies.forEach(policy => {
+            steps.push(this.policy(policy) +
+                (node.kind === 'function' && policy.dependencies.length ? ' Use ' + policy.dependencies.map(index => code(node.params[index].name)).join(', ') + '.' : ''));
         });
-        layers.forEach((layer, index) => {
+        layers.forEach(layer => {
             this.use(layer.definition, layer.around);
-            text += `${index + policies.length + 1}. Call ${this.link(layer.definition, `${layer.definition.name}.around`)}. ` +
-                'It can call the next layer or finish with its own result or failure. ' +
-                (layer.annotation.mappings.length ? 'Map ' + layer.annotation.mappings.map(mapping => code(mapping.source) + ' to ' + code(mapping.name)).join(', ') + '. ' : '') +
-                'Unselected inputs pass through.\n';
+            steps.push(`Call ${this.link(layer.definition, `${layer.definition.name}.around`)}.` +
+                (layer.annotation.mappings.length ? ' Map ' + layer.annotation.mappings.map(mapping => code(mapping.source) + ' to ' + code(mapping.name)).join(', ') + '.' : ''));
         });
-        return text + '\nThe first layer wraps the remaining layers. HTTP policies run before wire decoding; custom interceptors run after decoding. Follow linked behavior to see its conditions, input changes, and calls to the next layer.\n\n';
+        return [paragraph('Layers run in the declared order. ' + steps.join(' ')),
+            ...(policies.length ? [paragraph('HTTP policies run before decoding; custom interceptors run after it.')] : [])];
     }
     policy(policy) {
         const options = policy.options;
@@ -202,10 +280,12 @@ class SpecWriter {
             case 'Compress': return 'Negotiate gzip. Respect existing Content-Encoding and bodyless statuses. Encode stream items as complete concatenated gzip members.';
         }
     }
-    receiver(expr) {
-        const checked = this.checked.expressionTypes.get(expr)?.def;
-        if (checked)
-            return checked;
+    receiver(expr, operation) {
+        const checked = this.checked.expressionTypes.get(expr);
+        if (checked?.def)
+            return checked.def;
+        if (checked?.kind === 'param')
+            return checked.bounds?.find(bound => bound.def && (!operation || this.method(bound.def, operation)))?.def;
         const ref = expr.kind === 'name' ? this.locals.get(expr.name) : undefined;
         if (ref)
             return this.definition(ref.name);
@@ -216,7 +296,7 @@ class SpecWriter {
             if (def?.node.kind === 'class')
                 return def;
             if (def?.node.kind === 'function')
-                return this.definition(def.node.returns.name);
+                return callableResult(this.checked, def.node).def;
         }
         return undefined;
     }
@@ -246,57 +326,196 @@ class SpecWriter {
                 return def ? this.link(def) : code(expr.name);
             }
             case 'member': {
-                const def = this.receiver(expr.object);
+                const def = this.receiver(expr.object, expr.name);
                 this.use(def, undefined, expr.name);
                 const name = expr.name, receiverType = this.checked.expressionTypes.get(expr.object)?.name;
                 const property = receiverType && builtinProperties[receiverType]?.find(property => property.name === name);
                 if (property)
                     this.properties.set(receiverType + '.' + name, { ...property, type: this.checked.expressionTypes.get(expr) ? tyName(this.checked.expressionTypes.get(expr)) : property.type });
-                return `${code(name)} of ${this.expression(expr.object)}`;
+                const object = this.expression(expr.object), path = this.memberPath(expr);
+                return path ? code(path) : `${code(name)} of ${object}`;
             }
             case 'unary': {
                 if (expr.op === '!' && expr.value.kind === 'binary' && (expr.value.op === '==' || expr.value.op === '!='))
                     return `${this.expression(expr.value.left, true)} ${expr.value.op === '==' ? 'does not equal' : 'equals'} ${this.expression(expr.value.right, true)}`;
+                if (expr.op === '!' && expr.value.kind === 'call')
+                    return this.predicate(expr.value, false);
                 return `${expr.op === '!' ? 'not' : 'the negative of'} (${this.expression(expr.value)})`;
             }
             case 'binary': {
                 const words = { '+': 'plus', '-': 'minus', '*': 'times', '/': 'divided by', '==': 'equals', '!=': 'does not equal', '<': 'is less than', '>': 'is greater than', '<=': 'is at most', '>=': 'is at least', '&&': 'and', '||': 'or' };
                 if (!words[expr.op])
                     throw new Error(`No specification renderer for operator ${expr.op}`);
+                if (expr.right.kind === 'literal' && expr.right.value === null && ['==', '!='].includes(expr.op))
+                    return this.expression(expr.left) + (expr.op === '==' ? ' is null' : ' is not null');
+                if (expr.right.kind === 'literal' && expr.right.value === 0 && ['>', '<'].includes(expr.op))
+                    return this.expression(expr.left) + (expr.op === '>' ? ' is positive' : ' is negative');
                 const textParts = this.stringParts(expr);
-                if (expr.op === '+' && textParts.length >= 3)
-                    return 'text formed by joining ' + textParts.map(part => this.expression(part)).join(', ') + ' in order';
-                const result = `${this.expression(expr.left, expr.left.kind === 'binary')} ${words[expr.op]} ${this.expression(expr.right, expr.right.kind === 'binary')}`;
+                if (expr.op === '+' && textParts.length >= 2) {
+                    const text = textParts.map(part => part.kind === 'literal' && typeof part.value === 'string' ?
+                        part.value.replaceAll('{', '{{').replaceAll('}', '}}') : '{' + plain(this.expression(part)) + '}').join('');
+                    return 'the text ' + code(text);
+                }
+                const child = (value) => this.expression(value, value.kind === 'binary' && !(['&&', '||'].includes(expr.op) &&
+                    (value.op === expr.op || ['==', '!=', '<', '>', '<=', '>='].includes(value.op))));
+                const result = `${child(expr.left)} ${words[expr.op]} ${child(expr.right)}`;
                 return nested ? `(${result})` : result;
             }
             case 'collection': {
                 if (expr.collection === 'Map')
                     return 'a map with ' + expr.items.filter((_, index) => index % 2 === 0).map((key, index) => `${this.expression(key)} mapped to ${this.expression(expr.items[index * 2 + 1])}`).join('; ');
+                const first = expr.items[0];
+                if (expr.collection === 'List' && expr.items.length >= 3 && first?.kind === 'call' && first.callee.kind === 'name' && !this.locals.has(first.callee.name)) {
+                    const name = first.callee.name, def = this.definition(name);
+                    const labels = first.argLabels;
+                    if (def?.node.kind === 'class' && def.node.record && labels.every(Boolean) && expr.items.every(item => item.kind === 'call' && item.callee.kind === 'name' && item.callee.name === name &&
+                        item.typeArgs.map(typeName).join(',') === first.typeArgs.map(typeName).join(',') &&
+                        item.args.every(arg => arg.kind === 'literal') && item.argLabels.length === labels.length &&
+                        item.argLabels.every((label, index) => label === labels[index]))) {
+                        this.call(first);
+                        const rows = expr.items.map(item => code('(' + item.args.map(arg => arg.kind === 'literal' ? arg.numericText ?? JSON.stringify(arg.value) : '').join(', ') + ')'));
+                        return `a list of ${expr.items.length} ${this.link(def)} records, with ${code('(' + labels.join(', ') + ')')} values of ${coordinate(rows)}, in that order`;
+                    }
+                }
                 return `a ${expr.collection === 'empty' ? 'context-typed empty collection' : expr.collection.toLowerCase()}` + (expr.items.length ? ' containing ' + expr.items.map(item => this.expression(item)).join(', ') : ' with no items');
             }
             case 'resolve': return `the instance provided for ${code(expr.name)}${expr.typeArgs.length ? ' with type arguments ' + expr.typeArgs.map(type => this.type(type)).join(', ') : ''}`;
-            case 'call': return this.call(expr);
-            case 'start': return `a child task that starts ${this.expression(expr.call)}; evaluate its receiver and inputs now, and run its operation concurrently`;
-            case 'wait': return `the results of waiting for ${expr.tasks.map(task => this.expression(task)).join(' and ')}; keep input order when returning a tuple or a list, join cleanup, and propagate the first failure`;
+            case 'call': {
+                const action = this.call(expr);
+                const known = this.knownValue(expr);
+                if (known)
+                    return known;
+                if (expr.callee.kind === 'member') {
+                    const receiver = expr.callee.object, type = this.checked.expressionTypes.get(receiver)?.name;
+                    if (!this.receiver(receiver) && ['string', 'Bytes', 'List', 'Set', 'Map', 'Tuple'].includes(type ?? '') && !expr.args.length) {
+                        const value = this.expression(receiver);
+                        if (expr.callee.name === 'bytes' && type === 'string')
+                            return 'the UTF-8 bytes of ' + value;
+                        if (expr.callee.name === 'base64url' && type === 'Bytes')
+                            return 'the URL-safe base64 encoding of ' + value;
+                        if (expr.callee.name === 'length')
+                            return (type === 'string' || type === 'Bytes' ? 'the byte length of ' : 'the number of elements in ') + value;
+                    }
+                }
+                const name = expr.callee.kind === 'name' ? expr.callee.name : '';
+                return action.startsWith('construct ') ? (/^[AEIOU]/i.test(name) ? 'an ' : 'a ') + action.slice('construct '.length) :
+                    action.startsWith('call ') ? action.slice('call '.length) : action;
+            }
+            case 'start': return `a child task running ${this.expression(expr.call)} with its inputs captured now`;
+            case 'wait': return `the result of waiting for ${expr.tasks.map(task => this.expression(task)).join(' and ')}${expr.tasks.length > 1 ? ' in input order' : ''}; propagate failures`;
             case 'handle': {
-                const plan = this.checked.actions.get(expr);
-                return `a deferred HTTP form action for ${plan ? this.link(plan.endpoint) : this.expression(expr.call)}` +
-                    (expr.call.kind === 'call' && expr.call.args.length ? '; inputs: ' + expr.call.args.map((value, index) => (expr.call.kind === 'call' ? code(expr.call.argLabels[index] ?? (value.kind === 'name' ? value.name : String(index + 1))) + ' from ' : '') + this.expression(value)).join('; ') : '') +
-                    '; capture supplied values when rendering, and read form inputs when submitted; send the form to that endpoint with its declared HTTP method';
+                const plan = this.checked.actions.get(expr), endpoint = plan?.endpoint.node.kind === 'function' ? plan.endpoint.node.endpoint : undefined;
+                const captures = expr.call.kind === 'call' ? expr.call.args.filter(value => value.kind !== 'formInput').map(value => this.expression(value)) : [];
+                return endpoint ? `a form action that sends ${code(endpoint.method + ' ' + endpoint.path)} to ${this.link(plan.endpoint)} on submission` +
+                    (captures.length ? ' with captured ' + coordinate(captures) : '') : `a form action for ${this.expression(expr.call)}`;
             }
-            case 'formInput': return 'the checked form input supplied when the HTTP form is submitted';
+            case 'formInput': return 'the submitted form data';
             case 'markupText': return code(expr.text);
             case 'markup': {
                 const def = this.definition(expr.tag);
                 this.use(def);
-                return (def ? 'the server component ' + this.link(def) : 'the HTML element ' + code(expr.tag || 'fragment')) +
+                const elements = { p: 'a paragraph', h1: 'a heading', h2: 'a heading', button: 'a button', a: 'a link' };
+                return (def ? 'the server component ' + this.link(def) : elements[expr.tag] ?? 'the HTML element ' + code(expr.tag || 'fragment')) +
                     (expr.attributes.length ? ' with ' + expr.attributes.map(attribute => `${code(attribute.name)} = ${this.expression(attribute.value)}`).join(', ') : '') +
                     (expr.children.length ? ' containing ' + expr.children.map(child => this.expression(child)).join(', ') : '') +
-                    ' (rendered on the server with embedded text escaped)';
+                    ' with escaped text';
             }
             default: return unreachable(expr);
         }
     }
+    memberPath(expr) {
+        if (expr.kind === 'name' && !this.definition(expr.name))
+            return expr.name;
+        if (expr.kind === 'name' && this.locals.has(expr.name))
+            return expr.name;
+        if (expr.kind === 'member') {
+            const object = this.memberPath(expr.object);
+            return object ? object + '.' + expr.name : undefined;
+        }
+    }
+    argument(expr, label) {
+        const explicit = expr.args.findIndex((arg, index) => (expr.argLabels[index] ?? (arg.kind === 'name' ? arg.name : '')) === label);
+        if (explicit >= 0)
+            return expr.args[explicit];
+        const plan = this.checked.callPlans.get(expr);
+        const def = expr.callee.kind === 'name' ? this.definition(expr.callee.name) : expr.callee.kind === 'member' ? this.receiver(expr.callee.object, expr.callee.name) : undefined;
+        const method = def?.node.kind === 'function' ? def.node : expr.callee.kind === 'member' && def ? this.method(def, expr.callee.name) : undefined;
+        const params = method?.params ?? (def?.node.kind === 'class' ? def.node.fields : []);
+        const slot = params.findIndex(param => (param.label ?? param.name) === label);
+        const index = slot >= 0 ? plan?.sourceIndices[slot] : undefined;
+        return index !== undefined && index >= 0 ? expr.args[index] : undefined;
+    }
+    /** Interpret only compiler built-ins and the canonical standard-library contracts. */
+    standardOperation(expr) {
+        if (expr.callee.kind !== 'member')
+            return;
+        const def = this.receiver(expr.callee.object, expr.callee.name);
+        if (!def || !this.checked.project.files.get(def.file)?.builtin)
+            return;
+        return libraryRelative(this.checked.project.libraries, def.file).replaceAll('\\', '/') + ':' + def.name + '.' + expr.callee.name;
+    }
+    knownValue(expr) {
+        const arg = (label) => { const value = this.argument(expr, label); return value ? this.expression(value) : undefined; };
+        const receiver = expr.callee.kind === 'member' ? this.expression(expr.callee.object) : '';
+        switch (this.standardOperation(expr)) {
+            case 'crypto/contracts.aug:Crypto.random':
+            case 'crypto/contracts.aug:GnuTlsCrypto.random':
+                return `${arg('size')} random bytes from ${receiver}`;
+            case 'crypto/contracts.aug:Crypto.decodeBase64url':
+            case 'crypto/contracts.aug:GnuTlsCrypto.decodeBase64url':
+                return `${arg('input')} decoded as URL-safe base64 by ${receiver}`;
+            case 'time/contracts.aug:Clock.now':
+            case 'time/contracts.aug:SystemClock.now': return 'the current time from ' + receiver;
+            case 'memory/store.aug:ExpiringStore.take':
+            case 'memory/store.aug:MemoryStore.take':
+                return `the live value removed from ${receiver} under ${arg('key')}, using ${arg('now')} as the current time`;
+            case 'memory/store.aug:ExpiringStore.get':
+            case 'memory/store.aug:MemoryStore.get':
+                return `the live value in ${receiver} under ${arg('key')}, using ${arg('now')} as the current time`;
+        }
+        if (expr.callee.kind === 'member' && !this.receiver(expr.callee.object)) {
+            const type = this.checked.expressionTypes.get(expr.callee.object)?.name;
+            if (expr.callee.name === 'get' && type === 'List')
+                return `the item at index ${arg('index')} in ${receiver}`;
+            if (expr.callee.name === 'get' && type === 'Map')
+                return `the value under ${arg('key')} in ${receiver}`;
+            if (expr.callee.name === 'contains' && type === 'Map')
+                return `whether ${receiver} contains the key ${arg('key')}`;
+            if (expr.callee.name === 'contains' && type === 'Set')
+                return `whether ${receiver} contains ${arg('value')}`;
+            if (expr.callee.name === 'with' && type === 'Headers')
+                return `${receiver} with the header ${arg('name')} set to ${arg('value')}`;
+        }
+        if (expr.callee.kind === 'name') {
+            const def = this.definition(expr.callee.name);
+            if (def?.file && this.checked.project.files.get(def.file)?.builtin && libraryRelative(this.checked.project.libraries, def.file).replaceAll('\\', '/') === 'web/contracts.aug' && def.name === 'urlEncode')
+                return 'URL-encoded ' + arg('input');
+            if (this.checked.expressionTypes.get(expr)?.name === 'Html') {
+                const message = this.argument(expr, 'message');
+                if (message && expr.args.length === 1)
+                    return this.expression(expr.callee) + ' showing ' + this.expression(message);
+            }
+        }
+        if (expr.callee.kind === 'name' && !this.definition(expr.callee.name) && expr.callee.name === 'HttpResponse') {
+            const body = arg('body'), status = arg('status') ?? '200', headers = arg('headers');
+            return `HTTP ${status.replaceAll('`', '')} with ${body ?? 'an empty body'}` + (headers ? ' and ' + headers + ' headers' : '');
+        }
+    }
+    predicate(expr, expected = true) {
+        this.call(expr);
+        if (expr.callee.kind === 'member' && !this.receiver(expr.callee.object) &&
+            this.checked.expressionTypes.get(expr.callee.object)?.name === 'string' && expr.callee.name === 'isToken') {
+            const min = this.argument(expr, 'min'), max = this.argument(expr, 'max');
+            return this.expression(expr.callee.object) + ` is ${expected ? '' : 'not '}a URL-safe ASCII token` +
+                (min && max ? ' with ' + this.expression(min) + ' to ' + this.expression(max) + ' characters' : '');
+        }
+        const operation = this.standardOperation(expr);
+        if (operation === 'crypto/contracts.aug:Crypto.equal' || operation === 'crypto/contracts.aug:GnuTlsCrypto.equal') {
+            const left = this.argument(expr, 'left'), right = this.argument(expr, 'right');
+            return this.expression(left) + ' and ' + this.expression(right) + (expected ? ' match' : ' differ') + ' when compared by ' + this.expression(expr.callee.kind === 'member' ? expr.callee.object : expr.callee);
+        }
+        return this.expression(expr) + ` returns ${expected ? 'true' : 'false'}`;
+    }
     call(expr) {
         if (expr.callee.kind === 'name' && ['List', 'Set', 'Map'].includes(expr.callee.name) && !this.definition(expr.callee.name)) {
             const name = expr.callee.name, types = expr.typeArgs.map(type => this.type(type));
@@ -305,13 +524,14 @@ class SpecWriter {
                 name.toLowerCase() + ' of ' + (types[0] ?? 'any');
             return items.length ? 'a ' + label + ' containing ' + items.join(', ') : 'an empty ' + label;
         }
-        let target, method;
+        let target, method, constructs = false;
         if (expr.callee.kind === 'name') {
             const name = expr.callee.name;
             const def = this.definition(expr.callee.name);
             this.use(def);
             if (def?.node.kind === 'class' && def.file !== this.file.path)
                 this.used.get(def.id).constructed = true;
+            constructs = def?.node.kind === 'class' || !def && Object.hasOwn(builtinTypes, name);
             method = def?.node.kind === 'function' ? def.node : undefined;
             const builtin = !def && builtinFunctions.find(operation => operation.name === name);
             if (builtin)
@@ -320,7 +540,7 @@ class SpecWriter {
         }
         else if (expr.callee.kind === 'member') {
             const name = expr.callee.name;
-            const def = this.receiver(expr.callee.object);
+            const def = this.receiver(expr.callee.object, expr.callee.name);
             method = def && this.method(def, expr.callee.name);
             this.use(def, method);
             const receiver = this.checked.expressionTypes.get(expr.callee.object);
@@ -335,7 +555,10 @@ class SpecWriter {
             // An inherited operation links to the interface that actually declares it.
             const owner = method && [...this.checked.project.definitions.values()].find(def => 'methods' in def.node && def.node.methods.includes(method));
             this.use(owner, method);
-            target = (owner ? this.link(owner, `${owner.name}.${method.name}`) : code(expr.callee.name)) + ' on ' + this.expression(expr.callee.object);
+            const object = this.expression(expr.callee.object), path = this.memberPath(expr.callee);
+            target = owner ? this.link(owner, `${owner.name}.${method.name}`, path ?? expr.callee.name) : code(path ?? expr.callee.name);
+            if (!path)
+                target += ' on ' + object;
         }
         else
             target = this.expression(expr.callee);
@@ -346,12 +569,19 @@ class SpecWriter {
         const inputs = expr.args.map((arg, index) => {
             const slot = plan?.sourceIndices.indexOf(index);
             const label = expr.argLabels[index] ?? (slot !== undefined && slot >= 0 ? parameters[slot]?.label ?? parameters[slot]?.name : arg.kind === 'name' ? arg.name : undefined);
-            return (label ? code(label) + ' = ' : '') + (arg.kind === 'binary' ? '(' + this.expression(arg) + ')' : this.expression(arg));
+            const same = arg.kind === 'name' && arg.name === label || arg.kind === 'member' && arg.name === label;
+            const value = this.expression(arg);
+            return label && !same ? code(label) + (arg.kind === 'literal' ? ' ' : ' from ') + value : value;
+        });
+        let text = `${constructs ? 'construct' : 'call'} ${target}` + (expr.typeArgs.length ? ' for ' + coordinate(expr.typeArgs.map(type => this.type(type))) : '') + (inputs.length ? ' with ' + coordinate(inputs) : '');
+        const injected = parameters.flatMap((param, index) => {
+            if (!param.injected)
+                return [];
+            const source = plan?.injectionSources?.[index] ?? plan?.bindingKeys[index] ?? typeName(param.type);
+            return [code(source) + (source === param.name ? '' : ' for ' + code(param.name))];
         });
-        let text = `call ${target}` + (expr.typeArgs.length ? ' with type arguments ' + expr.typeArgs.map(type => this.type(type)).join(', ') : '') + (inputs.length ? ' with ' + inputs.join('; ') : '');
-        const injected = parameters.flatMap((param, index) => param.injected ? [`${code(param.name)} from ${code(plan?.injectionSources?.[index] ?? plan?.bindingKeys[index] ?? typeName(param.type))}`] : []);
         if (injected.length)
-            text += '; inject ' + injected.join(', ');
+            text += ' using injected ' + coordinate(injected);
         return text;
     }
     stringParts(expr) {
@@ -359,21 +589,55 @@ class SpecWriter {
             return [...this.stringParts(expr.left), ...this.stringParts(expr.right)];
         return [expr];
     }
-    joinedText(target, value, depth) {
-        const parts = this.stringParts(value);
-        if (parts.length < 4)
+    joinedText(target, value) {
+        if (this.stringParts(value).length < 2)
             return;
-        const indent = '  '.repeat(depth), child = '  '.repeat(depth + 1);
-        return `${indent}- Build ${target} by joining these text parts without separators, in order:\n` +
-            parts.map((part, index) => `${child}${index + 1}. ${this.expression(part)}\n`).join('');
+        return step(`It builds ${target} as ${this.expression(value)}.`);
+    }
+    headerFields(value) {
+        let current = value;
+        const calls = [];
+        while (current.kind === 'call' && current.callee.kind === 'member' && current.callee.name === 'with' &&
+            this.checked.expressionTypes.get(current.callee.object)?.name === 'Headers') {
+            const labels = current.args.map((arg, index) => current.kind === 'call' ?
+                current.argLabels[index] ?? (arg.kind === 'name' ? arg.name : '') : ''), name = labels.indexOf('name'), value = labels.indexOf('value');
+            if (name < 0 || value < 0)
+                return;
+            calls.unshift(current);
+            current = current.callee.object;
+        }
+        if (calls.length < 3)
+            return;
+        const operation = collectionOperations.Headers?.find(operation => operation.name === 'with');
+        if (operation)
+            this.builtins.set('Headers.with', operation);
+        return { base: current, fields: calls.map(call => {
+                const labels = call.args.map((arg, index) => call.argLabels[index] ?? (arg.kind === 'name' ? arg.name : ''));
+                return `${this.expression(call.args[labels.indexOf('name')])} to ${this.expression(call.args[labels.indexOf('value')])}`;
+            }) };
+    }
+    statements(body) {
+        const result = [];
+        for (let index = 0; index < body.length; index++) {
+            const stmt = body[index], nodes = this.statement(stmt), tail = body[index + 1];
+            // A terminal guard and final return are exact alternatives, even without a written else.
+            if (stmt.kind === 'if' && !stmt.otherwise.length && index === body.length - 2 && tail?.kind === 'return' &&
+                stmt.then.at(-1)?.kind === 'return' && nodes[0].kind === 'branch') {
+                nodes[0].otherwise = this.statement(tail);
+                index++;
+            }
+            result.push(...nodes);
+        }
+        return result;
     }
-    statements(body, depth = 0) {
-        if (!body.length)
-            return '  '.repeat(depth) + '- Finish this block without another operation.\n';
-        return body.map(stmt => this.statement(stmt, depth)).join('');
+    statement(stmt) {
+        const nodes = this.explainStatement(stmt);
+        // Source identities survive sentence aggregation. Two identical calls are still two facts.
+        nodes[0].source = `${stmt.span.file}:${stmt.span.start}:${stmt.span.end}`;
+        return nodes;
     }
-    statement(stmt, depth) {
-        const lead = '  '.repeat(depth) + '- ', nested = (body) => this.statements(body, depth + 1);
+    explainStatement(stmt) {
+        const nested = (body) => this.statements(body);
         switch (stmt.kind) {
             case 'assign': {
                 if (stmt.target.kind === 'name') {
@@ -386,42 +650,133 @@ class SpecWriter {
                             this.locals.set(stmt.target.name, { name: def.name, args: [], nullable: false, span: stmt.span });
                     }
                 }
-                const target = this.expression(stmt.target) + (stmt.declaredType ? ' of type ' + this.type(stmt.declaredType) : '');
-                return (this.joinedText(target, stmt.value, depth) ?? lead + `Set ${target} to ${this.expression(stmt.value)}.\n`) +
-                    (stmt.ownership === 'own' ? lead + 'This variable owns the value.\n' : '');
+                if (stmt.declaredType)
+                    this.type(stmt.declaredType);
+                const target = this.expression(stmt.target) + (stmt.declaredType && !['int', 'float', 'string', 'bool'].includes(stmt.declaredType.name) ? ' of type ' + this.type(stmt.declaredType) : '');
+                const headers = this.headerFields(stmt.value);
+                const arithmetic = stmt.value.kind === 'binary' && ['+', '-'].includes(stmt.value.op) && stmt.value.left.kind === 'name' && stmt.target.kind === 'name' && stmt.target.name === stmt.value.left.name && ['int', 'float', 'c_int'].includes(this.checked.expressionTypes.get(stmt.value)?.name ?? '');
+                const headerLead = headers ? `set ${target} from ${this.expression(headers.base)} by adding these header fields in order` : undefined;
+                const getter = stmt.value.kind === 'call' && !stmt.value.args.length && stmt.value.callee.kind === 'name' && this.definition(stmt.value.callee.name)?.node.kind === 'function';
+                const explanation = headers ? sequence('It ' + headerLead.replace(/^set /, 'sets '), headers.fields, headerLead) :
+                    getter ? step('It gets ' + target + ' from ' + this.expression(stmt.value) + '.') :
+                        this.joinedText(target, stmt.value) ?? (arithmetic && stmt.value.kind === 'binary' ? action(stmt.value.op === '+' ? 'increase' : 'decrease', `${target} by ${this.expression(stmt.value.right)}`) : action('set', `${target} to ${this.expression(stmt.value)}`));
+                return stmt.ownership === 'own' ? [explanation, step(`${target} owns this value.`)] : [explanation];
+            }
+            case 'destructure': return [action('split', `${this.expression(stmt.value)} into ${coordinate(stmt.names.map(code))} in order`)];
+            case 'expr': {
+                if (stmt.expr.kind === 'literal' && stmt.expr.value === null)
+                    return [action('continue', 'without an operation')];
+                if (stmt.expr.kind === 'call') {
+                    const call = this.call(stmt.expr);
+                    if (stmt.expr.callee.kind === 'name' && !this.definition(stmt.expr.callee.name)) {
+                        if (stmt.expr.callee.name === 'print')
+                            return [step('It prints ' + this.expression(stmt.expr.args[0]) + '.')];
+                        if (stmt.expr.callee.name === 'assert')
+                            return [step('The test requires ' + this.condition(stmt.expr.args[0]) + '.')];
+                    }
+                    if (stmt.expr.callee.kind === 'member') {
+                        const receiver = stmt.expr.callee.object, def = this.receiver(receiver, stmt.expr.callee.name), method = def && this.method(def, stmt.expr.callee.name);
+                        const type = this.checked.expressionTypes.get(receiver)?.name;
+                        const arg = (name) => this.expression(this.argument(stmt.expr, name));
+                        if (!def) {
+                            if (type === 'List' && stmt.expr.callee.name === 'append')
+                                return [step('It appends ' + arg('value') + ' to ' + this.expression(receiver) + '.')];
+                            if (type === 'Set' && stmt.expr.callee.name === 'add')
+                                return [step('It adds ' + arg('value') + ' to ' + this.expression(receiver) + '.')];
+                            if (type === 'Map' && stmt.expr.callee.name === 'set')
+                                return [step('It stores ' + arg('value') + ' in ' + this.expression(receiver) + ' under ' + arg('key') + '.')];
+                            if (type === 'Map' && stmt.expr.callee.name === 'take')
+                                return [step('It removes the key ' + arg('key') + ' from ' + this.expression(receiver) + '.')];
+                        }
+                        if (method && callableResult(this.checked, method).name === 'void' && method.params.filter(param => !param.injected).length === 1 && stmt.expr.args.length === 1) {
+                            const owner = [...this.checked.project.definitions.values()].find(owner => 'methods' in owner.node && owner.node.methods.includes(method));
+                            const target = this.link(owner, owner.name + '.' + method.name, this.memberPath(stmt.expr.callee) ?? method.name);
+                            const plan = this.checked.callPlans.get(stmt.expr);
+                            const injected = method.params.flatMap((param, index) => param.injected ? [code(plan?.injectionSources?.[index] ?? plan?.bindingKeys[index] ?? typeName(param.type))] : []);
+                            return [step('It passes ' + this.expression(stmt.expr.args[0]) + ' to ' + target + (injected.length ? ', using injected ' + coordinate(injected) : '') + '.')];
+                        }
+                    }
+                    const stored = this.standardOperation(stmt.expr);
+                    if (stored === 'memory/store.aug:ExpiringStore.put' || stored === 'memory/store.aug:MemoryStore.put') {
+                        const arg = (name) => this.expression(this.argument(stmt.expr, name));
+                        return [step(`It stores ${arg('value')} in ${this.expression(stmt.expr.callee.kind === 'member' ? stmt.expr.callee.object : stmt.expr.callee)} under ${arg('key')}, expiring at ${arg('expires')}. The current time for this write is ${arg('now')}.`)];
+                    }
+                    if (call.startsWith('call '))
+                        return [action('call', call.slice(5))];
+                    if (call.startsWith('construct '))
+                        return [action('construct', call.slice(10))];
+                }
+                return [action('evaluate', this.expression(stmt.expr))];
             }
-            case 'destructure': return lead + `Split ${this.expression(stmt.value)} into ${stmt.names.map(code).join(', ')}, in that order.\n`;
-            case 'expr': return lead + (stmt.expr.kind === 'literal' && stmt.expr.value === null ? 'Continue without another operation' : stmt.expr.kind === 'call' ? 'Call ' + this.call(stmt.expr).slice(5) : 'Evaluate ' + this.expression(stmt.expr)) + '.\n';
             case 'return': {
                 if (!stmt.value)
-                    return lead + 'Finish this operation without a result.\n';
-                const joined = this.joinedText('the return value', stmt.value, depth);
-                return joined ? joined + lead + 'Return that value.\n' : lead + 'Return ' + this.expression(stmt.value) + '.\n';
+                    return [action('return', 'without a value')];
+                const headers = this.headerFields(stmt.value);
+                if (headers) {
+                    const lead = `return headers starting with ${this.expression(headers.base)} and adding these fields in order`;
+                    return [sequence('It ' + lead.replace(/^return /, 'returns '), headers.fields, lead)];
+                }
+                return [action('return', this.expression(stmt.value))];
             }
-            case 'throw': return lead + 'Fail with ' + this.expression(stmt.value) + '. Transfer control to a matching catch or propagate the failure.\n';
-            case 'yield': return lead + 'Send ' + this.expression(stmt.value) + ' as the next stream item. Honor backpressure before producing more items.\n';
-            case 'if': return lead + 'If ' + this.condition(stmt.test) + ':\n' + nested(stmt.then) + (stmt.otherwise.length ? lead + 'Otherwise:\n' + nested(stmt.otherwise) : '');
-            case 'while': return lead + 'While ' + this.condition(stmt.test) + ', repeat:\n' + nested(stmt.body) + '  '.repeat(depth + 1) + '- Check the condition again before the next iteration.\n';
-            case 'for': return lead + 'For each ' + stmt.names.map(code).join(' and ') + ' in a snapshot of ' + this.expression(stmt.iterable) + ', in iteration order:\n' + nested(stmt.body);
-            case 'match': return lead + 'Select the matching case for ' + this.expression(stmt.value) + ':\n' + stmt.cases.map(clause => {
-                const pattern = clause.pattern === 'else' ? 'Any remaining case' : clause.pattern === 'some' ? 'A present, non-null value, named ' + code(clause.name) :
-                    clause.pattern === 'type' ? 'A value that satisfies ' + this.type(clause.type) + ', named ' + code(clause.name) :
-                        clause.pattern === 'literal' ? this.expression(clause.literal) : 'A null value, including omitted optional input';
-                return '  '.repeat(depth + 1) + '- ' + pattern + ':\n' + this.statements(clause.body, depth + 2);
-            }).join('');
-            case 'try': return lead + 'Try these operations:\n' + nested(stmt.body) + stmt.catches.map(clause => lead + 'If they fail with ' + this.type(clause.type) + ', name the failure ' + code(clause.name) + ' and recover:\n' + nested(clause.body)).join('') +
-                (stmt.always ? lead + 'On both success and failure, perform cleanup:\n' + nested(stmt.always) : '');
-            case 'unsafe': return lead + 'Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:\n' + nested(stmt.body);
-            case 'borrow': return lead + 'Grant exclusive mutable access to ' + code(stmt.name) + ' for this block, then end the borrow:\n' + nested(stmt.body);
-            case 'scope': return lead + 'Create a dependency and task scope. Join its child tasks and release scoped values before leaving:\n' + nested(stmt.body);
-            case 'lock': return lead + 'Lock ' + this.expression(stmt.value) + ', expose its mutable value as ' + code(stmt.name) + ', and release the lock on every exit:\n' + nested(stmt.body);
-            case 'freeze': return lead + 'Freeze ' + this.expression(stmt.value) + ' as ' + code(stmt.name) + '. Share the immutable value without copying it.\n';
-            case 'serve': return lead + 'Serve ' + stmt.names.map(name => { const def = this.definition(name); return def ? this.link(def) : code(name); }).join(', ') + ' on port ' + this.expression(stmt.port) + '.\n';
+            case 'throw': return [action('fail', 'with ' + this.expression(stmt.value))];
+            case 'yield': return [action('send', this.expression(stmt.value) + ' as the next stream item')];
+            case 'if': {
+                const node = branch(this.condition(stmt.test), nested(stmt.then), nested(stmt.otherwise));
+                if (node.kind === 'branch' && !stmt.otherwise.length && stmt.then.length === 1 && stmt.then[0].kind === 'throw' &&
+                    stmt.then[0].value.kind === 'call' && stmt.then[0].value.args.length === 0)
+                    node.requirement = this.requirement(stmt.test);
+                return [node];
+            }
+            case 'while': return [loop('While ' + this.condition(stmt.test), nested(stmt.body), 'Repeat this loop while its condition remains true.')];
+            case 'for': return [loop('For each ' + coordinate(stmt.names.map(code)) + ' in a snapshot of ' + this.expression(stmt.iterable), nested(stmt.body), 'Repeat these steps for each remaining item in the snapshot.')];
+            case 'match': {
+                const value = this.expression(stmt.value);
+                const terminal = (body) => ['return', 'throw'].includes(body.at(-1)?.kind ?? '');
+                // A null guard that exits is followed only by the non-null path. This is
+                // a sequential explanation, not a nested tour through match syntax.
+                if (stmt.cases.length === 2 && stmt.cases[0].pattern === 'null' && terminal(stmt.cases[0].body) && stmt.cases[1].pattern === 'some') {
+                    const read = stmt.value.kind === 'call', second = stmt.cases[1];
+                    const first = branch(read ? 'no value is found' : value + ' is null', nested(stmt.cases[0].body));
+                    return [...(read ? [step('It obtains ' + value + '.')] : []), first,
+                        step('The non-null ' + (read ? 'result' : value) + ' becomes ' + code(second.name) + '.'), ...nested(second.body)];
+                }
+                return [choice(value, stmt.cases.map(clause => {
+                        const condition = clause.pattern === 'else' ? 'Otherwise' : clause.pattern === 'some' ? 'If ' + value + ' is not null, using ' + code(clause.name) + ' for it' :
+                            clause.pattern === 'type' ? 'If ' + value + ' satisfies ' + this.type(clause.type) + ', using ' + code(clause.name) + ' for it' :
+                                clause.pattern === 'literal' ? 'If ' + value + ' equals ' + this.expression(clause.literal) : 'If ' + value + ' is null';
+                        return { condition, children: nested(clause.body) };
+                    }))];
+            }
+            case 'try': return [attempt(nested(stmt.body), stmt.catches.map(clause => ({ error: this.type(clause.type), name: code(clause.name), children: nested(clause.body) })), stmt.always ? nested(stmt.always) : undefined)];
+            case 'unsafe': return [scope('Within an unsafe block', nested(stmt.body), 'Native operations must satisfy their declared C contracts.')];
+            case 'borrow': return [scope('With temporary permission to change ' + code(stmt.name), nested(stmt.body), '')];
+            case 'scope': return [scope('Within a task and ownership scope', nested(stmt.body), 'On leaving this scope, join its child tasks and release its local values.')];
+            case 'lock': return [scope('While holding the lock on ' + this.expression(stmt.value) + ' as mutable ' + code(stmt.name), nested(stmt.body), 'Release this lock when the block exits, including on return or failure.')];
+            case 'freeze': return [action('freeze', this.expression(stmt.value) + ' as ' + code(stmt.name)), step('The immutable value is shared without copying it.')];
+            case 'serve': return [action('serve', coordinate(stmt.names.map(name => { const def = this.definition(name); return def ? this.link(def) : code(name); })) + ' on port ' + this.expression(stmt.port))];
             default: return unreachable(stmt);
         }
     }
     condition(expr) {
-        return this.expression(expr) + (['binary', 'unary'].includes(expr.kind) ? '' : ' is true');
+        return expr.kind === 'call' ? this.predicate(expr) : this.expression(expr) + (['binary', 'unary'].includes(expr.kind) ? '' : ' is true');
+    }
+    requirement(expr, nested = false) {
+        if (expr.kind === 'unary' && expr.op === '!')
+            return this.condition(expr.value);
+        if (expr.kind === 'binary') {
+            if (expr.op === '||' || expr.op === '&&') {
+                if (expr.op === '&&' && expr.left.kind === 'binary' && expr.right.kind === 'binary' && expr.left.op === '!=' && expr.right.op === '!=' &&
+                    this.memberPath(expr.left.left) === this.memberPath(expr.right.left) && this.memberPath(expr.left.left))
+                    return this.expression(expr.left.left) + ' is either ' + this.expression(expr.left.right) + ' or ' + this.expression(expr.right.right);
+                const child = (value) => this.requirement(value, value.kind === 'binary' && ['&&', '||'].includes(value.op) && value.op !== expr.op);
+                const text = child(expr.left) + (expr.op === '||' ? ' and ' : ' or ') + child(expr.right);
+                return nested ? '(' + text + ')' : text;
+            }
+            const inverse = { '==': 'does not equal', '!=': 'equals', '<': 'is at least', '>': 'is at most', '<=': 'is greater than', '>=': 'is less than' };
+            if (inverse[expr.op])
+                return this.expression(expr.left, true) + ' ' + inverse[expr.op] + ' ' + this.expression(expr.right, true);
+        }
+        return expr.kind === 'call' ? this.predicate(expr, false) : this.expression(expr) + ' is false';
     }
     binding(binding) {
         const info = this.checked.bindings.find(info => info.declaration === binding);
@@ -429,241 +784,200 @@ class SpecWriter {
         this.use(def);
         const lifetime = binding.lifetime ?? info?.lifetime;
         const key = binding.key + (binding.keyTypeArgs.length ? '<' + binding.keyTypeArgs.map(type => typeName(type)).join(', ') + '>' : '');
-        return (`Provide ${def ? this.link(def, def.name, typeName(binding.target)) : this.type(binding.target)} when ${code(key)} is requested. ` +
-            (lifetime === 'shared' ? 'Reuse one instance. ' : lifetime === 'scoped' ? 'Reuse one instance per explicit scope. ' : lifetime === 'fresh' ? 'Construct a fresh instance for each resolve. ' : 'Use a fresh instance when this provider retains state; otherwise reuse one instance. ') +
-            (binding.sharedMutation ? 'Permit explicit shared mutation. ' : '') +
-            (info?.dependencies.length ? 'Required dependencies: ' + info.dependencies.map(code).join(', ') + '. ' : '')).trimEnd() + '\n';
+        return (`${code(key)} is provided by ${def ? this.link(def, def.name, typeName(binding.target)) : this.type(binding.target)}. ` +
+            (lifetime === 'shared' ? 'The same instance is shared. ' : lifetime === 'scoped' ? 'Each scope shares one instance. ' : lifetime === 'fresh' ? 'Each resolve creates a new instance. ' : 'Stateless instances are reused; stateful instances are created for each resolve. ') +
+            (binding.sharedMutation ? 'Shared mutation is allowed. ' : '') +
+            (info?.dependencies.length ? 'It requires bindings for ' + coordinate(info.dependencies.map(code)) + '. ' : '')).trimEnd();
     }
     callable(method, owner) {
         this.locals = new Map(owner && 'fields' in owner.node ? fieldsOf(owner.node).map(field => [field.name, field.type]) : []);
         const name = owner && owner.node.kind !== 'function' ? `${owner.name}.${method.name}` : method.name;
-        return this.heading(name, method.span, owner && owner.node.kind !== 'function' ? 3 : 2) +
-            (method.name.startsWith('_') ? 'Private to its defining scope.\n\n' : '') + this.contract(method) + this.layers(method) +
-            (method.body ? '**What it does**\n\n' + this.statements(method.body) + '\n' : method.externC ? 'Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.\n\n' : 'Interface contract. A selected implementation supplies the behavior.\n\n') +
-            this.notes(method.annotations?.[0]?.span ?? method.span, method, owner);
+        const documentation = callableDocumentation(this.checked.project, method, owner);
+        const children = [];
+        if (method.endpoint)
+            children.push(paragraph(code(method.name) + ' handles ' + code(method.endpoint.method + ' ' + method.endpoint.path) + '.'));
+        if (method.name.startsWith('_'))
+            children.push(paragraph('It is private to its defining scope.'));
+        const notes = this.notes(documentation);
+        if (notes)
+            children.push(paragraph(notes));
+        children.push(...this.contract(method, documentation), ...this.layers(method));
+        if (method.body)
+            children.push(flow(this.statements(method.body)));
+        else if (method.externC)
+            children.push(paragraph('Native C implementation; only its declared contract is visible here.'));
+        return this.heading(name, method.span, owner && owner.node.kind !== 'function' ? 3 : 2, children);
+    }
+    exportLine(item) {
+        const folder = this.file.builtin ? libraryChild(this.checked.project.libraries, dirname(this.file.path), item.name) : join(dirname(this.file.path), item.name);
+        const file = item.folder ? join(folder, 'export.aug') : join(dirname(this.file.path), item.from + '.aug');
+        this.enqueue(file);
+        return `Export ${item.folder ? 'the folder ' : 'the declaration '}${code(item.name)} from [${code(basename(file))}](${url(relative(dirname(this.docs.get(this.file.path)), this.docs.get(file)))}${item.folder ? '' : '#' + encodeURIComponent(anchor(item.name))}).`;
+    }
+    providerLine(item) {
+        if (item.kind === 'bind')
+            return this.binding(item);
+        const def = this.definition(item.name);
+        return 'Include providers from ' + (def ? this.link(def) : code(item.name)) + '.';
     }
     declaration(item) {
         switch (item.kind) {
-            case 'import': return '';
-            case 'export': {
-                const folder = this.file.builtin ? libraryChild(this.checked.project.libraries, dirname(this.file.path), item.name) : join(dirname(this.file.path), item.name);
-                const file = item.folder ? join(folder, 'export.aug') : join(dirname(this.file.path), item.from + '.aug');
-                this.enqueue(file);
-                return `- Export ${item.folder ? 'the folder ' : 'the declaration '}${code(item.name)} from [${code(basename(file))}](${url(relative(dirname(this.docs.get(this.file.path)), this.docs.get(file)))}${item.folder ? '' : '#' + encodeURIComponent(anchor(item.name))}).\n`;
-            }
             case 'function': return this.callable(item);
             case 'class': {
                 const def = this.definition(item.name);
                 this.locals = new Map();
-                let text = this.heading(item.name, item.span) + `${item.record ? 'Immutable record' : 'Behavioral class'}${item.name.startsWith('_') ? ', private to this file' : ''}.\n\n` + this.generics(item) +
-                    (item.implements.length ? 'Satisfies ' + item.implements.map(type => { const def = this.definition(type.name); return def ? this.link(def) : this.type(type); }).join(', ') + '.\n\n' : '') +
-                    this.notes(item.annotations?.[0]?.span ?? item.span) + this.inputs(item.fields, true) + this.layers(item);
-                if (item.validationErrors?.length)
-                    text += 'Construction can fail with ' + item.validationErrors.map(type => this.type(type)).join(', ') + '.\n\n';
+                const documentation = javadocBefore(this.file.source, item.annotations?.[0]?.span.start ?? item.span.start);
+                const children = [];
+                const generics = this.generics(item), notes = this.notes(documentation);
+                const inputs = this.inputs(item.fields, true, this.file.path, documentation?.parameters);
+                const implementsText = item.implements.length ? 'It implements ' + coordinate(item.implements.map(type => this.type(type))) + '.' : '';
+                const introduction = [notes, implementsText, item.name.startsWith('_') ? 'It is private to this file.' : '', generics].filter(Boolean).join(' ');
+                if (introduction)
+                    children.push(paragraph(introduction));
+                if (inputs)
+                    children.push(paragraph(inputs));
+                children.push(...this.layers(item));
+                const errors = this.checked.constructorContracts.get(item)?.errors;
+                if (errors?.length)
+                    children.push(paragraph('Construction can fail with ' + errors.map(type => { this.use(type.def); return type.def ? this.link(type.def) : code(tyName(type)); }).join(', ') + '.'));
+                else if (item.validationErrors?.length)
+                    children.push(paragraph('Construction can fail with ' + item.validationErrors.map(type => this.type(type)).join(', ') + '.'));
                 if (item.stateFields?.length)
-                    text += '**Field initialization**\n\n' + item.stateFields.map(field => { this.locals.set(field.name, field.type); return `- Initialize ${code(field.name)} of type ${this.type(field.type)} to ${this.expression(field.initializer)}. ${field.mutable ? 'Mutable' : 'Read-only'} storage${field.name.startsWith('_') ? ', private to this class' : ''}.\n`; }).join('') + '\n';
+                    children.push(...item.stateFields.map(field => { this.locals.set(field.name, field.type); return paragraph(`The ${field.mutable ? 'mutable' : 'read-only'}${field.name.startsWith('_') ? ', private' : ''} field ${code(field.name)} has type ${this.type(field.type)} and starts as ${this.expression(field.initializer)}.`); }));
                 if (item.constructorBody)
-                    text += this.heading(item.name + '.initialize', item.span, 3) + 'When execution reaches the original constructor, store inputs and initialize local fields, then run this block once before returning the object:\n\n' + this.statements(item.constructorBody) + '\n';
+                    children.push(this.heading(item.name + '.initialize', item.span, 3, [flow(this.statements(item.constructorBody))]));
                 if (!item.record) {
                     const defaults = this.checked.defaults.get(def.id);
                     const inherited = [...(defaults?.values() ?? [])].filter(info => !item.methods.some(method => method.name === info.method.name));
                     if (inherited.length)
-                        text += '**Inherited default behavior**\n\n' + inherited.map(info => { const parent = this.checked.project.definitions.get(info.from); this.use(parent, info.method); return '- ' + (parent ? this.link(parent, `${parent.name}.${info.method.name}`) : code(info.method.name)) + '.\n'; }).join('') + '\n';
+                        children.push(paragraph('It inherits the default implementations of ' + coordinate(inherited.map(info => { const parent = this.checked.project.definitions.get(info.from); this.use(parent, info.method); return parent ? this.link(parent, `${parent.name}.${info.method.name}`) : code(info.method.name); })) + '.'));
                 }
-                return text + item.methods.map(method => this.callable(method, def)).join('');
+                children.push(...item.methods.map(method => this.callable(method, def)));
+                return this.heading(item.name, item.span, 2, children, item.record ? 'immutable record' : 'class');
             }
             case 'interface':
             case 'interceptor': {
                 const def = this.definition(item.name);
                 this.locals = new Map();
-                let text = this.heading(item.name, item.span) + (item.kind === 'interceptor' ? 'Function or constructor middleware' : item.capability ? 'Capability interface' : 'Interface') +
-                    (item.name.startsWith('_') ? ', private to this file' : '') + '.\n\n' + this.generics(item) + this.notes(item.span);
+                const generics = this.generics(item), notes = this.notes(javadocBefore(this.file.source, item.span.start));
+                const role = item.kind === 'interceptor' ? 'interceptor' : item.capability ? 'capability interface' : 'interface';
+                const introduction = [notes, item.name.startsWith('_') ? 'It is private to this file.' : '', generics].filter(Boolean).join(' ');
+                const children = introduction ? [paragraph(introduction)] : [];
                 if (item.kind === 'interface' && item.extends.length)
-                    text += 'Inherit contracts and default methods from ' + item.extends.map(type => { const def = this.definition(type.name); return def ? this.link(def) : this.type(type); }).join(', ') + '.\n\n';
-                if (item.kind === 'interceptor')
-                    text += this.inputs(item.fields, true) + 'Create a fresh interceptor for each invocation. Its around operation can delegate once, change selected inputs, or short-circuit with a compatible result or failure.\n\n';
-                return text + item.methods.map(method => this.callable(method, def)).join('');
+                    children.push(paragraph('It inherits ' + coordinate(item.extends.map(type => this.type(type))) + '.'));
+                if (item.kind === 'interceptor') {
+                    const inputs = this.inputs(item.fields, true);
+                    if (inputs)
+                        children.push(paragraph(inputs));
+                    children.push(paragraph('Creates one interceptor per invocation. Its around operation may delegate once or finish early.'));
+                }
+                children.push(...item.methods.map(method => this.callable(method, def)));
+                return this.heading(item.name, item.span, 2, children, role);
             }
-            case 'composition': return this.heading(item.name, item.span) + this.notes(item.span) + 'This composition declares these providers before startup:\n\n' + item.bindings.map(binding => '- ' + this.binding(binding)).join('') + '\n';
-            case 'bind': return '- ' + this.binding(item);
-            case 'include': {
-                const def = this.definition(item.name);
-                return '- Include the providers from ' + (def ? this.link(def) : code(item.name)) + ' before execution.\n';
+            case 'composition': {
+                const notes = this.notes(javadocBefore(this.file.source, item.span.start));
+                return this.heading(item.name, item.span, 2, [...(notes ? [paragraph(notes)] : []), paragraph('These providers are registered before startup. ' + item.bindings.map(binding => this.binding(binding)).join(' '))]);
             }
             case 'test': return this.tests(item);
-            default: return this.statement(item, 0);
+            case 'bind':
+            case 'include': return paragraph(this.providerLine(item));
+            case 'export': return paragraph(this.exportLine(item));
+            case 'import': return paragraph('');
+            default: return flow(this.statement(item));
         }
     }
     tests(suite) {
         this.locals = new Map();
-        let text = this.heading(this.testTitle(suite), suite.span) + 'Same-file ' + (suite.endpointSuite ? 'HTTP endpoint' : suite.functionSuite ? 'function' : 'class') + ' tests for ' + this.type(suite.type) + '. Each case gets isolated setup and dependency bindings.\n\n';
+        const children = [paragraph('Tests ' + this.type(suite.type) + '. Each case gets fresh setup and dependencies.')];
         for (const group of suite.groups) {
             this.locals = new Map();
-            text += '### Group ' + code(group.name) + '\n\n';
+            const groupChildren = [];
             if (group.setup.length)
-                text += '**Setup before each case**\n\n' + group.setup.map(entry => this.declaration(entry)).join('') + '\n';
+                groupChildren.push(paragraph('Setup for each case:'), flow(group.setup.flatMap(entry => entry.kind === 'bind' || entry.kind === 'include' ? [step(this.providerLine(entry))] : this.statement(entry))));
             const setupLocals = new Map(this.locals);
             for (const test of group.cases) {
                 this.locals = new Map(setupLocals);
-                text += '#### ' + code(test.name) + '\n\n' + this.source(test.span) + '\n\n';
+                const caseChildren = [];
                 if (test.parameters)
-                    text += 'Run once for each row of ' + test.rows.map(row => this.expression(row)).join('; ') + '. Bind row positions to ' + test.parameters.map(code).join(', ') + '.\n\n';
-                text += this.statements(test.body) + '\n';
+                    caseChildren.push(paragraph('Run once for each row of ' + test.rows.map(row => this.expression(row)).join('; ') + '. Bind row positions to ' + test.parameters.map(code).join(', ') + '.'));
+                caseChildren.push(flow(this.statements(test.body)));
+                groupChildren.push(section(code(test.name), 4, caseChildren, undefined, this.source(test.span)));
             }
+            children.push(section(code(group.name), 3, groupChildren));
         }
-        return text;
+        return this.heading(this.testTitle(suite), suite.span, 2, children);
     }
     testTitle(suite) {
         return 'test ' + suite.type.name + (suite.name === suite.type.name ? '' : ' ' + suite.name);
     }
     dependencySurface() {
         if (!this.used.size)
-            return '';
+            return;
         const entries = [...this.used.values()].sort((a, b) => compare(relative(this.checked.project.root, this.docs.get(a.def.file)) + ':' + a.def.name, relative(this.checked.project.root, this.docs.get(b.def.file)) + ':' + b.def.name));
-        let text = '## Dependencies used by this file\n\nOnly referenced types and operations appear here. Each name links to its complete specification.\n\n';
+        const groups = new Map();
         for (const entry of entries) {
             const def = entry.def, node = def.node;
-            const kind = node.kind === 'class' && node.record ? 'record' : node.kind === 'interface' && node.capability ? 'capability interface' : node.kind;
-            text += '### ' + this.link(def) + '\n\n' + kind[0].toUpperCase() + kind.slice(1);
             const imported = this.file.items.find(item => item.kind === 'import' && (this.checked.project.imports.get(item) ?? []).some(imported => imported.id === def.id));
-            if (imported?.kind === 'import')
-                text += ' from ' + code(imported.from.join('.')) + (imported.everything ? ' through import everything' : '');
-            text += '.\n\n';
-            if (node.kind === 'function')
-                text += this.dependencyOperation(node, def);
-            if (node.kind === 'class' && entry.constructed)
-                text += '- Construct with ' + this.shortInputs(node.fields, def.file) + ' → ' + this.link(def) +
-                    (node.validationErrors?.length ? '; can fail with ' + node.validationErrors.map(type => this.type(type, def.file)).join(', ') : '') + '.\n';
-            if (node.kind === 'class' && entry.fields.size)
-                for (const name of [...entry.fields].sort(compare)) {
-                    const field = fieldsOf(node).find(field => field.name === name);
-                    if (field)
-                        text += '- Read ' + code(name) + ' (' + this.type(field.type, def.file) + ')' + (field.mutable ? '; its owner can change it' : '') + '.\n';
-                }
-            if ('methods' in node)
-                for (const method of [...entry.operations].sort((a, b) => compare(a.name, b.name)))
-                    text += this.dependencyOperation(method, def);
-            if (node.kind !== 'function' && !entry.constructed && !entry.fields.size && !entry.operations.size)
-                text += 'Used as a type or provider.\n';
-            text += '\n';
+            const origin = imported?.kind === 'import' ? code(imported.from.join('.')) + (imported.everything ? ' through import everything' : '') : '';
+            const names = [this.link(def)];
+            const members = [...entry.operations].sort((a, b) => compare(a.name, b.name)).map(method => this.link(def, def.name + '.' + method.name, method.name));
+            members.push(...[...entry.fields].sort(compare).map(name => code(name)));
+            if (members.length)
+                names[0] += ' (' + coordinate(members) + ')';
+            const group = groups.get(origin) ?? [];
+            group.push(...names);
+            groups.set(origin, group);
         }
-        return text;
-    }
-    shortInputs(params, file) {
-        return params.filter(param => !param.injected).map(param => code(param.label ?? param.name) + ': ' + this.type(param.type, file) +
-            (param.source ? ' from HTTP ' + param.source.kind + (param.source.name ? ' ' + code(param.source.name) : '') : '')).join(', ') || 'no caller inputs';
-    }
-    dependencyOperation(method, owner) {
-        const effects = this.checked.effectContracts.get(method), layers = this.checked.interceptorPlans.get(method) ?? [];
-        const changes = effects?.changes ?? method.changes ?? [];
-        const uses = [...(effects?.uses.values() ?? method.uses ?? [])];
-        const errors = [...new Set([...method.throws.map(type => typeName(type)), ...layers.flatMap(layer => layer.errors.map(tyName))])];
-        const name = owner.node.kind === 'function' ? owner.name : owner.name + '.' + method.name;
-        let text = '- ' + this.link(owner, name) + (method.typeParams.length ? '<' + method.typeParams.map(code).join(', ') + '>' : '') +
-            ' (' + this.shortInputs(method.params, method.span.file) + ') → ' + this.type(method.returns, method.span.file);
-        const injected = method.params.filter(param => param.injected);
-        if (injected.length)
-            text += '; inject ' + injected.map(param => code(param.name) + ': ' + this.type(param.type, method.span.file)).join(', ');
-        if (changes.length)
-            text += '; changes ' + changes.map(code).join(', ');
-        const otherUses = uses.filter(effect => effect.source !== owner.name || effect.operation !== method.name);
-        if (otherUses.length)
-            text += '; uses ' + otherUses.map(effect => {
-                const target = ('capability' in effect ? effect.capability?.def : undefined) ?? this.checked.project.scopes.get(method.span.file)?.get(effect.source);
-                const operation = target && 'methods' in target.node ? target.node.methods.find(method => method.name === effect.operation) : undefined;
-                this.use(target, operation);
-                return target ? this.link(target, operation ? `${target.name}.${operation.name}` : target.name, `${effect.source}.${effect.operation}`) : code(`${effect.source}.${effect.operation}`);
-            }).join(', ');
-        if (errors.length)
-            text += '; can fail with ' + errors.map(code).join(', ');
-        return text + '.\n';
-    }
-    fileOverview() {
-        const lines = [];
-        const declaration = (name) => `[${code(name)}](${url(basename(this.docs.get(this.file.path)))}#${encodeURIComponent(anchor(name))})`;
-        for (const item of this.file.items) {
-            switch (item.kind) {
-                case 'class':
-                    lines.push(`- ${declaration(item.name)} is ${item.record ? 'an immutable record' : 'a class'}${item.implements.length ? ' implementing ' + item.implements.map(type => code(typeName(type))).join(', ') : ''}.`);
-                    break;
-                case 'interface':
-                    lines.push(`- ${declaration(item.name)} is ${item.capability ? 'a capability interface' : 'an interface'}.`);
-                    break;
-                case 'interceptor':
-                    lines.push(`- ${declaration(item.name)} is an interceptor.`);
-                    break;
-                case 'function':
-                    lines.push(`- ${declaration(item.name)} ${item.endpoint ? `handles ${code(item.endpoint.method)} ${code(item.endpoint.path)}` : 'is a function'}${item.returns.name === 'void' ? '' : ` returning ${code(typeName(item.returns))}`}.`);
-                    break;
-                case 'composition':
-                    lines.push(`- ${declaration(item.name)} declares ${item.bindings.length} ${item.bindings.length === 1 ? 'provider' : 'providers'}.`);
-                    break;
-                case 'bind': break;
-                case 'include':
-                    lines.push(`- Include providers from ${code(item.name)}.`);
-                    break;
-                case 'export':
-                    lines.push(`- Export ${code(item.name)} from this folder.`);
-                    break;
-                case 'test':
-                    lines.push(`- ${declaration(this.testTitle(item))} is a same-file test suite.`);
-                    break;
-                default: break;
-            }
-        }
-        const providers = this.file.items.filter(item => item.kind === 'bind');
-        if (providers.length)
-            lines.push(`- Register ${providers.length} ${providers.length === 1 ? 'dependency provider' : 'dependency providers'} before startup.`);
-        const executable = this.file.items.filter(item => !['import', 'export', 'test', 'bind', 'include', 'class', 'interface', 'interceptor', 'function', 'composition'].includes(item.kind));
-        if (executable.some(item => item.kind === 'try'))
-            lines.push('- Run startup operations with checked error recovery.');
-        for (const item of executable)
-            if (item.kind === 'serve')
-                lines.push(`- Serve ${item.names.length} HTTP ${item.names.length === 1 ? 'route' : 'routes'}.`);
-        const otherSteps = executable.filter(item => item.kind !== 'try' && item.kind !== 'serve').length;
-        if (otherSteps)
-            lines.push(`- Run ${otherSteps} other startup ${otherSteps === 1 ? 'step' : 'steps'} in source order.`);
-        return lines.length ? '## In this file\n\n' + lines.join('\n') + '\n\n' : '';
+        return section('Dependencies', 2, [...[...groups].map(([origin, names]) => paragraph('It uses ' + coordinate(names) + (origin ? ' from ' + origin : '') + '.'))]);
     }
     render() {
         const exports = this.file.items.filter(item => item.kind === 'export');
         const declarations = this.file.items.filter(item => ['class', 'interface', 'interceptor', 'function', 'composition'].includes(item.kind));
         const providers = this.file.items.filter(item => item.kind === 'bind' || item.kind === 'include');
         const startup = this.file.items.filter(item => item.kind !== 'import' && item.kind !== 'export' && item.kind !== 'test' && item.kind !== 'bind' && item.kind !== 'include' && !declarations.includes(item));
-        // Render behavior first to discover the exact dependency surface, including wildcard imports.
-        const behavior = (exports.length ? '## Folder exports\n\n' + exports.map(item => this.declaration(item)).join('') + '\n' : '') +
-            (providers.length ? '## Dependency providers\n\nRegister these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.\n\n' + providers.map(item => this.declaration(item)).join('') + '\n' : '') +
-            (startup.length ? '## Startup, in source order\n\n' + startup.map(item => this.declaration(item)).join('') + '\n' : '') +
-            declarations.sort((a, b) => Number('name' in a && a.name.startsWith('_')) - Number('name' in b && b.name.startsWith('_'))).map(item => this.declaration(item)).join('') +
-            this.file.items.filter(item => item.kind === 'test').map(item => this.declaration(item)).join('');
-        const surface = this.dependencySurface() + this.builtinSurface();
-        let config = '';
+        const children = [];
+        if (declarations.some(item => item.kind === 'function' && item.endpoint))
+            children.push(paragraph('Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.'));
         if (basename(this.file.path) === 'main.aug') {
             const project = this.checked.project;
             if (project.files.get(this.file.path)?.items.some(item => item.kind === 'serve'))
-                config += '## HTTP configuration\n\n' +
-                    `Listen on ${code(project.config.web.host)}. Limit request bodies to ${project.config.web.body_limit} bytes and buffered responses to ${project.config.web.response_limit} bytes.\n\n` +
-                    (project.config.web.tls.certificate ? 'Use TLS with the configured certificate and private key.\n\n' : '') +
-                    (project.config.web.http3 ? 'Enable HTTP/3 over TLS.\n\n' : '') +
-                    (project.config.openapi.enabled ? `Serve the OpenAPI document at ${code(project.config.openapi.path)} and API documentation at ${code(project.config.openapi.docs)}.\n\n` : '');
-        }
-        return generated + '\n\n# ' + code(basename(this.file.path)) + ' specification\n\n' +
-            `August ${compilerVersion()}. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.\n\n` +
-            this.fileOverview() + config + behavior + surface +
-            (behavior ? '' : 'This file declares no operations.\n') +
-            '## Shared language rules\n\nSee the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.\n';
+                children.push(section('HTTP configuration', 2, [paragraph(`Listen on ${code(project.config.web.host)}. Limit request bodies to ${project.config.web.body_limit} bytes and buffered responses to ${project.config.web.response_limit} bytes. ` +
+                        (project.config.web.tls.certificate ? 'Use TLS. ' : '') +
+                        (project.config.web.http3 ? 'Enable HTTP/3. ' : '') +
+                        (project.config.openapi.enabled ? `Serve OpenAPI at ${code(project.config.openapi.path)} and API docs at ${code(project.config.openapi.docs)}. ` : ''))]));
+        }
+        // Build the checked explanation first; rendering decides all spacing.
+        if (exports.length)
+            children.push(section('Exports', 2, exports.map(item => paragraph(this.exportLine(item)))));
+        if (providers.length)
+            children.push(section('Providers', 2, providers.map(item => paragraph(this.providerLine(item)))));
+        if (startup.length)
+            children.push(section('Startup', 2, [flow(startup.flatMap(item => this.statement(item)))]));
+        children.push(...declarations.sort((a, b) => Number('name' in a && a.name.startsWith('_')) - Number('name' in b && b.name.startsWith('_'))).map(item => this.declaration(item)));
+        children.push(...this.file.items.filter(item => item.kind === 'test').map(item => this.declaration(item)));
+        if (!children.length)
+            children.push(paragraph('This file declares no operations.'));
+        // Links may add inherited operation owners. Walk until the surface is closed.
+        const surfaceSize = () => [...this.used.values()].reduce((size, entry) => size + 1 + entry.operations.size + entry.fields.size + Number(entry.constructed ?? false), 0);
+        let surface, size = -1;
+        do {
+            size = surfaceSize();
+            surface = this.dependencySurface();
+        } while (surfaceSize() !== size);
+        if (surface)
+            children.push(surface);
+        const builtins = this.builtinSurface();
+        if (builtins)
+            children.push(builtins);
+        return generated + '\n\n' + renderSpecTree(section(code(basename(this.file.path)), 1, children));
     }
     builtinSurface() {
         if (!this.builtins.size && !this.properties.size)
-            return '';
-        return '## Built-in operations used by this file\n\n' + [...this.properties].sort(([a], [b]) => compare(a, b)).map(([name, property]) => `- ${code(name)} (${code(property.type)}): ${property.documentation}\n`).join('') +
-            [...this.builtins].sort(([a], [b]) => compare(a, b)).map(([name, operation]) => `- ${code(name)} (${operation.parameters.map(param => code(param.label) + ': ' + code(param.type)).join(', ') || 'no inputs'}) → ${code(operation.returns)}: ${operation.documentation}` +
-                (operation.changes ? ' Changes the receiver.' : '') +
-                (operation.errors?.length ? ' Can fail with ' + operation.errors.map(code).join(', ') + '.' : '') + '\n').join('') +
-            '\n[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).\n\n';
+            return;
+        return paragraph('Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).');
     }
 }
-/** Check generated artifacts without writing; protect neighboring handwritten documents. */
+/** Refresh pointers and artifacts atomically, or check drift without writing; protect handwritten documents. */
 export function updateSpecs(checked, check = false, options = {}) {
     const outputs = generateSpecs(checked, options), root = checked.project.root;
     const manifest = join(root, '.aug-spec', 'manifest.json');
@@ -674,11 +988,12 @@ export function updateSpecs(checked, check = false, options = {}) {
             throw new Error('Invalid generated specification manifest');
         previous = saved.files.map(path => resolve(root, path));
     }
-    const names = new Set(outputs.map(output => output.path));
+    const artifacts = outputs.filter(output => output.kind !== 'source-hint');
+    const names = new Set(artifacts.map(output => output.path));
     const removed = previous.filter(path => !names.has(path) && existsSync(path));
     const stale = outputs.filter(output => !existsSync(output.path) || readFileSync(output.path, 'utf8') !== output.text).map(output => relative(root, output.path));
     stale.push(...removed.map(path => relative(root, path)));
-    const manifestText = JSON.stringify({ format: 1, files: outputs.map(output => relative(root, output.path).replaceAll('\\', '/')), digest: hash(outputs.map(output => output.text).join('\0')) }, null, 2) + '\n';
+    const manifestText = JSON.stringify({ format: 1, files: artifacts.map(output => relative(root, output.path).replaceAll('\\', '/')), digest: hash(artifacts.map(output => output.text).join('\0')) }, null, 2) + '\n';
     if (options.manifest !== false && (!existsSync(manifest) || readFileSync(manifest, 'utf8') !== manifestText))
         stale.push('.aug-spec/manifest.json');
     if (check)
@@ -697,7 +1012,11 @@ export function updateSpecs(checked, check = false, options = {}) {
             if (lstatSync(output.path).isSymbolicLink())
                 throw new Error(`Specification output is a symbolic link: ${output.path}`);
             const text = readFileSync(output.path, 'utf8');
-            if (!text.startsWith(generated) && !text.startsWith(copied))
+            if (output.kind === 'source-hint') {
+                if (text !== checked.project.files.get(output.source)?.source)
+                    throw new Error('Source changed during compilation; retry before generating specifications');
+            }
+            else if (!text.startsWith(generated) && !text.startsWith(copied))
                 throw new Error(`Refusing to overwrite handwritten file ${output.path}`);
         }
     }
@@ -706,12 +1025,14 @@ export function updateSpecs(checked, check = false, options = {}) {
             continue;
         mkdirSync(dirname(output.path), { recursive: true });
         const temporary = output.path + '.aug-spec-tmp';
+        let created = false;
         try {
-            writeFileSync(temporary, output.text, { flag: 'wx' });
+            writeFileSync(temporary, output.text, { flag: 'wx', mode: output.kind === 'source-hint' ? lstatSync(output.path).mode : undefined });
+            created = true;
             renameSync(temporary, output.path);
         }
         finally {
-            if (existsSync(temporary))
+            if (created && existsSync(temporary))
                 rmSync(temporary);
         }
     }
@@ -724,12 +1045,14 @@ export function updateSpecs(checked, check = false, options = {}) {
         mkdirSync(dirname(manifest), { recursive: true });
         if (!existsSync(manifest) || readFileSync(manifest, 'utf8') !== manifestText) {
             const temporary = manifest + '.aug-spec-tmp';
+            let created = false;
             try {
                 writeFileSync(temporary, manifestText, { flag: 'wx' });
+                created = true;
                 renameSync(temporary, manifest);
             }
             finally {
-                if (existsSync(temporary))
+                if (created && existsSync(temporary))
                     rmSync(temporary);
             }
         }