docs: make technical prose concrete

packages/llm/llm-pi-ai/src/catalog.ts

@@ -145,12 +145,12 @@ export type PiAiReasoningEfforts = Partial<Record<ModelThinkingLevel, string | n
  * default) or per model (winning over the route). Only the switches pi-ai's
  * reasoning dispatch reads are offered; the rest of pi-ai's compat surface
  * keeps its baseURL-derived auto-detection. pi-ai types both fields only on
- * `OpenAICompletionsCompat` — the other wire protocols carry their reasoning
- * shape in the protocol itself — so resolution rejects a model-level switch
+ * `OpenAICompletionsCompat` — the other wire protocols define their reasoning
+ * fields in the protocol itself — so resolution rejects a model-level switch
  * anywhere else, while a route-level default skips past models it cannot fit.
  */
 export interface PiAiCompatProfile {
-  /** Reasoning parameter shape the endpoint expects; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
+  /** Reasoning parameter format the endpoint expects; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
   thinkingFormat?: PiAiThinkingFormat
   /** Whether the endpoint accepts `reasoning_effort`; absent keeps the catalog entry's, then pi-ai's baseURL-derived guess. */
   supportsReasoningEffort?: boolean

packages/llm/llm-pi-ai/src/config.ts

@@ -163,12 +163,12 @@ const compatProfile: z<PiAiCompatProfile> = z.object({
 /**
  * Keys are the offered levels, values their wire spellings. A valueless key
  * (`off:`) survives validation because schemastery passes nullable data
- * through before any member schema runs — `z.const(null)` only shapes the
- * error for non-null wrong values and what a configuration surface renders.
+ * through before any member schema runs — `z.const(null)` only controls the
+ * error for non-null wrong values and what a configuration UI renders.
  * Only resolution decides which levels may leave the value empty, so the
  * diagnostic can name the route and model. The assertion narrows
  * schemastery's `Dict`, which types every literal key as required; dict
- * validation is per-present-key, so the runtime shape is the partial record.
+ * validation checks only present keys, so the runtime value is a partial record.
  */
 const reasoningEfforts = z.dict(
   z.union([z.string(), z.const(null)]),
@@ -237,7 +237,7 @@ export function assertServiceable(config: Config): void {
   resolveProfiles(config.providers)
 }
 
-/** Reject a pre-release profile shape, naming the replacement. */
+/** Reject removed pre-release profile fields and name their replacements. */
 function rejectRemovedFields(provider: string, source: PiAiProviderProfile): void {
   const legacy = source as PiAiProviderProfile & {
     provider?: unknown