@voxgig/sdkgen 1.3.4 → 1.3.5

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

@@ -143,10 +143,10 @@ 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.
+      // data (every required member appears, including a required id), each
+      // with a type-correct example VALUE via exampleValue — a
+      // `"name": /* type */` comment is not a value and yields uncompilable
+      // Go, so the example must carry a real literal.
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -155,7 +155,7 @@ fmt.Println(${eVar}s) // the array of records
 result, err := client.${entity.Name}(nil).Create(map[string]any{
 `)
       createItems.map((it: any) => {
-        Content(`    "${it.name}": /* ${canonToType(it.type, target.name)} */,
+        Content(`    "${it.name}": ${exampleValue(entity, entity.op && entity.op.create, it.name, 'example_' + it.name)},
 `)
       })
       Content(`}, nil)

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -32,16 +32,16 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const exampleEntity = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `Load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
+  // only when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   // 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
-  // `Load` a create-only entity lacks.
-  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'nil'
   if (exampleEntity && isMatchOp) {
@@ -54,6 +54,23 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testArg = `map[string]any{${chosen.map((it: any) => `"${it.name}": ${goLit(it.type)}`).join(', ')}}`
   }
 
+  // The op-driven test-mode block, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a Direct() call instead — never
+  // a fabricated method (`cap(primaryOp)` would also fail on a null op).
+  const testModeExample = primaryOp
+    ? `${eLower}, err := client.${eName}(nil).${cap(primaryOp)}(
+    ${testArg}, nil,
+)
+if err != nil {
+    panic(err)
+}
+fmt.Println(${eLower}) // the returned mock data`
+    : `result, err := client.Direct(map[string]any{"path": "/api/resource", "method": "GET"})
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)`
+
   const apikeyEnvLine = isAuthActive(model)
     ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
@@ -102,13 +119,7 @@ Create a mock client for unit testing \u2014 no server required:
 \`\`\`go
 client := sdk.Test()
 
-${eLower}, err := client.${eName}(nil).${cap(primaryOp)}(
-    ${testArg}, nil,
-)
-if err != nil {
-    panic(err)
-}
-fmt.Println(${eLower}) // the returned mock data
+${testModeExample}
 \`\`\`
 
 ### Use a custom fetch function

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

@@ -50,23 +50,41 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     ? '| `"apikey"` | `string` | API key for authentication. |\n'
     : ''
 
-  // First published entity name, for the Result shape illustration.
-  const firstEntityName = (entityList[0] as any)?.Name || 'Entity'
+  // Illustrate the Result shape with the first entity that ACTUALLY exposes an
+  // op — never fabricate a `Load` on an op-less first entity (e.g. Cloudsmith's
+  // `Abort`). firstPrimaryOp is null only when NO active entity has any op (a
+  // direct()-only SDK), in which case the call illustration is omitted.
+  const firstWithOp = entityList.find((e: any) => entityPrimaryOp(e) != null)
+  const firstPrimaryOp = firstWithOp ? entityPrimaryOp(firstWithOp) : null
+  const firstEntityName = firstWithOp ? ((firstWithOp as any).Name || 'Entity') : 'Entity'
   // camelCase Go identifier (never snake_case or flattened lowercase,
   // never a Go keyword).
-  const firstEntityVar = goVarName((entityList[0] as any)?.name || 'entity')
+  const firstEntityVar = goVarName((firstWithOp 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] || {})
-  // The example entity's PRIMARY op — an op it actually exposes (never a
-  // hardcoded `Load` a create-only entity lacks).
-  const firstPrimaryOp = entityList[0] ? (entityPrimaryOp(entityList[0]) || 'load') : 'load'
-  const firstPrimaryMethod = firstPrimaryOp.charAt(0).toUpperCase() + firstPrimaryOp.slice(1)
+  const firstIdF = firstWithOp ? entityIdField(firstWithOp) : null
+  const firstPrimaryMethod = firstPrimaryOp
+    ? firstPrimaryOp.charAt(0).toUpperCase() + firstPrimaryOp.slice(1)
+    : ''
   const firstIsMatchOp = 'load' === firstPrimaryOp || 'remove' === firstPrimaryOp
   const firstOpArg = firstIsMatchOp
     ? (firstIdF ? `map[string]any{"${firstIdF}": "example_id"}` : 'nil')
     : 'map[string]any{/* fields */}'
 
+  // The Result-shape call illustration, shown only when some entity exposes an
+  // op. A direct()-only SDK (no entity ops) omits it — there is no op to call.
+  const resultCallExample = firstPrimaryOp
+    ? `Check \`err\` first, then use the value directly (or the typed
+\`...Typed\` variants, which return the entity's model struct and a typed
+slice):
+
+    ${firstEntityVar}, err := client.${firstEntityName}(nil).${firstPrimaryMethod}(${firstOpArg}, nil)
+    if err != nil { /* handle */ }
+    // ${firstEntityVar} is the returned record
+
+`
+    : ''
+
   Content(`### New${model.const.Name}SDK
 
 \`\`\`go
@@ -130,15 +148,7 @@ operation's data **directly** — there is no wrapper:
 | --- | --- |
 ${resultShapeRows}
 
-Check \`err\` first, then use the value directly (or the typed
-\`...Typed\` variants, which return the entity's model struct and a typed
-slice):
-
-    ${firstEntityVar}, err := client.${firstEntityName}(nil).${firstPrimaryMethod}(${firstOpArg}, nil)
-    if err != nil { /* handle */ }
-    // ${firstEntityVar} is the returned record
-
-Only \`Direct()\` returns a response envelope — a \`map[string]any\` with
+${resultCallExample}Only \`Direct()\` returns a response envelope — a \`map[string]any\` with
 \`"ok"\`, \`"status"\`, \`"headers"\`, and \`"data"\` keys.
 
 `)

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

@@ -296,17 +296,17 @@ 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.
+            // request data (every required member appears, including a
+            // required id), each with a type-correct example VALUE via
+            // exampleValue — a `"name": /* type */` comment is not a value
+            // and yields uncompilable Go.
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
             Content(`\`\`\`go
 result, err := client.${ent.Name}(nil).Create(map[string]any{
 `)
             createItems.map((it: any) => {
-              Content(`    "${it.name}": /* ${canonToType(it.type, target.name)} */,
+              Content(`    "${it.name}": ${exampleValue(ent, ent.op && ent.op.create, it.name, 'example_' + it.name)},
 `)
             })
             Content(`}, nil)

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -30,18 +30,17 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   // Go module path == repo path on GitHub (org from model.origin).
   const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
-  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
 
   Content(`\`\`\`go
 client := sdk.Test()
 `)
 
-  if (exampleEntity) {
+  if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
-    // Drive the test-mode example off the entity's PRIMARY op (never a hardcoded
-    // `Load` a create-only entity lacks).
     const idF = entityIdField(exampleEntity)
-    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'nil'
     if (isMatchOp) {

package/project/.sdk/src/cmp/go/fragment/Entity.fragment.go

@@ -6,7 +6,7 @@ import (
 	vs "github.com/voxgig/struct"
 )
 
-type EntityNameEntity struct {
+type EntyClass struct {
 	name    string
 	client  *core.ProjectNameSDK
 	utility *core.Utility
@@ -16,7 +16,7 @@ type EntityNameEntity struct {
 	entctx  *core.Context
 }
 
-func NewEntityNameEntity(client *core.ProjectNameSDK, entopts map[string]any) *EntityNameEntity {
+func NewEntyClass(client *core.ProjectNameSDK, entopts map[string]any) *EntyClass {
 	if entopts == nil {
 		entopts = map[string]any{}
 	}
@@ -28,7 +28,7 @@ func NewEntityNameEntity(client *core.ProjectNameSDK, entopts map[string]any) *E
 		entopts["active"] = true
 	}
 
-	e := &EntityNameEntity{
+	e := &EntyClass{
 		name:    "entityname",
 		client:  client,
 		utility: client.GetUtility(),
@@ -47,17 +47,17 @@ func NewEntityNameEntity(client *core.ProjectNameSDK, entopts map[string]any) *E
 	return e
 }
 
-func (e *EntityNameEntity) GetName() string { return e.name }
+func (e *EntyClass) GetName() string { return e.name }
 
-func (e *EntityNameEntity) Make() core.Entity {
+func (e *EntyClass) Make() core.Entity {
 	opts := map[string]any{}
 	for k, v := range e.entopts {
 		opts[k] = v
 	}
-	return NewEntityNameEntity(e.client, opts)
+	return NewEntyClass(e.client, opts)
 }
 
-func (e *EntityNameEntity) Data(args ...any) any {
+func (e *EntyClass) Data(args ...any) any {
 	if len(args) > 0 && args[0] != nil {
 		e.data = core.ToMapAny(vs.Clone(args[0]))
 		if e.data == nil {
@@ -71,7 +71,7 @@ func (e *EntityNameEntity) Data(args ...any) any {
 	return out
 }
 
-func (e *EntityNameEntity) Match(args ...any) any {
+func (e *EntyClass) Match(args ...any) any {
 	if len(args) > 0 && args[0] != nil {
 		e.match = core.ToMapAny(vs.Clone(args[0]))
 		if e.match == nil {
@@ -89,7 +89,7 @@ func (e *EntityNameEntity) Match(args ...any) any {
 // argument it returns the current data as an EntityName; with an argument it
 // sets the data and returns the stored value. It delegates to the untyped Data
 // (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) DataTyped(data ...EntityName) EntityName {
+func (e *EntyClass) DataTyped(data ...EntityName) EntityName {
 	if len(data) > 0 {
 		return typedFrom[EntityName](e.Data(asMap(data[0])))
 	}
@@ -99,7 +99,7 @@ func (e *EntityNameEntity) DataTyped(data ...EntityName) EntityName {
 // MatchTyped mirrors DataTyped for the entity's match filter. The match is a
 // partial of the entity, so it round-trips through EntityName (all fields
 // optional at the wire level).
-func (e *EntityNameEntity) MatchTyped(match ...EntityName) EntityName {
+func (e *EntyClass) MatchTyped(match ...EntityName) EntityName {
 	if len(match) > 0 {
 		return typedFrom[EntityName](e.Match(asMap(match[0])))
 	}
@@ -116,7 +116,7 @@ func (e *EntityNameEntity) MatchTyped(match ...EntityName) EntityName {
 
 // #RemoveOp
 
-func (e *EntityNameEntity) runOp(ctx *core.Context, postDone func()) (any, error) {
+func (e *EntyClass) runOp(ctx *core.Context, postDone func()) (any, error) {
 	utility := e.utility
 
 	// #PrePoint-Hook

package/project/.sdk/src/cmp/go/fragment/EntityCreateOp.fragment.go

@@ -10,7 +10,7 @@ type entityCreateOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) Create(reqdata map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) Create(reqdata map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":  "create",
@@ -35,7 +35,7 @@ func (e *EntityNameEntity) Create(reqdata map[string]any, ctrl map[string]any) (
 // CreateTyped is the statically-typed variant of Create: it takes an
 // EntityNameCreateData and returns an EntityName. It delegates to the untyped
 // Create (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) CreateTyped(reqdata EntityNameCreateData, ctrl map[string]any) (EntityName, error) {
+func (e *EntyClass) CreateTyped(reqdata EntityNameCreateData, ctrl map[string]any) (EntityName, error) {
 	res, err := e.Create(asMap(reqdata), ctrl)
 	if err != nil {
 		return EntityName{}, err

package/project/.sdk/src/cmp/go/fragment/EntityListOp.fragment.go

@@ -4,7 +4,7 @@ type entityListOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) List(reqmatch map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) List(reqmatch map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":   "list",
@@ -26,7 +26,7 @@ func (e *EntityNameEntity) List(reqmatch map[string]any, ctrl map[string]any) (a
 // ListTyped is the statically-typed variant of List: it takes an
 // EntityNameListMatch and returns []EntityName. It delegates to the untyped
 // List (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) ListTyped(reqmatch EntityNameListMatch, ctrl map[string]any) ([]EntityName, error) {
+func (e *EntyClass) ListTyped(reqmatch EntityNameListMatch, ctrl map[string]any) ([]EntityName, error) {
 	res, err := e.List(asMap(reqmatch), ctrl)
 	if err != nil {
 		return nil, err

package/project/.sdk/src/cmp/go/fragment/EntityLoadOp.fragment.go

@@ -10,7 +10,7 @@ type entityLoadOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) Load(reqmatch map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) Load(reqmatch map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":   "load",
@@ -38,7 +38,7 @@ func (e *EntityNameEntity) Load(reqmatch map[string]any, ctrl map[string]any) (a
 // LoadTyped is the statically-typed variant of Load: it takes an
 // EntityNameLoadMatch and returns an EntityName. It delegates to the untyped
 // Load (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) LoadTyped(reqmatch EntityNameLoadMatch, ctrl map[string]any) (EntityName, error) {
+func (e *EntyClass) LoadTyped(reqmatch EntityNameLoadMatch, ctrl map[string]any) (EntityName, error) {
 	res, err := e.Load(asMap(reqmatch), ctrl)
 	if err != nil {
 		return EntityName{}, err

package/project/.sdk/src/cmp/go/fragment/EntityRemoveOp.fragment.go

@@ -10,7 +10,7 @@ type entityRemoveOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) Remove(reqmatch map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) Remove(reqmatch map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":   "remove",
@@ -38,7 +38,7 @@ func (e *EntityNameEntity) Remove(reqmatch map[string]any, ctrl map[string]any)
 // RemoveTyped is the statically-typed variant of Remove: it takes an
 // EntityNameRemoveMatch and returns an EntityName. It delegates to the untyped
 // Remove (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) RemoveTyped(reqmatch EntityNameRemoveMatch, ctrl map[string]any) (EntityName, error) {
+func (e *EntyClass) RemoveTyped(reqmatch EntityNameRemoveMatch, ctrl map[string]any) (EntityName, error) {
 	res, err := e.Remove(asMap(reqmatch), ctrl)
 	if err != nil {
 		return EntityName{}, err

package/project/.sdk/src/cmp/go/fragment/EntityUpdateOp.fragment.go

@@ -10,7 +10,7 @@ type entityUpdateOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) Update(reqdata map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) Update(reqdata map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":  "update",
@@ -38,7 +38,7 @@ func (e *EntityNameEntity) Update(reqdata map[string]any, ctrl map[string]any) (
 // UpdateTyped is the statically-typed variant of Update: it takes an
 // EntityNameUpdateData and returns an EntityName. It delegates to the untyped
 // Update (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) UpdateTyped(reqdata EntityNameUpdateData, ctrl map[string]any) (EntityName, error) {
+func (e *EntyClass) UpdateTyped(reqdata EntityNameUpdateData, ctrl map[string]any) (EntityName, error) {
 	res, err := e.Update(asMap(reqdata), ctrl)
 	if err != nil {
 		return EntityName{}, err

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

@@ -3,9 +3,15 @@ import * as Path from 'node:path'
 
 import {
   cmp, each, camelify, names,
-  File, Content, Folder, Fragment, Line, FeatureHook, Slot
+  File, Content, Folder, Fragment, Line, FeatureHook, Slot,
+  entityClassName,
 } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
 import { EntityOperation } from './EntityOperation_js'
 
 
@@ -13,6 +19,12 @@ const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
 
+  // Collision-free entity CLASS name (see entityClassName): normally
+  // `<Name>Entity`, disambiguated when it would clash with another entity's
+  // data-type name. The class file name and the Main require path both use this.
+  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const cls = entityClassName(entity, entityColl)
+
   const entrep = {
     ...stdrep,
   }
@@ -23,7 +35,7 @@ const Entity = cmp(function Entity(props: any) {
 
   Folder({ name: 'src/entity' }, () => {
 
-    File({ name: entity.Name + 'Entity.' + target.name }, () => {
+    File({ name: cls + '.' + target.name }, () => {
 
       const opnames = Object.keys(entity.op)
 
@@ -43,6 +55,10 @@ const Entity = cmp(function Entity(props: any) {
           SdkName: model.const.Name,
           EntityName: entity.Name,
 
+          // Class token decoupled from the EntityName data-type token in
+          // Entity.fragment.js so the class can be renamed independently.
+          EntyClass: cls,
+
           '#Feature-Hook': ({ name, indent }: any) =>
             Content({ indent }, `
 fres = featureHook(ctx, '${name}')

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

@@ -1,16 +1,26 @@
 
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
 
 
 const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
+  const { model } = props.ctx$
+
+  // Return the collision-free class (entityClassName); the accessor METHOD name
+  // (entity.Name) is unchanged so callers still write client.<Name>().
+  const cls = entityClassName(entity, getModelPath(model, `main.${KIT}.entity`))
 
   Content(`
   // Entity access: \`client.${entity.Name}().list()\` / \`client.${entity.Name}().load({ id })\`.
   ${entity.Name}(data) {
     const self = this
-    return new ${entity.Name}Entity(self,data)
+    return new ${cls}(self,data)
   }
 
 `)

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

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+  entityClassName,
 } from '@voxgig/sdkgen'
 
 
@@ -55,8 +56,10 @@ const Main = cmp(async function Main(props: any) {
 
       Line(`// ${model.const.Name} ${target.Name} SDK\n`)
 
-      List({ item: entity }, ({ item }: any) =>
-        Line(`const { ${item.Name}Entity } = require('./entity/${item.Name}Entity')`))
+      List({ item: entity }, ({ item }: any) => {
+        const cls = entityClassName(item, entity)
+        return Line(`const { ${cls} } = require('./entity/${cls}')`)
+      })
 
       Fragment(
         {

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

@@ -132,10 +132,10 @@ 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.
+      // (opRequestShape): every required member appears — including a
+      // required id and parent keys like page_id — each with a type-correct
+      // example VALUE via exampleValue — a `name: /* type */` comment is not
+      // a value and yields invalid code.
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -144,7 +144,7 @@ const ${eVar}s = await client.${entity.Name}().list()
 const ${eVar} = await client.${entity.Name}().create({
 `)
       createItems.map((it: any) => {
-        Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
+        Content(`  ${it.name}: ${exampleValue(entity, entity.op && entity.op.create, it.name, 'example_' + it.name)},
 `)
       })
       Content(`})

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,14 +14,14 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const exampleEntity = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
+  // only when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   const eVar = safeVarName(eName.toLowerCase(), 'js')
 
-  // Drive the test-mode / stateful examples off the entity's PRIMARY op — an op
-  // it actually exposes — never a hardcoded `load` a create-only entity lacks.
-  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
-  const primaryOpDef = exampleEntity && exampleEntity.op && exampleEntity.op[primaryOp]
+  const primaryOpDef = exampleEntity && primaryOp && exampleEntity.op && exampleEntity.op[primaryOp]
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   // idF is the MATCH key; dataIdF is the id on the RETURNED record's data type
   // (guard `.id` reads off a returned record on this, not the match key).
@@ -29,7 +29,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const dataIdF = exampleEntity ? entityDataIdField(exampleEntity) : null
 
   const primaryArg = (idPlaceholder: string): string => {
-    if (!exampleEntity) return ''
+    if (!exampleEntity || !primaryOp) return ''
     if ('list' === primaryOp) return ''
     if (isMatchOp) {
       return idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, idF, idPlaceholder)} }` : ''
@@ -48,6 +48,34 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     ? `console.log(data.${dataIdF})`
     : `console.log(data)`
 
+  // The op-driven example lines, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() test call instead
+  // and omits the stateful section (there is no op to retain state across).
+  const testModeExample = primaryOp
+    ? `const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
+// ${eVar} is a bare entity populated with mock response data
+console.log(${eVar})`
+    : `const result = await client.direct({ path: '/api/resource', method: 'GET' })
+console.log(result)`
+  const stateSection = primaryOp
+    ? `### Retain entity state across calls
+
+Entity instances remember their last match and data:
+
+\`\`\`js
+const entity = client.${eName}()
+
+// First call runs the operation and stores its result
+await entity.${primaryOp}(${stateCallArg})
+
+// Subsequent calls reuse the stored state
+const data = entity.data()
+${stateDataLine}
+\`\`\`
+
+`
+    : ''
+
   const authActive = isAuthActive(model)
   const apikeyTesterCtor = authActive
     ? `new ${model.const.Name}SDK({ apikey: '...' })`
@@ -97,9 +125,7 @@ Create a mock client for unit testing — no server required:
 \`\`\`js
 const client = ${model.const.Name}SDK.test()
 
-const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
-// ${eVar} is a bare entity populated with mock response data
-console.log(${eVar})
+${testModeExample}
 \`\`\`
 
 You can also use the instance method:
@@ -109,22 +135,7 @@ const client = ${apikeyTesterCtor}
 const testClient = client.tester()
 \`\`\`
 
-### Retain entity state across calls
-
-Entity instances remember their last match and data:
-
-\`\`\`js
-const entity = client.${eName}()
-
-// First call runs the operation and stores its result
-await entity.${primaryOp}(${stateCallArg})
-
-// Subsequent calls reuse the stored state
-const data = entity.data()
-${stateDataLine}
-\`\`\`
-
-### Add custom middleware
+${stateSection}### Add custom middleware
 
 Pass features via the \`extend\` option:
 

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

@@ -299,17 +299,17 @@ 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.
+            // (opRequestShape): every required member appears — including
+            // a required id and parent keys like page_id — each with a
+            // type-correct example VALUE via exampleValue — a
+            // `name: /* type */` comment is not a value and yields invalid code.
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().create({
 `)
             createItems.map((it: any) => {
-              Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
+              Content(`  ${it.name}: ${exampleValue(ent, ent.op && ent.op.create, it.name, 'example_' + it.name)},
 `)
             })
             Content(`})