@voxgig/sdkgen 1.3.1 → 1.3.4

package/project/.sdk/src/cmp/go/ReadmeTopQuick_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue, goVarName } from './utility_go'
+
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -31,42 +33,61 @@ client := ${ctor}
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const eVar = safeVarName(eName.toLowerCase(), 'go')
-    const opnames = Object.keys(exampleEntity.op || {})
+    // camelCase Go identifier (never snake_case, never a Go keyword).
+    const eVar = goVarName(exampleEntity.name)
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would not compile.
+    const opnames = entityOps(exampleEntity)
 
     let hasCall = false
 
     if (opnames.includes('list')) {
       Content(`// List all ${eName.toLowerCase()}s
 ${eVar}s, err := client.${eName}(nil).List(nil, nil)
+if err != nil {
+    panic(err)
+}
 fmt.Println(${eVar}s)
 `)
       hasCall = true
     }
 
-    // Find a nested entity for a more interesting example
+    // Find a nested entity for a more interesting example: 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
 
-    if (nestedEntity && opnames.includes('load')) {
+    if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
-      const neVar = safeVarName(neName.toLowerCase(), 'go')
-      const parentFields = (nestedEntity.fields || [])
-        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
-      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
-      // Model-driven id key: only include the nested entity's id if it has one.
+      const neVar = goVarName(nestedEntity.name)
+      // Model-driven match: every REQUIRED load-match key — the same shape
+      // that generates the op's request match, so the example always carries
+      // the keys the route needs. Parent keys (e.g. page_id) first, the
+      // entity's own id last, each value a type-correct Go literal.
       const neIdF = entityIdField(nestedEntity)
-      const neMatchPairs = [`"${parentParam}": "example"`]
-      if (neIdF) {
-        neMatchPairs.push(`"${neIdF}": "example_id"`)
-      }
+      const neLoadOp = nestedEntity.op && nestedEntity.op.load
+      const neMatchPairs = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+        .map((it: any) =>
+          `"${it.name}": ${exampleValue(nestedEntity, neLoadOp, it.name,
+            it.name === neIdF ? 'example_id' : 'example_' + it.name)}`)
 
       Content(`
 // Load a specific ${neName.toLowerCase()}
 ${neVar}, err := client.${neName}(nil).Load(
     map[string]any{${neMatchPairs.join(', ')}}, nil,
 )
+if err != nil {
+    panic(err)
+}
 fmt.Println(${neVar})
 `)
       hasCall = true
@@ -74,8 +95,22 @@ fmt.Println(${neVar})
 
     // Fallback: APIs with only `load` (no list, no nested) — still show one call.
     if (!hasCall && opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first) — nil when there are none.
+      const idF = entityIdField(exampleEntity)
+      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
+        ? `map[string]any{${loadItems.map((it: any) =>
+          `"${it.name}": ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.load, it.name,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
+        : 'nil'
       Content(`// Load ${eName.toLowerCase()} data
-${eVar}, err := client.${eName}(nil).Load(map[string]any{}, nil)
+${eVar}, err := client.${eName}(nil).Load(${loadArg}, nil)
+if err != nil {
+    panic(err)
+}
 fmt.Println(${eVar})
 `)
       hasCall = true

package/project/.sdk/src/cmp/go/utility_go.ts

@@ -2,6 +2,13 @@
 import * as Path from 'node:path'
 
 
+import {
+  camelify,
+  canonKey,
+  each,
+  safeVarName,
+} from '@voxgig/sdkgen'
+
 import {
   clone,
   walk,
@@ -13,6 +20,67 @@ function projectPath(suffix?: string): string {
 }
 
 
+// --- Model-driven example literals -----------------------------------------
+// Doc snippets must use example values whose TYPE matches the model's
+// declared param/field type — a number id shown as a quoted string documents
+// a call the API would reject. These helpers derive the example literal from
+// the SAME model source the request shapes are built from (opRequestShape),
+// so the docs and the model can never disagree. Go twin of the ts
+// exampleValue (cmp/ts/utility_ts.ts), rendering Go literals.
+
+// The declared canon-type sentinel of a named parameter of an op — looked up
+// in the op's `points[].args.params[]` exactly as the typed-model generator
+// does. Falls back to the entity field of the same name (used when the op
+// has no params and the request shape mirrors the entity fields). Returns
+// undefined when neither is present.
+function paramCanonType(entity: any, op: any, paramName: string): unknown {
+  const points = op && op.points ? each(op.points) : []
+  for (const pt of points as any[]) {
+    const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
+    const found = (params as any[]).find((p: any) => p && p.name === paramName)
+    if (found) {
+      return found.type
+    }
+  }
+  const field = (entity && entity.fields ? each(entity.fields) : [])
+    .find((f: any) => f && f.name === paramName) as any
+  return field && field.type
+}
+
+
+// A type-correct Go example literal for a named match/data parameter of an
+// op, derived entirely from the model. INTEGER/NUMBER render as the bare
+// number `1`, BOOLEAN as `true`, ARRAY as the empty `[]any{}` and OBJECT as
+// the empty `map[string]any{}`, everything else (STRING, unknown, missing)
+// as the quoted `placeholder`.
+function exampleValue(entity: any, op: any, paramName: string, placeholder: string): string {
+  const key = canonKey(paramCanonType(entity, op, paramName))
+  if ('INTEGER' === key || 'NUMBER' === key) {
+    return '1'
+  }
+  if ('BOOLEAN' === key) {
+    return 'true'
+  }
+  if ('ARRAY' === key) {
+    return '[]any{}'
+  }
+  if ('OBJECT' === key) {
+    return 'map[string]any{}'
+  }
+  return `"${placeholder}"`
+}
+
+
+// A camelCase Go identifier for a snake_case model name
+// (`status_embed_config` -> `statusEmbedConfig`) — Go variables are
+// camelCase, never snake_case — with the reserved-word guard applied (a
+// `type`/`range` entity must not bind a Go keyword).
+function goVarName(name: string): string {
+  const pascal = camelify(name)
+  return safeVarName(pascal.charAt(0).toLowerCase() + pascal.slice(1), 'go')
+}
+
+
 function formatGoMap(obj: any, indent: number = 0): string {
   if (obj == null) {
     return 'nil'
@@ -82,7 +150,9 @@ function clean(o: any) {
 
 export {
   clean,
+  exampleValue,
   formatGoMap,
   formatGoValue,
+  goVarName,
   projectPath,
 }

package/project/.sdk/src/cmp/js/Config_js.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/js/ReadmeEntity_js.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 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}: ${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,21 @@ const ${eVar}s = await 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 (the /* type */
+      // placeholders mark the block as an illustration); an all-optional
+      // create renders an empty — still valid — 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/js/ReadmeQuick_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityOps, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -36,7 +36,9 @@ const client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
-    const opnames = Object.keys(exampleEntity.op || {})
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would be wrong.
+    const opnames = entityOps(exampleEntity)
 
     // Model-driven example fields, in parity with the ts target: derive the
     // create/update body from the op shape (opRequestShape) so the docs show
@@ -47,23 +49,45 @@ const client = ${ctor}
     // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
     const eVar = safeVarName(exampleEntity.name, 'js')
     const exampleFields = (opname: string): string[] => {
+      // ids are rendered separately as the match key for update/remove; a
+      // REQUIRED id stays for create (dropping it makes the payload
+      // incomplete).
       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)
-      // create needs ALL required fields for parity with the typed ts target.
+      const optional = items.filter((it: any) => it.optional)
+      // create needs ALL required fields for parity with the typed ts target;
+      // 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)
+        : 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)},`)
     }
 
+    // The full REQUIRED match for load/remove (id first, then parent path
+    // params like page_id) — the same shape the runtime resolves path params
+    // from, so the example always carries the keys the route needs.
+    const matchArg = (opname: string): string => {
+      const matchItems = opRequestShape(exampleEntity, 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))
+      return 0 < matchItems.length
+        ? `{ ${matchItems.map((it: any) =>
+          `${it.name}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op[opname], it.name,
+            it.name === idF ? exampleEntity.name + '_id' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
+    }
+
     if (opnames.includes('load')) {
       Content(`
 ### Load ${article} ${eName}
 
 \`\`\`js
-const ${eVar} = await client.${eName}().load(${idF ? `{ ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.load, idF, exampleEntity.name + '_id')} }` : ''})
+const ${eVar} = await client.${eName}().load(${matchArg('load')})
 console.log(${eVar})
 \`\`\`
 `)
@@ -115,7 +139,7 @@ console.log(updated)
 ### Remove a ${eName}
 
 \`\`\`js
-await client.${eName}().remove(${idF ? `{ ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.remove, idF, exampleEntity.name + '_id')} }` : ''})
+await client.${eName}().remove(${matchArg('remove')})
 \`\`\`
 `)
     }

package/project/.sdk/src/cmp/js/ReadmeRef_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -272,8 +272,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}: ${exampleValue(ent, ent.op && ent.op[opname], it.name,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')} }`
+              : ''
             Content(`\`\`\`ts
-const result = await client.${ent.Name}().${opname}(${idF ? `{ ${idF}: ${exampleValue(ent, ent.op && ent.op[opname], idF, ent.name + '_id')} }` : ''})
+const result = await client.${ent.Name}().${opname}(${arg})
 \`\`\`
 
 `)
@@ -286,14 +298,19 @@ const results = await client.${ent.Name}().${opname}()
 `)
           }
           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 (the /* type */
+            // placeholders mark the block as an illustration); an
+            // all-optional create renders an empty — still valid — literal.
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`ts
 const result = await client.${ent.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(`})
 \`\`\`
@@ -301,12 +318,18 @@ const result = await client.${ent.Name}().create({
 `)
           }
           else if ('update' === opname) {
-            const updateIdLine = idF
-              ? `  ${idF}: ${exampleValue(ent, ent.op && ent.op.update, 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}: ${exampleValue(ent, ent.op && ent.op.update, it.name,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().update({
-${updateIdLine}  // Fields to update
+${updateLines}  // Fields to update
 })
 \`\`\`
 

package/project/.sdk/src/cmp/js/ReadmeTopQuick_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, packageName, envName, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -30,7 +30,9 @@ const client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const eVar = safeVarName(eName.toLowerCase(), 'js')
-    const opnames = Object.keys(exampleEntity.op || {})
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would be wrong.
+    const opnames = entityOps(exampleEntity)
 
     if (opnames.includes('list')) {
       Content(`// List all ${eName.toLowerCase()}s (returns an array)
@@ -41,26 +43,34 @@ for (const ${eVar} of ${eVar}s) {
 `)
     }
 
-    // Find a nested entity for a more interesting example
+    // Find a nested entity for a more interesting example: one with a parent
+    // chain (relations.ancestors), an active load op of its OWN, 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
 
-    if (nestedEntity && opnames.includes('load')) {
+    if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
       const neVar = safeVarName(neName.toLowerCase(), 'js')
-      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 the nested entity
-      // has an id-like key field.
+      // Every REQUIRED load-match key (parent keys like page_id first, the
+      // entity's own id last) — the same shape the runtime resolves path
+      // params from, so the example always works.
       const neIdF = entityIdField(nestedEntity)
-      const neMatchLines = [`  ${parentParam}: ${exampleValue(nestedEntity, loadOp, parentParam, 'example')},`]
-      if (neIdF) {
-        neMatchLines.push(`  ${neIdF}: ${exampleValue(nestedEntity, loadOp, neIdF, 'example_id')},`)
-      }
+      const neMatchLines = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === neIdF)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+        .map((it: any) =>
+          `  ${it.name}: ${exampleValue(nestedEntity, loadOp, it.name,
+            it.name === neIdF ? 'example_id' : 'example_' + it.name)},`)
 
       Content(`
 // Load a specific ${neName.toLowerCase()} (returns the entity)

package/project/.sdk/src/cmp/js/ReadmeTopTest_js.ts

@@ -22,15 +22,27 @@ const client = ${model.const.Name}SDK.test()
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const eVar = safeVarName(eName.toLowerCase(), 'js')
     // Drive the test-mode example off the entity's PRIMARY op (never a
     // hardcoded `load` a create-only entity lacks).
     const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
+    // A list() result is an array — name the variable accordingly.
+    const eVar = safeVarName(eName.toLowerCase(), 'js') +
+      ('list' === primaryOp ? 's' : '')
     const primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
     const idF = entityIdField(exampleEntity)
     let arg = ''
     if ('load' === primaryOp || 'remove' === primaryOp) {
-      arg = idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, 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))
+      arg = 0 < items.length
+        ? `{ ${items.map((it: any) =>
+          `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
+            it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
     } else if ('create' === primaryOp || 'update' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
@@ -40,7 +52,7 @@ const client = ${model.const.Name}SDK.test()
         `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
     }
     Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
-// ${eVar} is a bare entity populated with mock data
+// ${eVar} is ${'list' === primaryOp ? 'an array of bare entities' : 'a bare entity'} populated with mock data
 console.log(${eVar})
 `)
   }

package/project/.sdk/src/cmp/lua/Config_lua.ts

@@ -10,6 +10,7 @@ import {
   cmp,
   each,
   isAuthActive,
+  resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
 
@@ -39,8 +40,8 @@ const Config = cmp(async function Config(props: any) {
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  let authPrefix = ''
-  try { authPrefix = getModelPath(model, `main.${KIT}.config.auth.prefix`) } catch (_e) { }
+  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
+  const authPrefix = resolveAuthPrefix(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }

package/project/.sdk/src/cmp/lua/ReadmeEntity_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,24 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, executable Lua literal for a param: numeric/boolean/table
+// params render a typed literal; strings render the quoted placeholder (the
+// doc test EXECUTES runnable blocks, so a comment placeholder would not
+// parse).
+function luaLit(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 || 'OBJECT' === k) return '{}'
+  return `"${placeholder}"`
+}
+
+// Non-identifier table keys use bracket syntax.
+function luaKey(name: string): string {
+  return /^[A-Za-z_]\w*$/.test(name) ? name : `["${name}"]`
+}
+
+
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
 // methods with optional ctrl. The op descriptions are language-agnostic.
@@ -95,10 +113,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 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) =>
+          `${luaKey(it.name)} = ${luaLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
+        : ''
       Content(`#### Example: Load
 
 \`\`\`lua
-local ${entity.name}, err = client:${entity.Name}():load(${idF ? `{ ${idF} = "${entity.name}_id" }` : ''})
+local ${entity.name}, err = client:${entity.Name}():load(${loadArg})
 \`\`\`
 
 `)
@@ -115,16 +145,21 @@ local ${entity.name}s, err = 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 nil member would vanish
+      // from the table and a comment placeholder would not parse).
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
 \`\`\`lua
 local ${entity.name}, err = client:${entity.Name}():create({
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  ${field.name} = nil, -- ${canonToType(field.type, target.name)}
+      createItems.map((it: any) => {
+        Content(`  ${luaKey(it.name)} = ${luaLit(it.type, 'example_' + it.name)}, -- ${canonToType(it.type, target.name)}
 `)
-        }
       })
       Content(`})
 \`\`\`