@voxgig/sdkgen 1.3.1 → 1.3.4

package/dist/utility.js

@@ -7,6 +7,7 @@ exports.SdkGenError = void 0;
 exports.resolvePath = resolvePath;
 exports.requirePath = requirePath;
 exports.isAuthActive = isAuthActive;
+exports.resolveAuthPrefix = resolveAuthPrefix;
 const node_path_1 = __importDefault(require("node:path"));
 const apidef_1 = require("@voxgig/apidef");
 function resolvePath(ctx$, path) {
@@ -16,7 +17,7 @@ function resolvePath(ctx$, path) {
 // True unless the model declares auth off. Templates use this to gate
 // apikey-related code, docs, and examples for public APIs that need no
 // authentication. Two opt-outs, in priority order:
-//   1. main.kit.info.auth: false        (user-facing, set in api-info.jsonic)
+//   1. main.kit.info.auth: false        (user-facing, set in api-info.aontu)
 //   2. main.kit.config.auth.active: false
 function isAuthActive(model) {
     const info = (0, apidef_1.getModelPath)(model, `main.${apidef_1.KIT}.info`, { only_active: false, required: false });
@@ -25,6 +26,24 @@ function isAuthActive(model) {
     const auth = (0, apidef_1.getModelPath)(model, `main.${apidef_1.KIT}.config.auth`, { only_active: false, required: false });
     return null == auth || false !== auth.active;
 }
+// The credential prefix for the Authorization header value, resolved in
+// priority order:
+//   1. main.kit.config.auth.prefix   (per-SDK user override)
+//   2. main.kit.info.security.prefix (spec-derived, set by apidef from the
+//      API's securityScheme — e.g. 'OAuth' for Statuspage)
+//   3. 'Bearer'                      (conventional fallback)
+// '' is a valid resolved value: it means a raw credential with no prefix
+// (e.g. an apiKey scheme in a custom header). Config generators for every
+// language target must use this instead of hardcoding 'Bearer'.
+function resolveAuthPrefix(model) {
+    const auth = (0, apidef_1.getModelPath)(model, `main.${apidef_1.KIT}.config.auth`, { only_active: false, required: false });
+    if (null != auth && null != auth.prefix)
+        return String(auth.prefix);
+    const security = (0, apidef_1.getModelPath)(model, `main.${apidef_1.KIT}.info.security`, { only_active: false, required: false });
+    if (null != security && null != security.prefix)
+        return String(security.prefix);
+    return 'Bearer';
+}
 function requirePath(ctx$, path, flags) {
     const fullpath = resolvePath(ctx$, path);
     const ignore = null == flags?.ignore ? false : flags.ignore;

package/dist/utility.js.map

@@ -1 +1 @@
-{"version":3,"file":"utility.js","sourceRoot":"","sources":["../src/utility.ts"],"names":[],"mappings":";;;;;;AA8DE,kCAAW;AACX,kCAAW;AACX,oCAAY;AA/Dd,0DAA4B;AAI5B,2CAAkD;AAGlD,SAAS,WAAW,CAAC,IAAS,EAAE,IAAY;IAC1C,MAAM,QAAQ,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;IAC7D,OAAO,QAAQ,CAAA;AACjB,CAAC;AAGD,sEAAsE;AACtE,uEAAuE;AACvE,mDAAmD;AACnD,8EAA8E;AAC9E,0CAA0C;AAC1C,SAAS,YAAY,CAAC,KAAU;IAC9B,MAAM,IAAI,GAAG,IAAA,qBAAY,EAAC,KAAK,EAAE,QAAQ,YAAG,OAAO,EACjD,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1C,IAAI,IAAI,IAAI,KAAK,KAAK,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAA;IAE7C,MAAM,IAAI,GAAG,IAAA,qBAAY,EAAC,KAAK,EAAE,QAAQ,YAAG,cAAc,EACxD,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1C,OAAO,IAAI,IAAI,IAAI,IAAI,KAAK,KAAK,IAAI,CAAC,MAAM,CAAA;AAC9C,CAAC;AAGD,SAAS,WAAW,CAAC,IAAS,EAAE,IAAY,EAAE,KAA4B;IACxE,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACxC,MAAM,MAAM,GAAG,IAAI,IAAI,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAA;IAE3D,kEAAkE;IAClE,sEAAsE;IACtE,qEAAqE;IACrE,wEAAwE;IACxE,qCAAqC;IACrC,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,CAAC;YACH,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;QAC3B,CAAC;QACD,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;YAC7D,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAA;AAC1B,CAAC;AAGD,MAAM,WAAY,SAAQ,KAAK;IAC7B,YAAY,GAAG,IAAW;QACxB,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;IAC3B,CAAC;CACF;AAOC,kCAAW"}
+{"version":3,"file":"utility.js","sourceRoot":"","sources":["../src/utility.ts"],"names":[],"mappings":"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"}

package/model/sdkgen.aontu

@@ -10,7 +10,7 @@ main: def: {
 # SDK but not listed here are appended afterwards in spec-defined
 # order. Override per-SDK by setting
 # `main.kit.config.docs_order: ['py','ts',...]` in
-# `<sdk>/.sdk/model/config.jsonic`.
+# `<sdk>/.sdk/model/config.aontu`.
 main: kit: config: docs_order: *['ts','py','php','go','rb','lua'] | [&: string]
 
 main: kit: target: &: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "1.3.1",
+  "version": "1.3.4",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "types": "dist/sdkgen.d.ts",

package/project/.sdk/model/feature/feature-index.aontu

@@ -0,0 +1,5 @@
+# Features
+
+
+@"test.aontu"
+@"log.aontu"

package/project/.sdk/src/cmp/go/Config_go.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/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)
 \`\`\`
 
 `)