docs: make technical prose concrete

packages/boot/app-boot/src/index.ts

@@ -306,7 +306,7 @@ export function loadOverlayPatches(binName: string, file: string): PatchOptions[
 /**
  * Parse one loader patch list: a top-level YAML array of
  * `@cordisjs/plugin-include` `PatchOptions` (id-targeted config overrides and
- * `insert` lists, `!!js` expressions allowed). Every shape failure throws,
+ * `insert` lists, `!!js` expressions allowed). Every invalid field or value throws,
  * because a patch file that cannot be applied at all is a misconfiguration; a
  * single patch whose target row is absent stays a per-entry Loader warning, so
  * one overlay shared across surfaces does not have to match every tree.
@@ -397,12 +397,12 @@ export function renderConfigDump(
     throw new Error(`${binName}: config ${absoluteConfigPath} must be a top-level YAML array of entries`)
   }
   const baseLabel = basename(absoluteConfigPath)
-  // The YAML boundary yields untyped rows; the include validates entry shape
+  // YAML parsing yields untyped rows; the include validates each entry
   // at mount, and the dump prints whatever the file holds, so `EntryOptions`
   // here is structural trust in the same file `boot()` would include.
   const base = parsed as Parameters<typeof applyEntryPatches>[0]
-  // snapshot_k = ONE application of layers 1..k flattened — boot's exact call
-  // shape for that prefix. snapshot_N is therefore the mounted composition.
+  // snapshot_k = ONE application of layers 1..k flattened, using the exact
+  // arguments boot passes for that prefix. snapshot_N is the mounted composition.
   // The patches are cloned per call: applyEntryPatches detaches the entry
   // list but pushes `insert` rows by reference from the patch list, so
   // sharing patch objects across snapshot calls would leak a later

packages/boot/app-boot/src/profile.ts

@@ -267,7 +267,7 @@ export function readProfileManifest(binName: string, dir: string): ProfileManife
   } catch (error) {
     throw new Error(`${binName}: failed to read profile manifest ${path}: ${String(error)}`)
   }
-  // File boundary: the shape check below validates what the parse type asserts.
+  // The field checks below validate the file data before trusting the parse type.
   const parsed = JSON.parse(raw) as ProfileManifest | null
   if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
     throw new Error(`${binName}: profile manifest ${path} must hold a JSON object`)