docs: make technical prose concrete

packages/scaffold/client/src/api.ts

@@ -203,7 +203,7 @@ export function normalizeInput(input: string | ContentBlock[]): ContentBlock[] {
   return typeof input === 'string' ? [{ type: 'text', text: input }] : input
 }
 
-/** Validate a wire `session.event` envelope to the shape the typed result exposes. */
+/** Validate the fields in a wire `session.event` envelope before returning the typed result. */
 function validatedSessionEvent(value: unknown): SessionEvent {
   if (!isRecord(value) || typeof value.type !== 'string') {
     throw new SdkProtocolError(`session.event carried no event envelope: ${JSON.stringify(value)}`)

packages/scaffold/helper/src/documents/tsconfig-file.ts

@@ -70,7 +70,7 @@ export class TsConfigFile extends ProjectFile {
     ))
   }
 
-  /** Validate JSONC and the project-reference shape. */
+  /** Validate JSONC and the project-reference fields. */
   override validate(): void {
     const value = parseConfig(this.text)
     if (value.references === undefined) return

packages/scaffold/helper/src/features/define-feature.ts

@@ -114,7 +114,7 @@ function configDiagnostics(
   if (!expected || Object.keys(expected).length === 0) return undefined
   return config => Object.entries(expected).flatMap(([key, value]) => sameShape(value, config[key])
     ? []
-    : [`${key} has an incompatible value shape`])
+    : [`${key} has fields or value types that do not match the expected config`])
 }
 
 function resourcesFromSpec(spec: FeatureResourceSpec): ProjectResource[] {

packages/scaffold/helper/src/features/feature.ts

@@ -236,7 +236,7 @@ export abstract class Feature {
   }
 
   /**
-   * Inspect current files and reject any partial or ambiguous owned shape.
+   * Inspect current files and reject any partial or ambiguous owned file set.
    * @param project - project snapshot to inspect.
    * @returns installation state, selection, and diagnostics.
    */