@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/src/cmp/c/ReadmeEntity_c.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -43,11 +43,12 @@ function cmapExpr(pairs: string[]): string {
 
 // Operation vtable descriptions (language-agnostic wording, C signatures).
 const OP_DESC: Record<string, { method: string, desc: string }> = {
-  load:   { method: 'vt->load(e, reqmatch, ctrl, &err)',   desc: 'Load a single entity by match criteria.' },
-  list:   { method: 'vt->list(e, reqmatch, ctrl, &err)',   desc: 'List entities, optionally matching the given criteria.' },
-  create: { method: 'vt->create(e, reqdata, ctrl, &err)',  desc: 'Create a new entity with the given data.' },
-  update: { method: 'vt->update(e, reqdata, ctrl, &err)',  desc: 'Update an existing entity.' },
-  remove: { method: 'vt->remove(e, reqmatch, ctrl, &err)', desc: 'Remove the matching entity.' },
+  load:   { method: 'Entity* vt->load(e, reqmatch, ctrl, &err)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'Entity** vt->list(e, reqmatch, ctrl, &err)',  desc: 'List entities, optionally matching the given criteria: a `NULL`-terminated array, one per record.' },
+  create: { method: 'Entity* vt->create(e, reqdata, ctrl, &err)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'Entity* vt->update(e, reqdata, ctrl, &err)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'Entity* vt->patch(e, reqdata, ctrl, &err)',  desc: 'Change part of an existing entity.' },
+  remove: { method: 'Entity* vt->remove(e, reqmatch, ctrl, &err)', desc: 'Remove the matching entity, which is returned marked as deleted.' },
 }
 
 
@@ -73,6 +74,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
     const evar = cVarName(entity.name)
@@ -128,7 +131,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -140,24 +143,30 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
 \`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+Entity* loaded = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+if (loaded) {
+    printf("%s\\n", voxgig_to_json(loaded->vt->data(loaded, NULL)));
+}
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+Entity** ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+for (size_t i = 0; ${evar}s && ${evar}s[i]; i++) {
+    printf("%s\\n", voxgig_to_json(${evar}s[i]->vt->data(${evar}s[i], NULL)));
+}
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -166,10 +175,10 @@ voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
 Entity* ${evar} = ${acc}(client, NULL);
 `)
       if (0 === createItems.length) {
-        Content(`voxgig_value* ${evar}_rec = ${evar}->vt->create(${evar}, NULL, NULL, &err);
+        Content(`Entity* created = ${evar}->vt->create(${evar}, NULL, NULL, &err);
 `)
       } else {
-        Content(`voxgig_value* ${evar}_rec = ${evar}->vt->create(${evar}, cmap(${createItems.length},
+        Content(`Entity* created = ${evar}->vt->create(${evar}, cmap(${createItems.length},
 `)
         createItems.map((it: any, i: number) => {
           const comma = i < createItems.length - 1 ? ',' : ')'

package/project/.sdk/src/cmp/c/ReadmeHowto_c.ts

@@ -43,7 +43,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'NULL'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `cmap(1, "${idF}", v_str("test01"))` : 'NULL'
-  } 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)
@@ -52,11 +52,16 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   }
 
   // The op-driven test-mode line. A direct()-only SDK shows a direct() call.
-  const testModeExample = primaryOp
-    ? `// Entity ops return the bare record and set *err on failure.
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns one entity per mock record, and sets *err on failure.
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${evar}_rec = ${evar}->vt->${primaryOp}(${evar}, ${testArg}, NULL, &err);
-// ${evar}_rec contains the mock response record`
+Entity** ${evar}s = ${evar}->vt->list(${evar}, ${testArg}, NULL, &err);
+// ${evar}s[i]->vt->data(${evar}s[i], NULL) is a mock record`
+    : primaryOp
+    ? `// Entity ops return the entity and set *err on failure.
+Entity* ${evar} = ${acc}(client, NULL);
+Entity* result = ${evar}->vt->${primaryOp}(${evar}, ${testArg}, NULL, &err);
+// result->vt->data(result, NULL) is the mock response record`
     : `voxgig_value* result = sdk_direct(client, cmap(2,
     "path", v_str("/api/resource"),
     "method", v_str("GET")), &err);

package/project/.sdk/src/cmp/c/ReadmeInstall_c.ts

@@ -24,9 +24,9 @@ cd ${target.name} && make
   // Publish pending: C has no central package registry — the release IS the
   // git tag. Build from a source checkout (the vendored voxgig struct means
   // there are no external dependencies to fetch).
-  const { releasesUrl } = repoInfo(model)
+  const { tagsUrl } = repoInfo(model)
   Content(`C has no central package registry — a release is the git tag
-(\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})). Build from a
+(\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})). Build from a
 source checkout with the bundled \`Makefile\`; the voxgig struct library is
 vendored under \`utility/struct\`, so there are no external dependencies to
 fetch:

package/project/.sdk/src/cmp/c/ReadmeIntro_c.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import { cIdent, cVarName } from './utility_c'
 
 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 || ''
 
   Content(`# ${model.Name} ${target.title} SDK
@@ -37,7 +37,7 @@ The ${target.title} SDK for the ${model.Name} API — an entity-oriented client
   // 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 CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {
     if (!e || e.active === false) return

package/project/.sdk/src/cmp/c/ReadmeModel_c.ts

@@ -23,13 +23,14 @@ 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` | `(Entity*, reqmatch, ctrl, PNError**) -> voxgig_value*` | Load a single entity by match criteria. |',
-    list: '| `list` | `(Entity*, reqmatch, ctrl, PNError**) -> voxgig_value*` | List entities matching the criteria (a List). |',
-    create: '| `create` | `(Entity*, reqdata, ctrl, PNError**) -> voxgig_value*` | Create a new entity. |',
-    update: '| `update` | `(Entity*, reqdata, ctrl, PNError**) -> voxgig_value*` | Update an existing entity. |',
-    remove: '| `remove` | `(Entity*, reqmatch, ctrl, PNError**) -> voxgig_value*` | Remove an entity. |',
+    load: '| `load` | `(Entity*, reqmatch, ctrl, PNError**) -> Entity*` | Load a single entity by match criteria. |',
+    list: '| `list` | `(Entity*, reqmatch, ctrl, PNError**) -> Entity**` | List entities matching the criteria: a `NULL`-terminated array, one per record. |',
+    create: '| `create` | `(Entity*, reqdata, ctrl, PNError**) -> Entity*` | Create a new entity. |',
+    update: '| `update` | `(Entity*, reqdata, ctrl, PNError**) -> Entity*` | Update an existing entity. |',
+    patch: '| `patch` | `(Entity*, reqdata, ctrl, PNError**) -> Entity*` | Change part of an existing entity. |',
+    remove: '| `remove` | `(Entity*, reqmatch, ctrl, PNError**) -> Entity*` | Remove an entity, which is returned 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 apikeyOptionRow = isAuthActive(model)
@@ -93,10 +94,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (a \`voxgig_value\` map for
-single-entity ops, a List for \`list\`) and set \`*err\` to a \`PNError*\` on
-failure. Always initialise \`PNError* err = NULL;\` and check it after the
-call.
+Entity operations return the entity, and \`list\` a \`NULL\`-terminated array
+of entities, one per record; \`vt->data\` reads an entity's record. On
+failure they return \`NULL\` and set \`*err\` to a \`PNError*\`. Always
+initialise \`PNError* err = NULL;\` and check it after the call.
 
 The \`sdk_direct()\` escape hatch never sets \`*err\` for a non-2xx response —
 it returns a result map you branch on via \`getp(result, "ok")\`:

package/project/.sdk/src/cmp/c/ReadmeQuick_c.ts

@@ -73,17 +73,18 @@ PNError* err = NULL;
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` returns a List of records and sets \`*err\` on failure — check
-\`err\` after the call.
+\`list()\` returns a \`NULL\`-terminated array of entities, one per record,
+and sets \`*err\` on failure — check \`err\` after the call. \`vt->data\`
+reads an entity's record.
 
 \`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+Entity** ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
 if (err) {
     fprintf(stderr, "list failed: %s\\n", err->msg);
 } else {
-    for (size_t i = 0; i < (size_t)voxgig_size(${evar}s); i++) {
-        printf("%s\\n", voxgig_to_json(voxgig_getelem(${evar}s, v_int(i), NULL)));
+    for (size_t i = 0; ${evar}s[i]; i++) {
+        printf("%s\\n", voxgig_to_json(${evar}s[i]->vt->data(${evar}s[i], NULL)));
     }
 }
 \`\`\`
@@ -112,15 +113,16 @@ if (err) {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record and sets \`*err\` on failure.
+\`load()\` returns the entity and sets \`*err\` on failure; \`vt->data\` reads
+its record.
 
 \`\`\`c
 Entity* ${neVar} = ${neAcc}(client, NULL);
-voxgig_value* ${neVar}_rec = ${neVar}->vt->load(${neVar}, ${neMatch}, NULL, &err);
+Entity* loaded = ${neVar}->vt->load(${neVar}, ${neMatch}, NULL, &err);
 if (err) {
     fprintf(stderr, "load failed: %s\\n", err->msg);
 } else {
-    printf("%s\\n", voxgig_to_json(${neVar}_rec));
+    printf("%s\\n", voxgig_to_json(loaded->vt->data(loaded, NULL)));
 }
 \`\`\`
 
@@ -140,14 +142,15 @@ if (err) {
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record and sets \`*err\` on failure.
+\`load()\` returns the entity and sets \`*err\` on failure; \`vt->data\` reads
+its record.
 
 \`\`\`c
-${acquire}voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+${acquire}Entity* loaded = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
 if (err) {
     fprintf(stderr, "load failed: %s\\n", err->msg);
 } else {
-    printf("%s\\n", voxgig_to_json(${evar}_rec));
+    printf("%s\\n", voxgig_to_json(loaded->vt->data(loaded, NULL)));
 }
 \`\`\`
 
@@ -172,14 +175,16 @@ if (err) {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
     }
-    // The id VALUE for an update/remove match: read it off the returned
-    // `created` record with getp when its data type carries the id AND a
-    // create ran; otherwise a type-correct literal.
-    const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `getp(created, "${dataIdF}")`
+    // The id VALUE for an update/remove match: `created_id`, read off the
+    // created entity's record, when its data type carries the id AND a create
+    // ran; otherwise a type-correct literal.
+    const readsId = null != dataIdF && opnames.includes('create')
+    const idValueFor = (opname: string): string => readsId
+      ? 'created_id'
       : cLit(idParamType(opname), 'example_id')
 
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       const acquire = (opnames.includes('list') || opnames.includes('load'))
         ? ''
         : `Entity* ${evar} = ${acc}(client, NULL);\n`
@@ -188,9 +193,14 @@ if (err) {
 \`\`\`c
 ${acquire}`)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record
-voxgig_value* created = ${evar}->vt->create(${evar}, ${cmapExpr(examplePairs('create'))}, NULL, &err);
-
+        const idLine = readsId && (opnames.includes('update') || opnames.includes('remove'))
+          ? `voxgig_value* created_id = created
+    ? getp(created->vt->data(created, NULL), "${dataIdF}") : v_undef();
+`
+          : ''
+        Content(`// Create — returns the created entity, or NULL with *err set
+Entity* created = ${evar}->vt->create(${evar}, ${cmapExpr(examplePairs('create'))}, NULL, &err);
+${idLine}
 `)
       }
       if (opnames.includes('update')) {
@@ -198,6 +208,13 @@ voxgig_value* created = ${evar}->vt->create(${evar}, ${cmapExpr(examplePairs('cr
         Content(`// Update
 ${evar}->vt->update(${evar}, ${cmapExpr(updatePairs)}, NULL, &err);
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`"${idF}", ${idValueFor('patch')}`] : []).concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+${evar}->vt->patch(${evar}, ${cmapExpr(patchPairs)}, NULL, &err);
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/c/ReadmeRef_c.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -53,24 +53,28 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
 
   const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
     load: {
-      sig: 'vt->load(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
-      desc: 'Load a single entity matching the given criteria. Returns the entity data and sets `*err` on failure.',
+      sig: 'Entity* vt->load(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `vt->data` reads, or `NULL` with `*err` set on failure.',
     },
     list: {
-      sig: 'vt->list(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
-      desc: 'List entities matching the given criteria. The match is optional — pass `NULL` to list all records. Returns a List.',
+      sig: 'Entity** vt->list(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'List entities matching the given criteria. The match is optional — pass `NULL` to list all records. Returns a `NULL`-terminated array of entities, one per record, or `NULL` with `*err` set on failure.',
     },
     create: {
-      sig: 'vt->create(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
-      desc: 'Create a new entity with the given data. Returns the created entity data and sets `*err` on failure.',
+      sig: 'Entity* vt->create(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
+      desc: 'Create a new entity with the given data. Returns the created entity, or `NULL` with `*err` set on failure.',
     },
     update: {
-      sig: 'vt->update(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
-      desc: 'Update an existing entity. The data must include the entity id. Returns the updated entity data.',
+      sig: 'Entity* vt->update(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
+      desc: 'Update an existing entity. The data must include the entity id. Returns the updated entity, or `NULL` with `*err` set on failure.',
+    },
+    patch: {
+      sig: 'vt->patch(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
+      desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity id. Returns the patched entity data.',
     },
     remove: {
-      sig: 'vt->remove(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
-      desc: 'Remove the entity matching the given criteria. Sets `*err` on failure.',
+      sig: 'Entity* vt->remove(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, or `NULL` with `*err` set on failure.',
     },
   }
 
@@ -219,7 +223,7 @@ Entity* ${evar} = ${acc}(client, NULL);
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -260,6 +264,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             const matchItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
@@ -270,7 +278,10 @@ ${info.desc}
                 it.name === idF ? ent.name + '_id' : it.name)}`))
             Content(`\`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* result = ${evar}->vt->${opname}(${evar}, ${arg}, NULL, &err);
+Entity* result = ${evar}->vt->${opname}(${evar}, ${arg}, NULL, &err);
+if (result) {
+    printf("%s\\n", voxgig_to_json(result->vt->data(result, NULL)));
+}
 \`\`\`
 
 `)
@@ -278,9 +289,9 @@ voxgig_value* result = ${evar}->vt->${opname}(${evar}, ${arg}, NULL, &err);
           else if ('list' === opname) {
             Content(`\`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* results = ${evar}->vt->list(${evar}, NULL, NULL, &err);
-for (size_t i = 0; i < (size_t)voxgig_size(results); i++) {
-    printf("%s\\n", voxgig_to_json(voxgig_getelem(results, v_int(i), NULL)));
+Entity** results = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+for (size_t i = 0; results && results[i]; i++) {
+    printf("%s\\n", voxgig_to_json(results[i]->vt->data(results[i], NULL)));
 }
 \`\`\`
 
@@ -293,10 +304,10 @@ for (size_t i = 0; i < (size_t)voxgig_size(results); i++) {
 Entity* ${evar} = ${acc}(client, NULL);
 `)
             if (0 === createItems.length) {
-              Content(`voxgig_value* result = ${evar}->vt->create(${evar}, NULL, NULL, &err);
+              Content(`Entity* result = ${evar}->vt->create(${evar}, NULL, NULL, &err);
 `)
             } else {
-              Content(`voxgig_value* result = ${evar}->vt->create(${evar}, cmap(${createItems.length},
+              Content(`Entity* result = ${evar}->vt->create(${evar}, cmap(${createItems.length},
 `)
               createItems.map((it: any, i: number) => {
                 const comma = i < createItems.length - 1 ? ',' : ')'
@@ -310,8 +321,8 @@ Entity* ${evar} = ${acc}(client, NULL);
 
 `)
           }
-          else if ('update' === opname) {
-            const updateItems = opRequestShape(ent, 'update').items
+          else if ('update' === opname || 'patch' === opname) {
+            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))
@@ -320,11 +331,18 @@ Entity* ${evar} = ${acc}(client, NULL);
                 it.name === idF ? ent.name + '_id' : it.name)}`)
             Content(`\`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* result = ${evar}->vt->update(${evar}, ${cmapExpr(updatePairs)}, NULL, &err);
+Entity* result = ${evar}->vt->${opname}(${evar}, ${cmapExpr(updatePairs)}, NULL, &err);
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a string value holding the bytes, such as `voxgig_new_string_n`',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/c/ReadmeTopQuick_c.ts

@@ -61,10 +61,10 @@ PNError* err = NULL;
     if (opnames.includes('list')) {
       Content(`Entity* ${evar} = ${acc}(client, NULL);
 
-// List all ${eName.toLowerCase()}s (returns a List, sets *err on failure)
-voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
-for (size_t i = 0; i < (size_t)voxgig_size(${evar}s); i++) {
-    printf("%s\\n", voxgig_to_json(voxgig_getelem(${evar}s, v_int(i), NULL)));
+// List all ${eName.toLowerCase()}s (one entity per record, sets *err on failure)
+Entity** ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+for (size_t i = 0; ${evar}s && ${evar}s[i]; i++) {
+    printf("%s\\n", voxgig_to_json(${evar}s[i]->vt->data(${evar}s[i], NULL)));
 }
 `)
     }
@@ -84,9 +84,11 @@ for (size_t i = 0; i < (size_t)voxgig_size(${evar}s); i++) {
         ? ''
         : `Entity* ${evar} = ${acc}(client, NULL);\n`
       Content(`
-${acquire}// Load a specific ${eName.toLowerCase()} (returns the record, sets *err on failure)
-voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
-printf("%s\\n", voxgig_to_json(${evar}_rec));
+${acquire}// Load a specific ${eName.toLowerCase()} (returns the entity, sets *err on failure)
+Entity* loaded = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+if (loaded) {
+    printf("%s\\n", voxgig_to_json(loaded->vt->data(loaded, NULL)));
+}
 `)
     }
   }

package/project/.sdk/src/cmp/c/ReadmeTopTest_c.ts

@@ -61,18 +61,29 @@ PNError* err = NULL;
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = cmapExpr(items.map((it: any) =>
         `"${it.name}", ${it.name === idF ? 'v_str("test01")' : cLit(it.type)}`))
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('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)
       arg = cmapExpr(chosen.map((it: any) => `"${it.name}", ${cLit(it.type)}`))
     }
-    const resVar = cVarName(exampleEntity.name) + ('list' === primaryOp ? 's' : '_rec')
     Content(`Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${resVar} = ${evar}->vt->${primaryOp}(${evar}, ${arg}, NULL, &err);
-printf("%s\\n", voxgig_to_json(${resVar}));
 `)
+    if ('list' === primaryOp) {
+      Content(`Entity** ${evar}s = ${evar}->vt->list(${evar}, ${arg}, NULL, &err);
+for (size_t i = 0; ${evar}s && ${evar}s[i]; i++) {
+    printf("%s\\n", voxgig_to_json(${evar}s[i]->vt->data(${evar}s[i], NULL)));
+}
+`)
+    }
+    else {
+      Content(`Entity* result = ${evar}->vt->${primaryOp}(${evar}, ${arg}, NULL, &err);
+if (result) {
+    printf("%s\\n", voxgig_to_json(result->vt->data(result, NULL)));
+}
+`)
+    }
   }
 
   Content(`\`\`\`