@voxgig/sdkgen 4.34.0 → 4.34.2

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

@@ -87,7 +87,7 @@ func prepareAuthUtil(ctx *core.Context) (*core.Spec, error) {
 import (
 ${withBasic ? `	"encoding/base64"
 
-` : ''}${'cookie' === spec.where ? `	"strings"
+` : ''}${'query' !== spec.where ? `	"strings"
 
 ` : ''}	vs "${spec.gomodule}/utility/struct"
 
@@ -100,6 +100,14 @@ ${'cookie' === spec.where ? `const cookieHeader = "cookie"
 ${withBasic ? `const optionSecret = "secret"
 ` : ''}const notFound = "__NOTFOUND__"
 
+// The client's auth.name option, when set, replaces the name the API declares.
+func authName(options map[string]any) string {
+	if name, ok := vs.GetPath(options, []any{"auth", "name"}).(string); ok && name != "" {
+		return ${caseFold(spec.where, 'name')}
+	}
+	return credName
+}
+
 ${cookieHelper(spec.where)}func prepareAuthUtil(ctx *core.Context) (*core.Spec, error) {
 	spec := ctx.Spec
 	if spec == nil {
@@ -112,10 +120,17 @@ ${cookieHelper(spec.where)}func prepareAuthUtil(ctx *core.Context) (*core.Spec,
 
 	// Public APIs that need no auth omit the options.auth block entirely.
 	if options["auth"] == nil {
-		${clear(spec.where)}
+		${clear(spec.where, 'credName')}
 		return spec, nil
 	}
 
+	name := authName(options)
+
+	// A credential left under the declared name would travel beside the renamed one.
+	if name != credName {
+		${clear(spec.where, 'credName')}
+	}
+
 	apikey := vs.GetProp(options, optionApikey, notFound)
 
 	skip := false
@@ -142,7 +157,7 @@ ${cookieHelper(spec.where)}func prepareAuthUtil(ctx *core.Context) (*core.Spec,
 		}
 
 		if skip {
-			${clear(spec.where)}
+			${clear(spec.where, 'name')}
 		} else {
 			apikeyVal, _ := apikey.(string)
 			b64 := base64.StdEncoding.EncodeToString([]byte(apikeyVal + ":" + secretVal))
@@ -156,9 +171,9 @@ ${cookieHelper(spec.where)}func prepareAuthUtil(ctx *core.Context) (*core.Spec,
 			}
 			// Empty prefix (raw apiKey credential) must not add a leading space.
 			if basicPrefix == "" {
-				${bagName(spec.where)}[credName] = b64
+				${bagName(spec.where)}[name] = b64
 			} else {
-				${bagName(spec.where)}[credName] = basicPrefix + " " + b64
+				${bagName(spec.where)}[name] = basicPrefix + " " + b64
 			}
 		}
 
@@ -168,9 +183,9 @@ ${cookieHelper(spec.where)}func prepareAuthUtil(ctx *core.Context) (*core.Spec,
 
   return head + basicBlock + `
 	if skip {
-		${clear(spec.where)}
+		${clear(spec.where, 'name')}
 	} else {
-${place(spec.where)}
+${place(spec.where, 'name')}
 	}
 
 	return spec, nil
@@ -196,14 +211,20 @@ function bagField(where: string): string {
 }
 
 
+// Header names travel lower-cased; query and cookie names are case-sensitive.
+function caseFold(where: string, expr: string): string {
+  return 'header' === where ? 'strings.ToLower(' + expr + ')' : expr
+}
+
+
 // A cookie has no header of its own: place() writes it into `cookie` as
-// `credName=value`, so clear() must free that slot, not credName.
-function clear(where: string): string {
+// `name=value`, so clear() frees that pair, not a header of that name.
+function clear(where: string, name: string): string {
   if ('cookie' === where) {
-    return `cookieSet(headers, nil)`
+    return `cookieSet(headers, ${name}, nil)`
   }
 
-  return `delete(${bagName(where)}, credName)`
+  return `delete(${bagName(where)}, ${name})`
 }
 
 
@@ -212,23 +233,16 @@ function cookieHelper(where: string): string {
     return ''
   }
 
-  return `func cookieSet(headers map[string]any, value any) {
+  return `func cookieSet(headers map[string]any, name string, value any) {
 	kept := []string{}
 
 	if existing, ok := headers[cookieHeader].(string); ok && existing != "" {
-		for _, part := range strings.Split(existing, ";") {
-			piece := strings.TrimSpace(part)
-			if piece == "" || piece == credName ||
-				strings.HasPrefix(piece, credName+"=") {
-				continue
-			}
-			kept = append(kept, piece)
-		}
+		kept = cookieKeep(existing, map[string]bool{name: true})
 	}
 
 	if value != nil {
 		valStr, _ := value.(string)
-		kept = append(kept, credName+"="+valStr)
+		kept = append(kept, name+"="+valStr)
 	}
 
 	if len(kept) == 0 {
@@ -242,13 +256,13 @@ function cookieHelper(where: string): string {
 }
 
 
-function place(where: string): string {
+function place(where: string, name: string): string {
   if ('query' === where) {
     return `		apikeyVal := ""
 		if av, ok := apikey.(string); ok {
 			apikeyVal = av
 		}
-		query[credName] = apikeyVal`
+		query[${name}] = apikeyVal`
   }
 
   if ('cookie' === where) {
@@ -256,7 +270,7 @@ function place(where: string): string {
 		if av, ok := apikey.(string); ok {
 			apikeyVal = av
 		}
-		cookieSet(headers, apikeyVal)`
+		cookieSet(headers, ${name}, apikeyVal)`
   }
 
   return `		authPrefix := ""
@@ -269,9 +283,9 @@ function place(where: string): string {
 		}
 		// Empty prefix (raw apiKey credential) must not add a leading space.
 		if authPrefix == "" {
-			headers[credName] = apikeyVal
+			headers[${name}] = apikeyVal
 		} else {
-			headers[credName] = authPrefix + " " + apikeyVal
+			headers[${name}] = authPrefix + " " + apikeyVal
 		}`
 }
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, entityOps, opRequestShape, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -17,6 +17,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'List(match, ctrl)',   desc: 'List entities matching the criteria.' },
   create: { method: 'Create(data, ctrl)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'Update(data, ctrl)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'Patch(data, ctrl)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'Remove(match, ctrl)', desc: 'Remove the matching entity.' },
 }
 
@@ -116,7 +117,7 @@ ${eVar}, err := client.${entity.Name}(nil).Load(${loadArg}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(${eVar}) // the loaded record
+fmt.Println(${eVar}.(sdk.Entity).Data()) // the loaded entity's record
 \`\`\`
 
 `)
@@ -126,11 +127,14 @@ fmt.Println(${eVar}) // the loaded record
       Content(`#### Example: List
 
 \`\`\`go
-${eVar}s, err := client.${entity.Name}(nil).List(nil, nil)
+${eVar}s, err := client.${entity.Name}(nil).List(${listMatchArg('go', entity)}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(${eVar}s) // the array of records
+// A []any of entities, one per record.
+for _, item := range ${eVar}s.([]any) {
+    fmt.Println(item.(sdk.Entity).Data())
+}
 \`\`\`
 
 `)
@@ -157,7 +161,7 @@ result, err := client.${entity.Name}(nil).Create(map[string]any{
 if err != nil {
     panic(err)
 }
-fmt.Println(result)
+fmt.Println(result.(sdk.Entity).Data()) // the created entity's record
 \`\`\`
 
 `)

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

@@ -31,6 +31,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"regexp"
 	"runtime"
 	"strconv"
 	"strings"
@@ -53,6 +54,10 @@ const testSeed = \`${goSeed}\`
 // seedRef is how a snippet names the shared fixture; seedFile declares it.
 const seedRef = "readmeTestSeed"
 
+// The client variable, not the word: an import path carries the word between
+// hyphens (github.com/voxgig-sdk/multifon-client-sdk/go).
+var clientVar = regexp.MustCompile(\`(^|[^\\w.\\-/"])client([^\\w\\-/"]|$)\`)
+
 func seedFile(pkg string) []byte {
 	return []byte("package " + pkg + "\\n\\nvar " + seedRef + " = " + testSeed + "\\n")
 }
@@ -524,7 +529,7 @@ func wrapFragment(name, block, modulePath string) string {
 	}
 
 	declaresClient := strings.Contains(block, "client :=")
-	injectClient := !declaresClient && strings.Contains(block, "client")
+	injectClient := !declaresClient && clientVar.MatchString(block)
 
 	needSdk := injectClient || strings.Contains(block, "sdk.")
 	usesFmt := strings.Contains(block, "fmt.")

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

@@ -14,7 +14,9 @@ The Go SDK uses \`map[string]any\` throughout rather than typed structs.
 This mirrors the dynamic nature of the API and keeps the SDK
 flexible \u2014 no code generation is needed when the API schema changes.
 
-Use \`core.ToMapAny()\` to safely cast results and nested data.
+An operation returns the entity, and its \`Data()\` returns the record. Use
+\`core.ToMapAny()\` to safely cast that record, or data nested in it, to
+\`map[string]any\`: it returns \`nil\` for anything else, an entity included.
 
 ### Package structure
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, goModule } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, goModule, requiredItems, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -12,6 +12,7 @@ import { goVarName } from './utility_go'
 
 function goLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '[]any{}'
@@ -41,32 +42,43 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'nil'
-  if (exampleEntity && isMatchOp) {
-    const items = opRequestShape(exampleEntity, primaryOp).items
-      .filter((it: any) => !it.optional || it.name === idF)
+  if (exampleEntity && (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length))) {
+    const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => !it.optional || it.name === idF) : requiredItems(exampleEntity, 'list'))
       .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
     testArg = 0 < items.length
-      ? `map[string]any{${items.map((it: any) => `"${it.name}": ${it.name === idF ? '"test01"' : goLit(it.type)}`).join(', ')}}`
+      ? `map[string]any{${items.map((it: any) => litPair('go', it.name, isMatchOp && it.name === idF ? '"test01"' : goLit(it.type))).join(', ')}}`
       : 'nil'
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)
     const chosen = required.length ? required : items.slice(0, 3)
-    testArg = `map[string]any{${chosen.map((it: any) => `"${it.name}": ${goLit(it.type)}`).join(', ')}}`
+    testArg = `map[string]any{${chosen.map((it: any) => litPair('go', 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
+  const testModeExample = 'list' === primaryOp
+    ? `${eLower}s, err := client.${eName}(nil).List(
+    ${testArg}, nil,
+)
+if err != nil {
+    panic(err)
+}
+// A []any of entities, one per mock record.
+for _, item := range ${eLower}s.([]any) {
+    fmt.Println(item.(sdk.Entity).Data())
+}`
+    : primaryOp
     ? `${eLower}, err := client.${eName}(nil).${cap(primaryOp)}(
     ${testArg}, nil,
 )
 if err != nil {
     panic(err)
 }
-fmt.Println(${eLower}) // the returned mock data`
+fmt.Println(${eLower}.(sdk.Entity).Data()) // the entity's mock record`
     : `result, err := client.Direct(map[string]any{"path": "/api/resource", "method": "GET"})
 if err != nil {
     panic(err)

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

@@ -10,14 +10,14 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   const gomodule = packageName(model, target.name)
   // `repo` is the directory a `git clone` of this project creates — not
   // `<slug>-sdk`, which is only the DEFAULT repo name.
-  const { releasesUrl, repo } = repoInfo(model)
+  const { hostName, tagsUrl, repo } = repoInfo(model)
 
   Content(`\`\`\`bash
 go get ${gomodule}@latest
 \`\`\`
 
-The Go module proxy resolves the version from the \`go/vX.Y.Z\` GitHub
-release tag — see [Releases](${releasesUrl}) for the available versions.
+The Go module proxy resolves the version from the \`go/vX.Y.Z\` ${hostName}
+release tag — see [Tags](${tagsUrl}) for the available versions.
 
 To vendor from a local checkout instead, clone this repo alongside your
 project and add a \`replace\` directive pointing at the checked-out

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,7 +10,7 @@ import {
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
-  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const info = modelText(model)
   const tagline = info.tagline || ''
 
   // Derive a real entity accessor from the model for the semantic-entity
@@ -23,7 +23,7 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   // expose (a read-only entity has just List+Load); never claim
   // Create/Update/Remove exist when no entity has them. Go method names are
   // capitalised, so present the ops that way.
-  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const cap = (o: string) => o.charAt(0).toUpperCase() + o.slice(1)
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, entityIdField, entityPrimaryOp, goModule } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, entityIdField, entityPrimaryOp, goModule, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -24,20 +24,21 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
   const opRowDefs: Record<string, string> = {
-    load: '| `Load` | `(reqmatch, ctrl map[string]any) (any, error)` | Load a single entity by match criteria. |',
-    list: '| `List` | `(reqmatch, ctrl map[string]any) (any, error)` | List entities matching the criteria. |',
-    create: '| `Create` | `(reqdata, ctrl map[string]any) (any, error)` | Create a new entity. |',
-    update: '| `Update` | `(reqdata, ctrl map[string]any) (any, error)` | Update an existing entity. |',
-    remove: '| `Remove` | `(reqmatch, ctrl map[string]any) (any, error)` | Remove an entity. |',
+    load: '| `Load` | `(reqmatch, ctrl map[string]any) (any, error)` | Load a single entity by match criteria, and return it. |',
+    list: '| `List` | `(reqmatch, ctrl map[string]any) (any, error)` | List entities matching the criteria, one per record. |',
+    create: '| `Create` | `(reqdata, ctrl map[string]any) (any, error)` | Create a new entity, and return it. |',
+    update: '| `Update` | `(reqdata, ctrl map[string]any) (any, error)` | Update an existing entity, and return it. |',
+    patch: '| `Patch` | `(reqdata, ctrl map[string]any) (any, error)` | Change part of an existing entity, and return it. |',
+    remove: '| `Remove` | `(reqmatch, ctrl map[string]any) (any, error)` | Remove an entity, and return it marked as deleted. |',
   }
-  const opRows = ['load', 'list', 'create', 'update', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
-  const recordOps = ['load', 'create', 'update', 'remove'].filter((o) => opUnion.has(o))
+  const recordOps = ['load', 'create', 'update', 'patch', 'remove'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o.charAt(0).toUpperCase() + o.slice(1) + '`')
   const resultRows: string[] = []
-  if (recordOps.length) resultRows.push('| ' + recordOps.join(' / ') + ' | the entity record (`map[string]any`) |')
-  if (opUnion.has('list')) resultRows.push('| `List` | a `[]any` of entity records |')
+  if (recordOps.length) resultRows.push('| ' + recordOps.join(' / ') + ' | the entity, whose `Data()` reads its record (`map[string]any`) |')
+  if (opUnion.has('list')) resultRows.push('| `List` | a `[]any` of entities, one per record |')
   const resultShapeRows = resultRows.join('\n')
 
   const gomodule = goModule(model, target.name)
@@ -61,7 +62,8 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const firstIsMatchOp = 'load' === firstPrimaryOp || 'remove' === firstPrimaryOp
   const firstOpArg = firstIsMatchOp
     ? (firstIdF ? `map[string]any{"${firstIdF}": "example_id"}` : 'nil')
-    : 'map[string]any{/* fields */}'
+    : 'list' === firstPrimaryOp ? listMatchArg('go', firstWithOp)
+      : 'map[string]any{/* fields */}'
 
   const resultCallExample = firstPrimaryOp
     ? `Check \`err\` first, then use the value directly (or the typed
@@ -70,7 +72,9 @@ slice):
 
     ${firstEntityVar}, err := client.${firstEntityName}(nil).${firstPrimaryMethod}(${firstOpArg}, nil)
     if err != nil { /* handle */ }
-    // ${firstEntityVar} is the returned record
+    // ${'list' === firstPrimaryOp
+    ? `${firstEntityVar} is a []any of entities, one per record`
+    : `${firstEntityVar} is the entity; ${firstEntityVar}.(sdk.Entity).Data() reads its record`}
 
 `
     : ''
@@ -131,8 +135,8 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return \`(value, error)\`. The \`value\` is the
-operation's data **directly** — there is no wrapper:
+Entity operations return \`(value, error)\`. The \`value\` is the entity
+itself — there is no wrapper:
 
 | Operation | \`value\` |
 | --- | --- |

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps, goModule , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps, goModule, serverVariables, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -80,25 +80,25 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     }
 
     if (opnames.includes('list')) {
-      body.push(`    // List ${eLower} records — the value is the array of records itself.`)
-      body.push(`    ${eLower}s, err := client.${eName}(nil).List(nil, nil)`)
+      body.push(`    // List ${eLower} records — the value is a []any of entities, one per record.`)
+      body.push(`    ${eLower}s, err := client.${eName}(nil).List(${listMatchArg('go', exampleEntity)}, nil)`)
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
       body.push(`    for _, item := range ${eLower}s.([]any) {`)
-      body.push(`        fmt.Println(item)`)
+      body.push(`        fmt.Println(item.(sdk.Entity).Data())`)
       body.push(`    }`)
       body.push(``)
       usesFmt = true
     }
 
     if (opnames.includes('load')) {
-      body.push(`    // Load a single ${eLower} — the value is the loaded record.`)
+      body.push(`    // Load a single ${eLower} — the value is the entity; Data() reads its record.`)
       body.push(`    ${eLower}, err := client.${eName}(nil).Load(${matchArg('load')}, nil)`)
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(${eLower})`)
+      body.push(`    fmt.Println(${eLower}.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -109,7 +109,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(created)`)
+      body.push(`    fmt.Println(created.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -125,7 +125,21 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(updated)`)
+      body.push(`    fmt.Println(updated.(sdk.Entity).Data())`)
+      body.push(``)
+      usesFmt = true
+    }
+
+    if (opnames.includes('patch')) {
+      const patchMembers = (idF
+        ? [`"${idF}": ${exampleValue(exampleEntity, exampleEntity.op.patch, idF, 'example_id')}`]
+        : []).concat(exampleFields('patch'))
+      body.push(`    // Patch a ${eLower}: only the fields given are sent.`)
+      body.push(`    patched, err := client.${eName}(nil).Patch(map[string]any{${patchMembers.join(', ')}}, nil)`)
+      body.push(`    if err != nil {`)
+      body.push(`        panic(err)`)
+      body.push(`    }`)
+      body.push(`    fmt.Println(patched.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -136,7 +150,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       body.push(`    if err != nil {`)
       body.push(`        panic(err)`)
       body.push(`    }`)
-      body.push(`    fmt.Println(removed)`)
+      body.push(`    fmt.Println(removed.(sdk.Entity).Data())`)
       body.push(``)
       usesFmt = true
     }
@@ -171,9 +185,10 @@ func main() {
   Content(`### Quickstart
 
 A complete program: create a client, then call the entity operations.
-Each operation returns \`(value, error)\` — the value is the data itself
-(there is no \`{ok, data}\` wrapper), so check \`err\` and use the value
-directly.
+Each operation returns \`(value, error)\` — the value is the entity, and for
+\`List\` a \`[]any\` of entities, one per record (there is no \`{ok, data}\`
+wrapper), so check \`err\` and read a record through the entity's
+\`Data()\`.
 
 \`\`\`go
 ${program}

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, entityOps, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, entityOps, opRequestShape, targetFeatures, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -14,27 +14,32 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   load: {
     sig: 'Load(reqmatch, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'Load a single entity matching the given criteria.',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `Data()` reads; `err` is non-nil on failure.',
   },
   list: {
     sig: 'List(reqmatch, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    desc: 'List entities matching the given criteria. Returns a `[]any` of entities, one per record; `err` is non-nil on failure.',
   },
   create: {
     sig: 'Create(reqdata, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'Create a new entity with the given data.',
+    desc: 'Create a new entity with the given data. Returns the created entity; `err` is non-nil on failure.',
   },
   update: {
     sig: 'Update(reqdata, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity; `err` is non-nil on failure.',
+  },
+  patch: {
+    sig: 'Patch(reqdata, ctrl map[string]any) (any, error)',
+    returns: '(any, error)',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity; `err` is non-nil on failure.',
   },
   remove: {
     sig: 'Remove(reqmatch, ctrl map[string]any) (any, error)',
     returns: '(any, error)',
-    desc: 'Remove the entity matching the given criteria.',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted; `err` is non-nil on failure.',
   },
 }
 
@@ -210,7 +215,7 @@ fmt.Println(${eVar}.GetName()) // "${ent.name}"
           // Only emit columns for operations this entity actually exposes —
           // never advertise a create/update/remove column the entity lacks
           // (opnames already carries active ops only).
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op))
           Content(`### Field Usage by Operation
 
@@ -272,18 +277,20 @@ result, err := client.${ent.Name}(nil).${goOpName}(${arg}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(result)
+fmt.Println(result.(sdk.Entity).Data())
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`go
-results, err := client.${ent.Name}(nil).List(nil, nil)
+results, err := client.${ent.Name}(nil).List(${listMatchArg('go', ent)}, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(results)
+for _, item := range results.([]any) {
+    fmt.Println(item.(sdk.Entity).Data())
+}
 \`\`\`
 
 `)
@@ -307,34 +314,42 @@ result, err := client.${ent.Name}(nil).Create(map[string]any{
 if err != nil {
     panic(err)
 }
-fmt.Println(result)
+fmt.Println(result.(sdk.Entity).Data())
 \`\`\`
 
 `)
           }
-          else if ('update' === opname) {
+          else if ('update' === opname || 'patch' === opname) {
             // 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
+            const updateItems = 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 updateLines = updateItems.map((it: any) =>
-              `    "${it.name}": ${exampleValue(ent, ent.op && ent.op.update, it.name,
+              `    "${it.name}": ${exampleValue(ent, ent.op && ent.op[opname], it.name,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`go
-result, err := client.${ent.Name}(nil).Update(map[string]any{
-${updateLines}    // Fields to update
+result, err := client.${ent.Name}(nil).${'patch' === opname ? 'Patch' : 'Update'}(map[string]any{
+${updateLines}    // ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 }, nil)
 if err != nil {
     panic(err)
 }
-fmt.Println(result)
+fmt.Println(result.(sdk.Entity).Data())
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a `[]byte`, a `string` or an `io.Reader`',
+              once: 'an `io.Reader`',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 
@@ -356,6 +371,14 @@ Get or set the entity match criteria. Works the same as \`Data()\`.
 Create a new \`${ent.Name}Entity\` instance with the same client and
 options.
 
+#### \`Stream(action string, args map[string]any, callopts map[string]any) <-chan StreamItem\`
+
+Run an operation through the pipeline and send its result items on the
+returned channel, which closes when the stream ends. A \`StreamItem\` holds
+one item in \`Item\`, or in \`Err\` the error that ended the stream: the
+error the operation itself would return, sent as the last value. Under
+\`throw: false\` in \`callopts["ctrl"]\`, no error is sent.
+
 #### \`GetName() string\`
 
 Return the entity name.