@voxgig/sdkgen 1.3.1 → 1.3.2

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

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content, canonToType, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue, goVarName } from './utility_go'
+
 
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
@@ -39,12 +41,15 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
   publishedEntities.map((entity: any) => {
-    const opnames = Object.keys(entity.op || {})
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would not compile.
+    const opnames = entityOps(entity)
     const fields = entity.fields || []
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
-    // Variable-safe lowercase name (a `Type`/`Range` entity must not bind a Go keyword).
-    const eVar = safeVarName(entity.name, 'go')
+    // camelCase Go identifier (a `status_embed_config` entity must not bind a
+    // snake_case Go variable, and a `type`/`range` entity not a Go keyword).
+    const eVar = goVarName(entity.name)
 
     Content(`
 ### ${entity.Name}
@@ -97,10 +102,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 the op's request match, so
+      // the example always carries the keys the route needs.
+      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
+        ? `map[string]any{${loadItems.map((it: any) =>
+          `"${it.name}": ${exampleValue(entity, entity.op && entity.op.load, it.name,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')}}`
+        : 'nil'
       Content(`#### Example: Load
 
 \`\`\`go
-${eVar}, err := client.${entity.Name}(nil).Load(${idF ? `map[string]any{"${idF}": "${entity.name}_id"}` : 'nil'}, nil)
+${eVar}, err := client.${entity.Name}(nil).Load(${loadArg}, nil)
 if err != nil {
     panic(err)
 }
@@ -125,18 +142,27 @@ fmt.Println(${eVar}s) // the array of records
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape that generates the op's request
+      // data: every required member must appear — including a required id
+      // (the /* type */ placeholders also mark the block as an illustration
+      // for the doc gates); an all-optional create renders an empty — still
+      // valid — literal, and the compiled example is self-consuming.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
 \`\`\`go
 result, err := client.${entity.Name}(nil).Create(map[string]any{
 `)
-      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(`}, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)

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

@@ -206,10 +206,14 @@ func TestReadmeGoSnippets(t *testing.T) {
 
 	// Build. The Go compiler is the oracle for unused imports/vars in the
 	// wrapped fragments: blank them out and rebuild. Any OTHER error is a
-	// genuine snippet bug and fails the test.
+	// genuine snippet bug and fails the test. The loop is progress-based,
+	// not attempt-capped: \`-gcflags=-e\` lifts the compiler's 10-error cap so
+	// every error surfaces in one round, applyFixes repairs them all, and
+	// the loop continues while a round makes progress. It fails hard when no
+	// fix applies, and fails as non-converged when a round changes nothing
+	// in the build output (the fixes stopped helping).
 	var lastOut string
-	built := false
-	for attempt := 0; attempt < 15; attempt++ {
+	for {
 		for name, content := range fragFiles {
 			if err := os.WriteFile(filepath.Join(fragDir, name+".go"), []byte(content), 0o644); err != nil {
 				t.Fatal(err)
@@ -217,17 +221,16 @@ func TestReadmeGoSnippets(t *testing.T) {
 		}
 		out, buildErr := runGoBuild(moduleRoot, binDir, progDirs, fragPkg)
 		if buildErr == nil {
-			built = true
 			break
 		}
+		if out == lastOut {
+			t.Fatalf("README go snippets did not converge to a clean build:\\n%s", out)
+		}
 		lastOut = out
 		if !applyFixes(out, fragFiles) {
 			t.Fatalf("README go snippet failed to compile:\\n%s", out)
 		}
 	}
-	if !built {
-		t.Fatalf("README go snippets did not converge to a clean build:\\n%s", lastOut)
-	}
 
 	// Everything compiled. Now RUN the test-mode variants of the complete
 	// programs and fail on a genuine runtime panic.
@@ -357,15 +360,16 @@ func isIdentByte(c byte) bool {
 		(c >= '0' && c <= '9')
 }
 
-// runGoBuild type-checks the fragment package with a plain \`go build\`
-// (a non-main package produces no output but is still fully type-checked
-// — unlike \`go build -o dir/\`, which skips non-main packages), and builds
-// each complete program with \`-o binDir/\`. Any compile error from either
-// is returned.
+// runGoBuild type-checks the fragment package with \`go build -gcflags=-e\`
+// (a non-main package produces no output but is still fully type-checked —
+// unlike \`go build -o dir/\`, which skips non-main packages — and \`-e\` lifts
+// the compiler's 10-errors-per-package cap so EVERY unused-var/import error
+// surfaces in a single round), and builds each complete program with
+// \`-o binDir/\`. Any compile error from either is returned.
 func runGoBuild(dir, binDir string, progDirs []string, fragPkg string) (string, error) {
 	var out strings.Builder
 	if fragPkg != "" {
-		cmd := exec.Command("go", "build", fragPkg)
+		cmd := exec.Command("go", "build", "-gcflags=-e", fragPkg)
 		cmd.Dir = dir
 		o, err := cmd.CombinedOutput()
 		out.Write(o)
@@ -374,7 +378,7 @@ func runGoBuild(dir, binDir string, progDirs []string, fragPkg string) (string,
 		}
 	}
 	if len(progDirs) > 0 {
-		args := append([]string{"build", "-o", binDir + string(os.PathSeparator)}, progDirs...)
+		args := append([]string{"build", "-gcflags=-e", "-o", binDir + string(os.PathSeparator)}, progDirs...)
 		cmd := exec.Command("go", args...)
 		cmd.Dir = dir
 		o, err := cmd.CombinedOutput()

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { goVarName } from './utility_go'
+
 
 // A type-correct Go literal for a field's canonical type.
 function goLit(type: any): string {
@@ -32,7 +34,9 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const exampleEntity = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
-  const eLower = safeVarName(eName.toLowerCase(), 'go')
+  // camelCase Go identifier (never snake_case or flattened lowercase,
+  // never a Go keyword).
+  const eLower = exampleEntity ? goVarName(exampleEntity.name) : 'entity'
   // Model-driven id key: null when the entity has no id-like field.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   // Drive the test-mode example off the entity's PRIMARY op — never a hardcoded

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

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content, isAuthActive, entityIdField, entityPrimaryOp, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, entityIdField, entityPrimaryOp } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { goVarName } from './utility_go'
+
 
 const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const { target, ctx$: { model } } = props
@@ -50,7 +52,9 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
 
   // First published entity name, for the Result shape illustration.
   const firstEntityName = (entityList[0] as any)?.Name || 'Entity'
-  const firstEntityVar = safeVarName(firstEntityName.toLowerCase(), 'go')
+  // camelCase Go identifier (never snake_case or flattened lowercase,
+  // never a Go keyword).
+  const firstEntityVar = goVarName((entityList[0] as any)?.name || 'entity')
   // Model-driven id key: null when the example entity has no id-like field, so
   // the Result-shape illustration passes a nil match.
   const firstIdF = entityIdField(entityList[0] || {})

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue, goVarName } from './utility_go'
+
 
 // Emits the go/README.md Quickstart as ONE complete, compilable program.
 // Every entity operation returns `(value, error)` where `value` is the
@@ -35,40 +37,54 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    // Variable-safe lowercase name — a `Type`/`Range` entity must not bind a Go
-    // keyword (`type, err := ...` fails `go build`).
-    const eLower = safeVarName(eName.toLowerCase(), 'go')
-    const opnames = Object.keys(exampleEntity.op || {})
-
-    // Model-driven example fields (from the same op shape the request types are
-    // built from) so create/update reference REAL writable fields, not a
-    // hardcoded "name", and ids use a type-correct literal.
-    const idField = (exampleEntity.id && exampleEntity.id.field) || 'id'
+    // camelCase variable name — a `status_embed_config` entity must not bind
+    // a snake_case Go variable, and a `Type`/`Range` entity must not bind a
+    // Go keyword (`type, err := ...` fails `go build`).
+    const eLower = goVarName(exampleEntity.name)
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would not compile.
+    const opnames = entityOps(exampleEntity)
+
     // Model-driven id key: null when the entity has no id-like field (a
     // response-wrapped spec). When null, load/remove pass a nil match and
     // update omits the id member.
     const idF = entityIdField(exampleEntity)
-    const goLit = (type: any): string => {
-      const k = canonKey(type)
-      if ('INTEGER' === k || 'NUMBER' === k) return '1'
-      if ('BOOLEAN' === k) return 'true'
-      if ('ARRAY' === k) return '[]any{}'
-      if ('OBJECT' === k) return 'map[string]any{}'
-      return '"example"'
-    }
-    const examplePairs = (opname: string): string[] => {
+
+    // Model-driven example members for an op body, from the SAME op shape the
+    // request types are built from (opRequestShape), so create/update
+    // reference REAL writable fields, not a hardcoded "name", and every value
+    // is a type-correct Go literal (exampleValue). ids are rendered
+    // separately as the match key for update/remove; a REQUIRED id stays for
+    // create (dropping it makes the payload incomplete).
+    const exampleFields = (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)
+      const optional = items.filter((it: any) => it.optional)
+      // Required members must all appear or the payload is incomplete; 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)
-      return chosen.map((it: any) => `"${it.name}": ${goLit(it.type)}`)
+        : 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 that generates the op's request
+    // match, 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
+        ? `map[string]any{${matchItems.map((it: any) =>
+          `"${it.name}": ${exampleValue(exampleEntity, exampleEntity.op[opname], it.name,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
+        : 'nil'
     }
-    const idOp = opnames.includes('load') ? 'load' : (opnames.includes('update') ? 'update' : 'remove')
-    const idShape = opRequestShape(exampleEntity, idOp)
-      .items.find((it: any) => it.name === idField || it.name === 'id')
-    const idLit = idShape ? goLit(idShape.type) : '"example_id"'
 
     if (opnames.includes('list')) {
       body.push(`    // List ${eLower} records — the value is the array of records itself.`)
@@ -85,7 +101,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
     if (opnames.includes('load')) {
       body.push(`    // Load a single ${eLower} — the value is the loaded record.`)
-      body.push(`    ${eLower}, err := client.${eName}(nil).Load(${idF ? `map[string]any{"${idF}": ${idLit}}` : 'nil'}, nil)`)
+      body.push(`    ${eLower}, err := client.${eName}(nil).Load(${matchArg('load')}, nil)`)
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
@@ -96,7 +112,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
     if (opnames.includes('create')) {
       body.push(`    // Create a ${eLower}.`)
-      body.push(`    created, err := client.${eName}(nil).Create(map[string]any{${examplePairs('create').join(', ')}}, nil)`)
+      body.push(`    created, err := client.${eName}(nil).Create(map[string]any{${exampleFields('create').join(', ')}}, nil)`)
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
@@ -106,8 +122,13 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     }
 
     if (opnames.includes('update')) {
+      // The id member (when the entity has an id-like key) plus example
+      // patch fields — the same shape that generates the op's request data.
+      const updateMembers = (idF
+        ? [`"${idF}": ${exampleValue(exampleEntity, exampleEntity.op.update, idF, 'example_id')}`]
+        : []).concat(exampleFields('update'))
       body.push(`    // Update a ${eLower}.`)
-      body.push(`    updated, err := client.${eName}(nil).Update(map[string]any{${(idF ? [`"${idF}": ${idLit}`] : []).concat(examplePairs('update')).join(', ')}}, nil)`)
+      body.push(`    updated, err := client.${eName}(nil).Update(map[string]any{${updateMembers.join(', ')}}, nil)`)
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
@@ -118,7 +139,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
     if (opnames.includes('remove')) {
       body.push(`    // Remove a ${eLower}.`)
-      body.push(`    removed, err := client.${eName}(nil).Remove(${idF ? `map[string]any{"${idF}": ${idLit}}` : 'nil'}, nil)`)
+      body.push(`    removed, err := client.${eName}(nil).Remove(${matchArg('remove')}, nil)`)
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)

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

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue, goVarName } from './utility_go'
+
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
@@ -158,11 +160,16 @@ same parameters as \`Direct()\`.
 
     // Entity reference sections
     publishedEntities.map((ent: any) => {
-      const opnames = Object.keys(ent.op || {})
+      // ACTIVE ops only — an inactive op generates no method, so an example
+      // calling it would not compile.
+      const opnames = entityOps(ent)
       const fields = ent.fields || []
       // Model-driven id key: null when this entity has no id-like field, in
       // which case load/remove pass a nil match and update omits the id.
       const idF = entityIdField(ent)
+      // camelCase Go identifier (a `status_embed_config` entity must not bind
+      // a snake_case Go variable).
+      const eVar = goVarName(ent.name)
 
       Content(`
 ---
@@ -178,7 +185,8 @@ same parameters as \`Direct()\`.
       }
 
       Content(`\`\`\`go
-${ent.name} := client.${ent.Name}(nil)
+${eVar} := client.${ent.Name}(nil)
+fmt.Println(${eVar}.GetName()) // "${ent.name}"
 \`\`\`
 
 `)
@@ -205,9 +213,10 @@ ${ent.name} := client.${ent.Name}(nil)
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
           // Only emit columns for operations this entity actually exposes —
-          // never advertise a create/update/remove column the entity lacks.
+          // never advertise a create/update/remove column the entity lacks
+          // (opnames already carries active ops only).
           const opcols = ['load', 'list', 'create', 'update', 'remove']
-            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
+            .filter((op: string) => opnames.includes(op))
           Content(`### Field Usage by Operation
 
 | Field | ${opcols.join(' | ')} |
@@ -247,11 +256,29 @@ ${info.desc}
 
 `)
 
-          // Show example
+          // Show example. Every compiled example is self-consuming — check
+          // `err` and print the result — so the doc gate builds it without
+          // unused-variable repairs, and readers see the idiomatic pattern.
           if ('load' === opname || 'remove' === opname) {
             const goOpName = opname.charAt(0).toUpperCase() + opname.slice(1)
+            // The id key plus every REQUIRED match key (parent path params
+            // like page_id) — the same shape that generates the op's request
+            // match, so the example always carries the keys the route needs.
+            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
+              ? `map[string]any{${matchItems.map((it: any) =>
+                `"${it.name}": ${exampleValue(ent, ent.op && ent.op[opname], it.name,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')}}`
+              : 'nil'
             Content(`\`\`\`go
-result, err := client.${ent.Name}(nil).${goOpName}(${idF ? `map[string]any{"${idF}": "${ent.name}_id"}` : 'nil'}, nil)
+result, err := client.${ent.Name}(nil).${goOpName}(${arg}, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)
@@ -259,31 +286,57 @@ result, err := client.${ent.Name}(nil).${goOpName}(${idF ? `map[string]any{"${id
           else if ('list' === opname) {
             Content(`\`\`\`go
 results, err := client.${ent.Name}(nil).List(nil, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(results)
 \`\`\`
 
 `)
           }
           else if ('create' === opname) {
+            // Members come from the SAME shape that generates the op's
+            // request data: every required member must appear — including a
+            // required id (the /* type */ placeholders also mark the block
+            // as an illustration for the doc gates); an all-optional create
+            // renders an empty — still valid — literal.
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`go
 result, err := client.${ent.Name}(nil).Create(map[string]any{
 `)
-            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(`}, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)
           }
           else if ('update' === opname) {
-            const updateIdLine = idF ? `    "${idF}": "${ent.name}_id",\n` : ''
+            // The id key plus every REQUIRED data member — the same shape
+            // that generates the op's request data — 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(`\`\`\`go
 result, err := client.${ent.Name}(nil).Update(map[string]any{
-${updateIdLine}    // Fields to update
+${updateLines}    // Fields to update
 }, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)

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

@@ -12,6 +12,10 @@ result, err := client.Direct(map[string]any{
     "method": "GET",
     "params": map[string]any{"id": "example"},
 })
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)

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