@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -1,20 +1,61 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
+  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 {
+  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"'
+}
+
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  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
+  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) {
+    testArg = idF ? `map[string]any{"${idF}": "test01"}` : 'nil'
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === 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(', ')}}`
+  }
 
   const apikeyEnvLine = isAuthActive(model)
-    ? `\n${model.NAME}_APIKEY=<your-key>`
+    ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
 
   Content(`### Make a direct HTTP request
@@ -59,12 +100,15 @@ fmt.Println(fetchdef["headers"])
 Create a mock client for unit testing \u2014 no server required:
 
 \`\`\`go
-client := sdk.TestSDK(nil, nil)
+client := sdk.Test()
 
-result, err := client.Planet(nil).Load(
-    map[string]any{"id": "test01"}, nil,
+${eLower}, err := client.${eName}(nil).${cap(primaryOp)}(
+    ${testArg}, nil,
 )
-// result contains mock response data
+if err != nil {
+    panic(err)
+}
+fmt.Println(${eLower}) // the returned mock data
 \`\`\`
 
 ### Use a custom fetch function
@@ -96,7 +140,7 @@ client := sdk.New${model.const.Name}SDK(map[string]any{
 Create a \`.env.local\` file at the project root:
 
 \`\`\`
-${model.NAME}_TEST_LIVE=TRUE${apikeyEnvLine}
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
 \`\`\`
 
 Then run:

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, packageName, repoInfo } from '@voxgig/sdkgen'
 
 
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
@@ -7,17 +7,22 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   const { model } = ctx$
 
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  const gomodule = packageName(model, 'go')
+  const { releasesUrl } = repoInfo(model)
 
   Content(`\`\`\`bash
-go get ${gomodule}
+go get ${gomodule}@latest
 \`\`\`
 
-If the module is not yet published to a registry, use a \`replace\` directive
-in your \`go.mod\` to point to a local checkout:
+The Go module proxy resolves the version from the \`go/vX.Y.Z\` GitHub
+release tag — see [Releases](${releasesUrl}) 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
+\`go/\` directory:
 
 \`\`\`bash
-go mod edit -replace ${gomodule}=../path/to/${gomodule}
+go mod edit -replace ${gomodule}=../${model.name}-sdk/go
 \`\`\`
 
 `)

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

@@ -1,13 +1,52 @@
 
 import { cmp, Content } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  // Derive a real entity accessor from the model for the semantic-entity
+  // note (fall back to a generic name if the model has no entities).
+  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'
+
+  // Model-driven op list — only the operations the active entities actually
+  // 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 cap = (o: string) => o.charAt(0).toUpperCase() + o.slice(1)
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + cap(o) + '`').join(', ')
 
   Content(`# ${model.Name} ${target.title} SDK
 
-The ${target.title} SDK for the ${model.Name} API. Provides an entity-oriented interface using standard Go conventions — no generics required, data flows as \`map[string]any\`.
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client using standard Go conventions. No generics required; data flows as \`map[string]any\`.
+
+It exposes the API as capitalised, semantic **Entities** — e.g. \`client.${eName}(nil)\` — each with the same small set of operations (${opList}) instead of raw URL paths and query strings. You call meaning, not endpoints, which keeps the cognitive load low.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
 
 `)
 })

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

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content, isAuthActive } 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
@@ -13,13 +15,58 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
+  // Model-driven op rows for the shared entity interface: emit a
+  // Load/List/Create/Update/Remove row only for operations at least one active
+  // entity actually exposes (a read-only entity has just List+Load) — never
+  // document an operation no entity has. Model op keys are lowercase; Go
+  // method names are capitalised.
+  const opUnion = new Set<string>()
+  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. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
+  // Model-driven Result-shape rows: only describe the operations that
+  // actually exist. Record-returning ops (Load/Create/Update/Remove) share
+  // one row; List has its own — never name a missing op.
+  const recordOps = ['load', 'create', 'update', '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 |')
+  const resultShapeRows = resultRows.join('\n')
+
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
   const apikeyOptionRow = isAuthActive(model)
     ? '| `"apikey"` | `string` | API key for authentication. |\n'
     : ''
 
+  // First published entity name, for the Result shape illustration.
+  const firstEntityName = (entityList[0] as any)?.Name || 'Entity'
+  // 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] || {})
+  // 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 firstIsMatchOp = 'load' === firstPrimaryOp || 'remove' === firstPrimaryOp
+  const firstOpArg = firstIsMatchOp
+    ? (firstIdF ? `map[string]any{"${firstIdF}": "example_id"}` : 'nil')
+    : 'map[string]any{/* fields */}'
+
   Content(`### New${model.const.Name}SDK
 
 \`\`\`go
@@ -56,7 +103,8 @@ Creates a test-mode client with mock transport. Both arguments may be \`nil\`.
 `)
 
   each(entityList, (ent: any) => {
-    Content(`| \`${ent.Name}\` | \`(data map[string]any) ${model.const.Name}Entity\` | Create a ${ent.Name} entity instance. |
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${ent.Name}\` | \`(data map[string]any) ${model.const.Name}Entity\` | Create ${article} ${ent.Name} entity instance. |
 `)
   })
 
@@ -67,11 +115,7 @@ All entities implement the \`${model.const.Name}Entity\` interface.
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| \`Load\` | \`(reqmatch, ctrl map[string]any) (any, error)\` | Load a single entity by match criteria. |
-| \`List\` | \`(reqmatch, ctrl map[string]any) (any, error)\` | List entities matching the criteria. |
-| \`Create\` | \`(reqdata, ctrl map[string]any) (any, error)\` | Create a new entity. |
-| \`Update\` | \`(reqdata, ctrl map[string]any) (any, error)\` | Update an existing entity. |
-| \`Remove\` | \`(reqmatch, ctrl map[string]any) (any, error)\` | Remove an entity. |
+${opRows}
 | \`Data\` | \`(args ...any) any\` | Get or set entity data. |
 | \`Match\` | \`(args ...any) any\` | Get or set entity match criteria. |
 | \`Make\` | \`() Entity\` | Create a new instance with the same options. |
@@ -79,17 +123,23 @@ All entities implement the \`${model.const.Name}Entity\` interface.
 
 ### Result shape
 
-Entity operations return \`(any, error)\`. The \`any\` value is a
-\`map[string]any\` with these keys:
+Entity operations return \`(value, error)\`. The \`value\` is the
+operation's data **directly** — there is no wrapper:
 
-| Key | Type | Description |
-| --- | --- | --- |
-| \`"ok"\` | \`bool\` | \`true\` if the HTTP status is 2xx. |
-| \`"status"\` | \`int\` | HTTP status code. |
-| \`"headers"\` | \`map[string]any\` | Response headers. |
-| \`"data"\` | \`any\` | Parsed JSON response body. |
+| Operation | \`value\` |
+| --- | --- |
+${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
 
-On error, \`"ok"\` is \`false\` and \`"err"\` contains the error value.
+Only \`Direct()\` returns a response envelope — a \`map[string]any\` with
+\`"ok"\`, \`"status"\`, \`"headers"\`, and \`"data"\` keys.
 
 `)
 

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

@@ -1,12 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
 
 
 const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  const publishedOptions = each(target.options).filter((option: any) => option.publish)
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
   if (0 === publishedOptions.length) {
     return
   }
@@ -25,7 +26,7 @@ client := sdk.New${model.const.Name}SDK(map[string]any{
 
   publishedOptions.map((option: any) => {
     if ('apikey' === option.name) {
-      Content(`    "${option.name}": os.Getenv("${model.NAME}_APIKEY"),
+      Content(`    "${option.name}": os.Getenv("${envName(model)}_APIKEY"),
 `)
     }
     else {

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,157 +7,187 @@ 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
+// data itself — NOT a `{ok, data, ...}` envelope (only Direct returns
+// that). So examples check `err` and use the value directly. The whole
+// program is compiled by the README snippet test (readme_examples_test.go).
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
-  // Find the first published entity for examples
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  // Find a nested entity if available
-  const nestedEntity = Object.values(entity).find((e: any) =>
-    e.active !== false && e.ancestors && e.ancestors.length > 0
-  ) as any
-
   const authActive = isAuthActive(model)
-  const goImports = authActive
-    ? `    "fmt"\n    "os"\n`
-    : `    "fmt"\n`
-  const apikeyArg = authActive
-    ? `\n        "apikey": os.Getenv("${model.NAME}_APIKEY"),\n    `
-    : ''
+  const ctor = authActive
+    ? `sdk.New${model.const.Name}SDK(map[string]any{\n        "apikey": os.Getenv("${envName(model)}_APIKEY"),\n    })`
+    : `sdk.New()`
 
-  Content(`### 1. Create a client
-
-\`\`\`go
-package main
-
-import (
-${goImports}
-    sdk "${gomodule}"
-    "${gomodule}/core"
-)
-
-func main() {
-    client := sdk.New${model.const.Name}SDK(map[string]any{${apikeyArg}})
-\`\`\`
-
-`)
+  // Build the body of main() from the operations the example entity
+  // supports. Each op names a fresh value var, so `:=` always declares a
+  // new variable (reusing `err`), and every var is used (printed).
+  const body: string[] = []
+  let usesFmt = false
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const opnames = Object.keys(exampleEntity.op || {})
-
-    if (opnames.includes('list')) {
-      Content(`### 2. List ${eName.toLowerCase()}s
-
-\`\`\`go
-    result, err := client.${eName}(nil).List(nil, nil)
-    if err != nil {
-        panic(err)
+    // 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)
+
+    // 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 !== 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))
+        : 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)}`)
     }
 
-    rm := core.ToMapAny(result)
-    if rm["ok"] == true {
-        for _, item := range rm["data"].([]any) {
-            p := core.ToMapAny(item)
-            fmt.Println(p["id"], p["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'
     }
-\`\`\`
 
-`)
+    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(`    if err != nil {`)
+      body.push(`        panic(err)`)
+      body.push(`    }`)
+      body.push(`    for _, item := range ${eLower}s.([]any) {`)
+      body.push(`        fmt.Println(item)`)
+      body.push(`    }`)
+      body.push(``)
+      usesFmt = true
     }
 
-    if (nestedEntity && opnames.includes('load')) {
-      const neName = nom(nestedEntity, 'Name')
-      const parentFields = (nestedEntity.fields || [])
-        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
-      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
-
-      Content(`### 3. Load a ${neName.toLowerCase()}
-
-${neName} is nested under ${eName}, so provide the \`${parentParam}\`:
-
-\`\`\`go
-    ${neName.toLowerCase()} := client.${neName}(nil)
-    result, err = ${neName.toLowerCase()}.Load(
-        map[string]any{"${parentParam}": "example", "id": "example_id"}, nil,
-    )
-    if err != nil {
-        panic(err)
+    if (opnames.includes('load')) {
+      body.push(`    // Load a single ${eLower} — the value is the loaded 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(``)
+      usesFmt = true
     }
 
-    rm = core.ToMapAny(result)
-    if rm["ok"] == true {
-        fmt.Println(rm["data"])
+    if (opnames.includes('create')) {
+      body.push(`    // Create a ${eLower}.`)
+      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(`    }`)
+      body.push(`    fmt.Println(created)`)
+      body.push(``)
+      usesFmt = true
     }
-}
-\`\`\`
 
-`)
+    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{${updateMembers.join(', ')}}, nil)`)
+      body.push(`    if err != nil {`)
+      body.push(`        panic(err)`)
+      body.push(`    }`)
+      body.push(`    fmt.Println(updated)`)
+      body.push(``)
+      usesFmt = true
     }
-    else if (opnames.includes('load')) {
-      Content(`### 3. Load a ${eName.toLowerCase()}
 
-\`\`\`go
-    result, err = client.${eName}(nil).Load(
-        map[string]any{"id": "example_id"}, nil,
-    )
-    if err != nil {
-        panic(err)
+    if (opnames.includes('remove')) {
+      body.push(`    // Remove a ${eLower}.`)
+      body.push(`    removed, err := client.${eName}(nil).Remove(${matchArg('remove')}, nil)`)
+      body.push(`    if err != nil {`)
+      body.push(`        panic(err)`)
+      body.push(`    }`)
+      body.push(`    fmt.Println(removed)`)
+      body.push(``)
+      usesFmt = true
     }
+  }
 
-    rm = core.ToMapAny(result)
-    if rm["ok"] == true {
-        fmt.Println(rm["data"])
-    }
-}
-\`\`\`
+  // Drop trailing blank lines from the body.
+  while (body.length > 0 && body[body.length - 1] === '') {
+    body.pop()
+  }
 
-`)
-    }
+  const imports: string[] = []
+  if (usesFmt) imports.push(`    "fmt"`)
+  if (authActive) imports.push(`    "os"`)
+  imports.push(`    sdk "${gomodule}"`)
 
-    // CRUD operations
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
-      Content(`### 4. Create, update, and remove
+  let program = `package main
 
-\`\`\`go
-`)
-      if (opnames.includes('create')) {
-        Content(`// Create
-created, _ := client.${eName}(nil).Create(
-    map[string]any{"name": "Example"}, nil,
+import (
+${imports.join('\n')}
 )
-cm := core.ToMapAny(created)
-newID := core.ToMapAny(cm["data"])["id"]
 
-`)
-      }
-      if (opnames.includes('update')) {
-        Content(`// Update
-client.${eName}(nil).Update(
-    map[string]any{"id": newID, "name": "Example-Renamed"}, nil,
-)
+func main() {
+    client := ${ctor}
 
-`)
-      }
-      if (opnames.includes('remove')) {
-        Content(`// Remove
-client.${eName}(nil).Remove(
-    map[string]any{"id": newID}, nil,
-)
-`)
-      }
-      Content(`\`\`\`
+`
+  if (body.length > 0) {
+    program += body.join('\n') + '\n'
+  } else {
+    program += `    _ = client\n`
+  }
+  program += `}`
+
+  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.
+
+\`\`\`go
+${program}
+\`\`\`
 
 `)
-    }
-  }
 
 })