@voxgig/sdkgen 1.2.0 → 1.3.1

package/project/.sdk/src/cmp/py/ReadmeHowto_py.ts

@@ -1,12 +1,50 @@
 
-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'
+
+
+// A type-correct Python literal for a field's canonical type.
+function pyLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'True'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return '"example"'
+}
 
 
 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
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+  // Model-driven id key: null when the entity has no id-like field, so a
+  // match op takes no argument.
+  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 = ''
+  if (exampleEntity && isMatchOp) {
+    testArg = idF ? `{"${idF}": "test01"}` : ''
+  } 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 = `{${chosen.map((it: any) => `"${it.name}": ${pyLit(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
@@ -14,29 +52,31 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
 For endpoints not covered by entity methods:
 
 \`\`\`python
-result, err = client.direct({
+result = client.direct({
     "path": "/api/resource/{id}",
     "method": "GET",
     "params": {"id": "example"},
 })
-if err:
-    raise Exception(err)
 
 if result["ok"]:
     print(result["status"])  # 200
     print(result["data"])    # response body
+else:
+    # A non-2xx response carries status + data (the error body); a
+    # transport-level failure carries err instead. Only one is present, so
+    # read both with .get() rather than indexing a key that may be absent.
+    print(result.get("status"), result.get("err"))
 \`\`\`
 
 ### Prepare a request without sending it
 
 \`\`\`python
-fetchdef, err = client.prepare({
+# prepare() returns the fetch definition and raises on error.
+fetchdef = client.prepare({
     "path": "/api/resource/{id}",
     "method": "DELETE",
     "params": {"id": "example"},
 })
-if err:
-    raise Exception(err)
 
 print(fetchdef["url"])
 print(fetchdef["method"])
@@ -48,12 +88,11 @@ print(fetchdef["headers"])
 Create a mock client for unit testing — no server required:
 
 \`\`\`python
-client = ${model.const.Name}SDK.test(None, None)
+client = ${model.const.Name}SDK.test()
 
-result, err = client.${model.const.Name}(None).load(
-    {"id": "test01"}, None
-)
-# result contains mock response data
+# Entity ops return the bare record and raise on error.
+${eName.toLowerCase()} = client.${eName}().${primaryOp}(${testArg})
+# ${eName.toLowerCase()} contains the mock response record
 \`\`\`
 
 ### Use a custom fetch function
@@ -82,7 +121,7 @@ client = ${model.const.Name}SDK({
 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/py/ReadmeInstall_py.ts

@@ -1,13 +1,14 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
 
 
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
-  Content(`\`\`\`bash
-pip install ${model.name}-sdk
+  if (isPublished(model, target.name)) {
+    Content(`\`\`\`bash
+${installCommand(model, target.name)}
 \`\`\`
 
 Or install from source:
@@ -16,6 +17,21 @@ Or install from source:
 pip install -e .
 \`\`\`
 
+`)
+    return
+  }
+
+  // Publish pending: not yet on PyPI. Install from the git release tag or
+  // from a local source checkout.
+  const { releasesUrl } = repoInfo(model)
+  Content(`This package is not yet published to PyPI. Install it from the GitHub
+release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) or
+from a source checkout:
+
+\`\`\`bash
+pip install -e .
+\`\`\`
+
 `)
 })
 

package/project/.sdk/src/cmp/py/ReadmeIntro_py.ts

@@ -1,13 +1,60 @@
 
 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 || ''
 
   Content(`# ${model.Name} ${target.title} SDK
 
-The ${target.title} SDK for the ${model.Name} API. Provides an entity-oriented interface following Pythonic conventions.
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client following Pythonic conventions.
+
+`)
+
+  // Emphasise the entity-oriented design: the SDK surfaces the API as
+  // capitalised, semantic Entities with a small, uniform verb set rather
+  // than raw URL paths and query strings. The example entity name is
+  // derived from the model, never hardcoded.
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {})
+    .find((e: any) => e.active !== false) as any
+  const example = exampleEntity
+    ? `for example \`client.${nom(exampleEntity, 'Name')}()\` — each`
+    : 'each'
+
+  // 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.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  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) => '`' + o + '`').join(', ')
+
+  Content(`The SDK exposes the API as capitalised, semantic **Entities** — ${example}
+carrying a small, uniform set of operations (${opList}) instead of raw URL
+paths and query strings. You work with named resources and verbs, 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/py/ReadmeModel_py.ts

@@ -13,6 +13,23 @@ 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.
+  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) -> any` | Load a single entity by match criteria. Raises on error. |',
+    list: '| `list` | `(reqmatch, ctrl) -> list` | List entities matching the criteria. Raises on error. |',
+    create: '| `create` | `(reqdata, ctrl) -> any` | Create a new entity. Raises on error. |',
+    update: '| `update` | `(reqdata, ctrl) -> any` | Update an existing entity. Raises on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> any` | Remove an entity. Raises on error. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
   const apikeyOptionRow = isAuthActive(model)
     ? '| `apikey` | `str` | API key for authentication. |\n'
     : ''
@@ -50,12 +67,13 @@ Creates a test-mode client with mock transport. Both arguments may be \`None\`.
 | --- | --- | --- |
 | \`options_map\` | \`() -> dict\` | Deep copy of current SDK options. |
 | \`get_utility\` | \`() -> Utility\` | Copy of the SDK utility object. |
-| \`prepare\` | \`(fetchargs) -> (dict, err)\` | Build an HTTP request definition without sending. |
-| \`direct\` | \`(fetchargs) -> (dict, err)\` | Build and send an HTTP request. |
+| \`prepare\` | \`(fetchargs) -> dict\` | Build an HTTP request definition without sending. Raises on error. |
+| \`direct\` | \`(fetchargs) -> dict\` | Build and send an HTTP request. Returns a result dict (branch on \`ok\`). |
 `)
 
   each(entityList, (ent: any) => {
-    Content(`| \`${ent.Name}\` | \`(data) -> ${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${ent.Name}\` | \`(data) -> ${ent.Name}Entity\` | Create ${article} ${ent.Name} entity instance. |
 `)
   })
 
@@ -66,11 +84,7 @@ All entities share the same interface.
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| \`load\` | \`(reqmatch, ctrl) -> (any, err)\` | Load a single entity by match criteria. |
-| \`list\` | \`(reqmatch, ctrl) -> (any, err)\` | List entities matching the criteria. |
-| \`create\` | \`(reqdata, ctrl) -> (any, err)\` | Create a new entity. |
-| \`update\` | \`(reqdata, ctrl) -> (any, err)\` | Update an existing entity. |
-| \`remove\` | \`(reqmatch, ctrl) -> (any, err)\` | Remove an entity. |
+${opRows}
 | \`data_get\` | \`() -> dict\` | Get entity data. |
 | \`data_set\` | \`(data)\` | Set entity data. |
 | \`match_get\` | \`() -> dict\` | Get entity match criteria. |
@@ -80,8 +94,12 @@ All entities share the same interface.
 
 ### Result shape
 
-Entity operations return \`(any, err)\`. The first value is a
-\`dict\` with these keys:
+Entity operations return the bare result data (a \`dict\` for single-entity
+ops, a \`list\` for \`list\`) and raise on error. Wrap calls in
+\`try\`/\`except\` to handle failures.
+
+The \`direct()\` escape hatch never raises — it returns a result \`dict\`
+you branch on via \`result["ok"]\`:
 
 | Key | Type | Description |
 | --- | --- | --- |

package/project/.sdk/src/cmp/py/ReadmeOptions_py.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 = ${model.Name}SDK({
 
   publishedOptions.map((option: any) => {
     if ('apikey' === option.name) {
-      Content(`    "${option.name}": os.environ.get("${model.NAME}_APIKEY"),
+      Content(`    "${option.name}": os.environ.get("${envName(model)}_APIKEY"),
 `)
     }
     else {

package/project/.sdk/src/cmp/py/ReadmeQuick_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -20,74 +20,123 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const authActive = isAuthActive(model)
   const apikeyImport = authActive ? `import os\n` : ''
-  const apikeyArg = authActive
-    ? `\n    "apikey": os.environ.get("${model.NAME}_APIKEY"),\n`
-    : ''
+  const ctor = authActive
+    ? `${model.const.Name}SDK({\n    "apikey": os.environ.get("${envName(model)}_APIKEY"),\n})`
+    : `${model.const.Name}SDK()`
 
   Content(`### 1. Create a client
 
 \`\`\`python
 ${apikeyImport}from ${model.const.Name.toLowerCase()}_sdk import ${model.const.Name}SDK
 
-client = ${model.const.Name}SDK({${apikeyArg}})
+client = ${ctor}
 \`\`\`
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
     const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: `idF` is the entity's id-like MATCH field name, or
+    // null when it has none (a response-wrapped spec). `dataIdF` is the id on
+    // the RETURNED record's data type — an entity can key its match on an id it
+    // does not carry as data, so indexing `created["id"]` when the data type has
+    // none is wrong (and would KeyError at runtime).
+    const idF = entityIdField(exampleEntity)
+    const dataIdF = entityDataIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`### 2. List ${eName.toLowerCase()}s
+      Content(`### 2. List ${eName.toLowerCase()} records
+
+\`list()\` returns a \`list\` of records (each a \`dict\`) and raises on
+error — iterate it directly.
 
 \`\`\`python
-result, err = client.${eName}(None).list(None, None)
-if err:
-    raise Exception(err)
-
-if isinstance(result, list):
-    for item in result:
-        d = item.data_get()
-        print(d["id"], d["name"])
+try:
+    ${eName.toLowerCase()}s = client.${eName}().list()
+    for ${eName.toLowerCase()} in ${eName.toLowerCase()}s:
+        print(${eName.toLowerCase()})
+except Exception as err:
+    print(f"list failed: {err}")
 \`\`\`
 
 `)
     }
 
     if (opnames.includes('load')) {
-      Content(`### 3. Load a ${eName.toLowerCase()}
+      Content(`### 3. Load ${article} ${eName.toLowerCase()}
+
+\`load()\` returns the bare record (a \`dict\`) and raises on error.
 
 \`\`\`python
-result, err = client.${eName}(None).load({"id": "example_id"}, None)
-if err:
-    raise Exception(err)
-print(result)
+try:
+    ${eName.toLowerCase()} = client.${eName}().load(${idF ? `{"${idF}": "example_id"}` : ''})
+    print(${eName.toLowerCase()})
+except Exception as err:
+    print(f"load failed: {err}")
 \`\`\`
 
 `)
     }
 
+    // Model-driven example fields: derive the create/update body from the op
+    // shape (opRequestShape) so the docs reference REAL writable fields, not a
+    // hardcoded "name" the entity may not have. Literals are Python-typed by
+    // the field's canonical type.
+    const idField = (exampleEntity.id && exampleEntity.id.field) || 'id'
+    const pyLit = (type: any): string => {
+      const k = canonKey(type)
+      if ('INTEGER' === k || 'NUMBER' === k) return '1'
+      if ('BOOLEAN' === k) return 'True'
+      if ('ARRAY' === k) return '[]'
+      if ('OBJECT' === k) return '{}'
+      return '"example"'
+    }
+    const examplePairs = (opname: string): string[] => {
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => it.name !== idField && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      // create needs ALL required fields; update is a patch, so a couple suffice.
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : items.slice(0, 2)
+      return chosen.map((it: any) => `"${it.name}": ${pyLit(it.type)}`)
+    }
+
+    // The id VALUE for an update/remove match: taken off the returned `created`
+    // record only when its data type carries the id AND a create ran; otherwise
+    // a type-correct literal.
+    const idParamType = (opname: string): any => {
+      const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
+      return it && it.type
+    }
+    const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
+      ? `created["${dataIdF}"]`
+      : pyLit(idParamType(opname))
+
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`python
 `)
       if (opnames.includes('create')) {
-        Content(`# Create
-created, _ = client.${eName}(None).create({"name": "Example"}, None)
+        Content(`# Create — returns the bare created record (a dict)
+created = client.${eName}().create({${examplePairs('create').join(', ')}})
 
 `)
       }
       if (opnames.includes('update')) {
-        Content(`# Update
-client.${eName}(None).update({"id": created["id"], "name": "Example-Renamed"}, None)
+        const updatePairs = (idF ? [`"${idF}": ${idValueFor('update')}`] : []).concat(examplePairs('update'))
+        const fromCreated = null != dataIdF && opnames.includes('create')
+        Content(`# Update${fromCreated ? " — the created record's id is a plain dict key" : ''}
+client.${eName}().update({${updatePairs.join(', ')}})
 
 `)
       }
       if (opnames.includes('remove')) {
         Content(`# Remove
-client.${eName}(None).remove({"id": created["id"]}, None)
+client.${eName}().remove(${idF ? `{"${idF}": ${idValueFor('remove')}}` : ''})
 `)
       }
       Content(`\`\`\`

package/project/.sdk/src/cmp/py/ReadmeRef_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,31 +7,43 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, JSON-serialisable Python literal — never an Ellipsis (`...`),
+// which is not JSON-serialisable when a create body is executed by the doc test.
+function pyLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'True'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return '"example"'
+}
+
+
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'load(reqmatch, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'Load a single entity matching the given criteria.',
+    sig: 'load(reqmatch, ctrl=None) -> dict',
+    returns: 'the entity data',
+    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
   },
   list: {
-    sig: 'list(reqmatch, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    sig: 'list(reqmatch=None, ctrl=None) -> list',
+    returns: 'a list of entities',
+    desc: 'List entities matching the given criteria. The match is optional — call `list()` with no argument to list all records. Returns a list and raises on error.',
   },
   create: {
-    sig: 'create(reqdata, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'Create a new entity with the given data.',
+    sig: 'create(reqdata, ctrl=None) -> dict',
+    returns: 'the created entity data',
+    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
   },
   update: {
-    sig: 'update(reqdata, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    sig: 'update(reqdata, ctrl=None) -> dict',
+    returns: 'the updated entity data',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
   },
   remove: {
-    sig: 'remove(reqmatch, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'Remove the entity matching the given criteria.',
+    sig: 'remove(reqmatch, ctrl=None) -> dict',
+    returns: 'the removed entity data',
+    desc: 'Remove the entity matching the given criteria. Raises on error.',
   },
 }
 
@@ -60,7 +72,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
 `)
 
     Content(`\`\`\`python
-from ${model.name}_sdk import ${model.const.Name}SDK
+from ${model.const.Name.toLowerCase()}_sdk import ${model.const.Name}SDK
 
 client = ${model.const.Name}SDK(options)
 \`\`\`
@@ -72,8 +84,7 @@ Create a new SDK client instance.
 | Name | Type | Description |
 | --- | --- | --- |
 | \`options\` | \`dict\` | SDK configuration options. |
-| \`options["apikey"]\` | \`str\` | API key for authentication. |
-| \`options["base"]\` | \`str\` | Base URL for API requests. |
+${isAuthActive(model) ? '| \`options["apikey"]\` | \`str\` | API key for authentication. |\n' : ''}| \`options["base"]\` | \`str\` | Base URL for API requests. |
 | \`options["prefix"]\` | \`str\` | URL prefix appended after base. |
 | \`options["suffix"]\` | \`str\` | URL suffix appended after path. |
 | \`options["headers"]\` | \`dict\` | Custom headers for all requests. |
@@ -123,9 +134,9 @@ Return a deep copy of the current SDK options.
 
 Return a copy of the SDK utility object.
 
-#### \`direct(fetchargs=None) -> tuple\`
+#### \`direct(fetchargs=None) -> dict\`
 
-Make a direct HTTP request to any API endpoint. Returns \`(result, err)\`.
+Make a direct HTTP request to any API endpoint. Returns a result \`dict\` with \`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure). This escape hatch never raises — branch on \`result["ok"]\`.
 
 **Parameters:**
 
@@ -138,11 +149,11 @@ Make a direct HTTP request to any API endpoint. Returns \`(result, err)\`.
 | \`fetchargs["headers"]\` | \`dict\` | Request headers (merged with defaults). |
 | \`fetchargs["body"]\` | \`any\` | Request body (dicts are JSON-serialized). |
 
-**Returns:** \`(result_dict, err)\`
+**Returns:** \`result_dict\`
 
-#### \`prepare(fetchargs=None) -> tuple\`
+#### \`prepare(fetchargs=None) -> dict\`
 
-Prepare a fetch definition without sending. Returns \`(fetchdef, err)\`.
+Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises on error.
 
 `)
 
@@ -151,6 +162,9 @@ Prepare a fetch definition without sending. Returns \`(fetchdef, err)\`.
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = ent.fields || []
+      // Model-driven id key: null when this entity has no id-like field, in
+      // which case load/remove match on no argument and update omits the id.
+      const idF = entityIdField(ent)
 
       Content(`
 ---
@@ -182,7 +196,7 @@ ${ent.name} = client.${ent.Name}()
         each(fields, (field: any) => {
           const req = field.req ? 'Yes' : 'No'
           const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${req} | ${desc} |
+          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -192,15 +206,18 @@ ${ent.name} = client.${ent.Name}()
         // Field operations breakdown
         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.
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
-| Field | load | list | create | update | remove |
-| --- | --- | --- | --- | --- | --- |
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
 `)
           each(fields, (field: any) => {
             const fops = field.op || {}
-            const cols = ['load', 'list', 'create', 'update', 'remove'].map((op: string) => {
-              if (!opnames.includes(op)) return '-'
+            const cols = opcols.map((op: string) => {
               const fop = fops[op]
               if (null == fop) return '-'
               if (fop.active === false) return '-'
@@ -232,28 +249,31 @@ ${info.desc}
 
 `)
 
-          // Show example
+          // Show example. Entity ops return the bare result and raise on
+          // error; direct() is the only method that returns a result dict.
           if ('load' === opname || 'remove' === opname) {
             Content(`\`\`\`python
-result, err = client.${ent.Name}().${opname}({"id": "${ent.name}_id"})
+result = client.${ent.Name}().${opname}(${idF ? `{"${idF}": "${ent.name}_id"}` : ''})
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`python
-results, err = client.${ent.Name}().list({})
+results = client.${ent.Name}().list()
+for ${ent.name} in results:
+    print(${ent.name})
 \`\`\`
 
 `)
           }
           else if ('create' === opname) {
             Content(`\`\`\`python
-result, err = client.${ent.Name}().create({
+result = client.${ent.Name}().create({
 `)
             each(fields, (field: any) => {
               if ('id' !== field.name && field.req) {
-                Content(`    "${field.name}": # ${field.type || 'value'},
+                Content(`    "${field.name}": ${pyLit(field.type)},  # ${canonToType(field.type, target.name)}
 `)
               }
             })
@@ -263,10 +283,10 @@ result, err = client.${ent.Name}().create({
 `)
           }
           else if ('update' === opname) {
+            const updateIdLine = idF ? `    "${idF}": "${ent.name}_id",\n` : ''
             Content(`\`\`\`python
-result, err = client.${ent.Name}().update({
-    "id": "${ent.name}_id",
-    # Fields to update
+result = client.${ent.Name}().update({
+${updateIdLine}    # Fields to update
 })
 \`\`\`