@voxgig/sdkgen 1.3.1 → 1.3.2

package/project/.sdk/src/cmp/rb/ReadmeEntity_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -9,13 +9,14 @@ import {
 
 // A type-correct Ruby literal for a field's canonical type — the create body
 // is EXECUTED by the doc test, so it must carry a real value per field.
-function rbLit(type: any): string {
+// Strings render the quoted placeholder.
+function rbLit(type: any, placeholder: string = 'example'): string {
   const k = canonKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'
   if ('OBJECT' === k) return '{}'
-  return '"example"'
+  return `"${placeholder}"`
 }
 
 
@@ -107,11 +108,23 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{ ${loadItems.map((it: any) =>
+          `"${it.name}" => ${rbLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
+        : ''
       Content(`#### Example: Load
 
 \`\`\`ruby
 # load returns the bare ${entity.Name} record (raises on error).
-${entity.name} = client.${entity.Name}.load(${idF ? `{ "${idF}" => "${entity.name}_id" }` : ''})
+${entity.name} = client.${entity.Name}.load(${loadArg})
 \`\`\`
 
 `)
@@ -129,16 +142,21 @@ ${entity.name}s = client.${entity.Name}.list
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id — with a real, executable
+      // literal (the doc test RUNS this block, so a comment placeholder
+      // would break it).
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
 \`\`\`ruby
 ${entity.name} = client.${entity.Name}.create({
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  "${field.name}" => ${rbLit(field.type)}, # ${canonToType(field.type, target.name)}
+      createItems.map((it: any) => {
+        Content(`  "${it.name}" => ${rbLit(it.type, 'example_' + it.name)}, # ${canonToType(it.type, target.name)}
 `)
-        }
       })
       Content(`})
 \`\`\`

package/project/.sdk/src/cmp/rb/ReadmeQuick_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,8 +14,16 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  // Find a nested entity if available: one with a parent chain
+  // (relations.ancestors), an active load op, and a required non-id load
+  // param to demonstrate (the parent key, e.g. page_id).
   const nestedEntity = Object.values(entity).find((e: any) =>
-    e.active !== false && e.ancestors && e.ancestors.length > 0
+    e.active !== false &&
+    e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
+    entityOps(e).includes('load') &&
+    opRequestShape(e, 'load').items.some((it: any) =>
+      !it.optional && it.name !== entityIdField(e))
   ) as any
 
   const ctor = isAuthActive(model)
@@ -35,7 +43,7 @@ client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const article = /^[aeiou]/i.test(eName) ? "an" : "a"
-    const opnames = Object.keys(exampleEntity.op || {})
+    const opnames = entityOps(exampleEntity)
     // Model-driven id keys: `idF` is the load-MATCH key (null when the entity
     // has no id-like field — a response-wrapped spec); when null, load/remove
     // take no argument. `dataIdF` is the id on the RETURNED record's data type —
@@ -45,6 +53,19 @@ client = ${ctor}
     const idF = entityIdField(exampleEntity)
     const dataIdF = entityDataIdField(exampleEntity)
 
+    // A type-correct, executable Ruby literal for a param: numeric/boolean/
+    // array/hash params render a typed literal; strings render the quoted
+    // placeholder (the doc test EXECUTES these blocks, so a comment
+    // placeholder would not parse).
+    const rbLit = (type: any, placeholder: string = 'example'): string => {
+      const k = canonKey(type)
+      if ('INTEGER' === k || 'NUMBER' === k) return '1'
+      if ('BOOLEAN' === k) return 'true'
+      if ('ARRAY' === k) return '[]'
+      if ('OBJECT' === k) return '{}'
+      return `"${placeholder}"`
+    }
+
     // Model-driven display field: the entity's first non-id string field
     // (falling back to any non-id field), so the list example prints a real
     // column instead of a hardcoded "name" the entity may not have.
@@ -75,13 +96,62 @@ end
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (nestedEntity) {
+      const neName = nom(nestedEntity, 'Name')
+      const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
+      const neVar = neName.toLowerCase()
+
+      // Model-driven match: every REQUIRED load-match key — the same shape
+      // the runtime resolves path params from, so the example always works.
+      // Parent keys (e.g. page_id) first, the entity's own id last.
+      const neIdF = entityIdField(nestedEntity)
+      const neRequired = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+      const parentItem = neRequired.find((it: any) => it.name !== neIdF) as any
+      const parentParam = parentItem && parentItem.name
+      const parentName = parentParam ? parentParam.replace(/_id$/, '') : 'its parent'
+      const neMatch = neRequired.map((it: any) =>
+        `"${it.name}" => ${rbLit(it.type,
+          it.name === neIdF ? 'example_id' : 'example_' + it.name)}`)
+
+      Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
+
+${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
+
+\`\`\`ruby
+begin
+  # load returns the bare ${neName} record (raises on error).
+  ${neVar} = client.${neName}.load({ ${neMatch.join(', ')} })
+  puts ${neVar}
+rescue => err
+  warn "load failed: #{err}"
+end
+\`\`\`
+
+`)
+    }
+    else if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadRequired = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadRequired.length
+        ? `{ ${loadRequired.map((it: any) =>
+          `"${it.name}" => ${rbLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
+
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
 \`\`\`ruby
 begin
   # load returns the bare ${eName} record (raises on error).
-  ${eName.toLowerCase()} = client.${eName}.load(${idF ? `{ "${idF}" => "example_id" }` : ''})
+  ${eName.toLowerCase()} = client.${eName}.load(${loadArg})
   puts ${eName.toLowerCase()}
 rescue => err
   warn "load failed: #{err}"
@@ -94,25 +164,21 @@ end
     // Model-driven example fields: derive the create/update body from the op
     // shape (opRequestShape) so the docs reference REAL writable fields, not a
     // hardcoded "name" the entity may not have. Literals are Ruby-typed by the
-    // field's canonical type.
-    const idField = (exampleEntity.id && exampleEntity.id.field) || 'id'
-    const rbLit = (type: any): string => {
-      const k = canonKey(type)
-      if ('INTEGER' === k || 'NUMBER' === k) return '1'
-      if ('BOOLEAN' === k) return 'true'
-      if ('ARRAY' === k) return '[]'
-      if ('OBJECT' === k) return '{}'
-      return '"example"'
-    }
+    // field's canonical type. ids are rendered separately as the match key for
+    // update/remove; a REQUIRED create id stays (the call is invalid without
+    // it).
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
-        .filter((it: any) => it.name !== idField && it.name !== 'id')
+        .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
+          ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
-      // create needs ALL required fields; update is a patch, so a couple suffice.
+      const optional = items.filter((it: any) => it.optional)
+      // create needs ALL required fields; update is a patch, so the required
+      // members plus a sample optional field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
-        : items.slice(0, 2)
-      return chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type)}`)
+        : required.concat(optional).slice(0, Math.max(2, required.length))
+      return chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type, 'example_' + it.name)}`)
     }
 
     // The id VALUE for an update/remove match: off the returned `created`
@@ -125,7 +191,7 @@ end
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
       ? `created["${dataIdF}"]`
-      : rbLit(idParamType(opname))
+      : rbLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
@@ -147,8 +213,17 @@ client.${eName}.update({ ${updatePairs.join(', ')} })
 `)
       }
       if (opnames.includes('remove')) {
+        // Every REQUIRED remove-match key: the id (off the created record
+        // when possible) plus parent keys like page_id.
+        const removePairs = opRequestShape(exampleEntity, 'remove').items
+          .filter((it: any) => !it.optional || it.name === idF)
+          .sort((a: any, b: any) =>
+            (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+          .map((it: any) => it.name === idF
+            ? `"${it.name}" => ${idValueFor('remove')}`
+            : `"${it.name}" => ${rbLit(it.type, 'example_' + it.name)}`)
         Content(`# Remove
-client.${eName}.remove(${idF ? `{ "${idF}" => ${idValueFor('remove')} }` : ''})
+client.${eName}.remove(${removePairs.length ? `{ ${removePairs.join(', ')} }` : ''})
 `)
       }
       Content(`\`\`\`

package/project/.sdk/src/cmp/rb/ReadmeRef_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -9,13 +9,14 @@ import {
 
 // A type-correct Ruby literal for a field's canonical type — the create body
 // is EXECUTED by the doc test, so it must carry a real value per field.
-function rbLit(type: any): string {
+// Strings render the quoted placeholder.
+function rbLit(type: any, placeholder: string = 'example'): string {
   const k = canonKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]'
   if ('OBJECT' === k) return '{}'
-  return '"example"'
+  return `"${placeholder}"`
 }
 
 
@@ -257,8 +258,20 @@ ${info.desc}
 
           // Show example
           if ('load' === opname || 'remove' === opname) {
+            // The id key plus every REQUIRED match key (parent path params
+            // like page_id) — the same shape the runtime resolves path
+            // params from, so the example always works.
+            const matchItems = opRequestShape(ent, opname).items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const arg = 0 < matchItems.length
+              ? `{ ${matchItems.map((it: any) =>
+                `"${it.name}" => ${rbLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')} }`
+              : ''
             Content(`\`\`\`ruby
-result = client.${ent.Name}.${opname}(${idF ? `{ "${idF}" => "${ent.name}_id" }` : ''})
+result = client.${ent.Name}.${opname}(${arg})
 \`\`\`
 
 `)
@@ -271,14 +284,19 @@ results = client.${ent.Name}.list
 `)
           }
           else if ('create' === opname) {
+            // Members come from the SAME shape the runtime validates
+            // (opRequestShape): every required member must appear — including
+            // a required id and parent keys like page_id — with a real,
+            // executable literal (the doc test RUNS this block, so a comment
+            // placeholder would break it).
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`ruby
 result = client.${ent.Name}.create({
 `)
-            each(fields, (field: any) => {
-              if ('id' !== field.name && field.req) {
-                Content(`  "${field.name}" => ${rbLit(field.type)}, # ${canonToType(field.type, target.name)}
+            createItems.map((it: any) => {
+              Content(`  "${it.name}" => ${rbLit(it.type, 'example_' + it.name)}, # ${canonToType(it.type, target.name)}
 `)
-              }
             })
             Content(`})
 \`\`\`
@@ -286,10 +304,18 @@ result = client.${ent.Name}.create({
 `)
           }
           else if ('update' === opname) {
-            const updateIdLine = idF ? `  "${idF}" => "${ent.name}_id",\n` : ''
+            // The id key plus every REQUIRED data member — the same shape the
+            // runtime validates — then the patch-fields note.
+            const updateItems = opRequestShape(ent, 'update').items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateLines = updateItems.map((it: any) =>
+              `  "${it.name}" => ${rbLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ruby
 result = client.${ent.Name}.update({
-${updateIdLine}  # Fields to update
+${updateLines}  # Fields to update
 })
 \`\`\`
 

package/project/.sdk/src/cmp/rb/ReadmeTopQuick_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,20 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, executable Ruby literal for a param: numeric/boolean/
+// array/hash params render a typed literal; strings render the quoted
+// placeholder (the doc test EXECUTES this block, so a comment placeholder
+// would break it).
+function rbLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return `"${placeholder}"`
+}
+
+
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -45,9 +59,21 @@ puts ${eName.toLowerCase()}s
     }
 
     if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{ ${loadItems.map((it: any) =>
+          `"${it.name}" => ${rbLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
       Content(`
 # Load a specific ${eName.toLowerCase()} (returns the bare record; raises on error)
-${eName.toLowerCase()} = client.${eName}.load(${idF ? `{ "${idF}" => "example_id" }` : ''})
+${eName.toLowerCase()} = client.${eName}.load(${loadArg})
 puts ${eName.toLowerCase()}
 `)
       hasCall = true

package/project/.sdk/src/cmp/rb/ReadmeTopTest_rb.ts

@@ -39,7 +39,16 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
     const recBody = idF ? `{ "${idF}" => "test01" }` : '{}'
     let callArg = ''
     if (isMatchOp) {
-      callArg = idF ? `{ "${idF}" => "test01" }` : ''
+      // Every REQUIRED match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from.
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      callArg = 0 < items.length
+        ? `{ ${items.map((it: any) =>
+          `"${it.name}" => ${it.name === idF ? '"test01"' : rbLit(it.type)}`).join(', ')} }`
+        : ''
     } else if ('create' === primaryOp || 'update' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
@@ -47,12 +56,14 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
       const chosen = required.length ? required : items.slice(0, 3)
       callArg = `{ ${chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type)}`).join(', ')} }`
     }
+    // A list result is an Array — name the variable accordingly.
+    const eVar = ename + ('list' === primaryOp ? 's' : '')
     Content(`\`\`\`ruby
 # Seed fixture data so offline calls resolve without a live server.
 client = ${model.const.Name}SDK.test({
   "entity" => { "${ename}" => { "test01" => ${recBody} } },
 })
-${ename} = client.${eName}.${primaryOp}(${callArg})
+${eVar} = client.${eName}.${primaryOp}(${callArg})
 \`\`\`
 `)
   } else {

package/project/.sdk/src/cmp/ts/Config_ts.ts

@@ -11,6 +11,7 @@ import {
   each,
   indent,
   isAuthActive,
+  resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
 
@@ -42,12 +43,8 @@ const Config = cmp(async function Config(props: any) {
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  let authPrefix = 'Bearer'
-  try {
-    const v = getModelPath(model, `main.${KIT}.config.auth.prefix`,
-      { only_active: false, required: false })
-    if (null != v) authPrefix = v
-  } catch (_e) { /* ignore */ }
+  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
+  const authPrefix = resolveAuthPrefix(model)
   const authBlock = authActive
     ? `auth: {
       prefix: '${authPrefix}',

package/project/.sdk/src/cmp/ts/ReadmeEntity_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -99,10 +99,22 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape that generates <Name>LoadMatch, so the
+      // example always type-checks.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{ ${loadItems.map((it: any) =>
+          `${it.name}: ${exampleValue(entity, entity.op && entity.op.load, it.name,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
+        : ''
       Content(`#### Example: Load
 
 \`\`\`ts
-const ${eVar} = await client.${entity.Name}().load(${idF ? `{ ${idF}: ${exampleValue(entity, entity.op && entity.op.load, idF, entity.name + '_id')} }` : ''})
+const ${eVar} = await client.${entity.Name}().load(${loadArg})
 \`\`\`
 
 `)
@@ -119,16 +131,20 @@ const ${eVar}s = await client.${entity.Name}().list()
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape that generates <Name>CreateData:
+      // every required member must appear (the /* type */ placeholders also
+      // mark the block as an illustration for the doc gates); an
+      // all-optional create renders an empty — still assignable — literal.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
 \`\`\`ts
 const ${eVar} = await client.${entity.Name}().create({
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${canonToType(field.type, target.name)} */,
+      createItems.map((it: any) => {
+        Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
 `)
-        }
       })
       Content(`})
 \`\`\`

package/project/.sdk/src/cmp/ts/ReadmeQuick_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityDataIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -18,9 +18,15 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // Find the first published entity for examples
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  // Find a nested entity if available
+  // Find a nested entity if available: one with a parent chain
+  // (relations.ancestors), an active load op, and a required non-id load
+  // param to demonstrate (the parent key, e.g. page_id).
   const nestedEntity = Object.values(entity).find((e: any) =>
-    e.active !== false && e.ancestors && e.ancestors.length > 0
+    e.active !== false &&
+    e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
+    entityOps(e).includes('load') &&
+    opRequestShape(e, 'load').items.some((it: any) =>
+      !it.optional && it.name !== entityIdField(e))
   ) as any
 
   const ctor = isAuthActive(model)
@@ -44,7 +50,7 @@ const client = ${ctor}
     // reserved word (`const delete = ...` is a TS1109 syntax error).
     const eVar = safeVarName(eName.toLowerCase(), 'ts')
     const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
-    const opnames = Object.keys(exampleEntity.op || {})
+    const opnames = entityOps(exampleEntity)
     // Model-driven id key: `idF` is the entity's id-like MATCH field name, or
     // null when it has none (then load/remove match on no argument).
     const idF = entityIdField(exampleEntity)
@@ -74,22 +80,26 @@ for (const ${eVar} of ${eVar}s) {
       const neName = nom(nestedEntity, 'Name')
       const neVar = safeVarName(neName.toLowerCase(), 'ts')
       const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
-      const parentFields = (nestedEntity.fields || [])
-        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
-      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
       const loadOp = nestedEntity.op && nestedEntity.op.load
 
-      // Model-driven id key: only emit an id match line if this nested entity
-      // actually has an id-like key field (some response-wrapped specs do not).
+      // Model-driven match: every REQUIRED load-match key — the same shape
+      // that generates <Name>LoadMatch, so the example always type-checks.
+      // Parent keys (e.g. page_id) first, the entity's own id last.
       const neIdF = entityIdField(nestedEntity)
-      const neMatchLines = [`    ${parentParam}: ${exampleValue(nestedEntity, loadOp, parentParam, 'example')},`]
-      if (neIdF) {
-        neMatchLines.push(`    ${neIdF}: ${exampleValue(nestedEntity, loadOp, neIdF, 'example_id')},`)
-      }
+      const neRequired = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+      const parentItem = neRequired.find((it: any) => it.name !== neIdF) as any
+      const parentParam = parentItem && parentItem.name
+      const parentName = parentParam ? parentParam.replace(/_id$/, '') : 'its parent'
+      const neMatchLines = neRequired.map((it: any) =>
+        `    ${it.name}: ${exampleValue(nestedEntity, loadOp, it.name,
+          it.name === neIdF ? 'example_id' : 'example_' + it.name)},`)
 
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
-${neName} is nested under ${eName}, so provide the \`${parentParam}\`.
+${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 \`load()\` returns the entity directly and throws on failure:
 
 \`\`\`ts
@@ -106,13 +116,25 @@ ${neMatchLines.join('\n')}
 `)
     }
     else if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first) — the same shape that
+      // generates <Name>LoadMatch, so the example always type-checks.
+      const loadRequired = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadRequired.length
+        ? `{ ${loadRequired.map((it: any) =>
+          `${it.name}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.load, it.name,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
+
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
 \`load()\` returns the entity directly and throws on failure:
 
 \`\`\`ts
 try {
-  const ${eVar} = await client.${eName}().load(${idF ? `{ ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.load, idF, 'example_id')} }` : ''})
+  const ${eVar} = await client.${eName}().load(${loadArg})
   console.log(${eVar})
 } catch (err) {
   console.error('load failed:', err)
@@ -133,12 +155,19 @@ try {
       // <Name>CreateData (a TS2345); update is a patch, so a couple of fields
       // suffice.
       const exampleFields = (opname: string): string[] => {
+        // ids are rendered separately as the match key for update/remove; a
+        // REQUIRED id stays (dropping it makes the literal unassignable).
         const items = opRequestShape(exampleEntity, opname).items
-          .filter((it: any) => it.name !== idF && it.name !== 'id')
+          .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
+            ('create' === opname && !it.optional))
         const required = items.filter((it: any) => !it.optional)
+        const optional = items.filter((it: any) => it.optional)
+        // Required members must all appear or the literal is not assignable
+        // to the typed <Name>{Create,Update}Data; pad update (a patch) with a
+        // sample optional field or two.
         const chosen = 'create' === opname
           ? (required.length ? required : items.slice(0, 2))
-          : items.slice(0, 2)
+          : required.concat(optional).slice(0, Math.max(2, required.length))
         return chosen.map((it: any) =>
           `  ${it.name}: ${exampleValue(exampleEntity, exampleEntity.op[opname], it.name, 'example_' + it.name)},`)
       }
@@ -175,8 +204,17 @@ const updated = await client.${eName}().update({${updateBody}})
 `)
       }
       if (opnames.includes('remove')) {
+        // Every REQUIRED remove-match key: the id (off the created record
+        // when possible) plus parent keys like page_id.
+        const removeLines = opRequestShape(exampleEntity, 'remove').items
+          .filter((it: any) => !it.optional || it.name === idF)
+          .sort((a: any, b: any) =>
+            (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+          .map((it: any) => it.name === idF
+            ? `  ${it.name}: ${idValueFor('remove')},`
+            : `  ${it.name}: ${exampleValue(exampleEntity, exampleEntity.op.remove, it.name, 'example_' + it.name)},`)
         Content(`// Remove
-await client.${eName}().remove(${idF ? `{\n  ${idF}: ${idValueFor('remove')},\n}` : ''})
+await client.${eName}().remove(${removeLines.length ? `{\n${removeLines.join('\n')}\n}` : ''})
 `)
       }
       Content(`\`\`\`