@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/elixir/Entity_elixir.ts

@@ -10,6 +10,9 @@ import {
 import { EntityOperation } from './EntityOperation_elixir'
 
 
+const OPS = ['load', 'list', 'create', 'update', 'patch', 'remove']
+
+
 const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
@@ -26,7 +29,7 @@ const Entity = cmp(function Entity(props: any) {
         const opnames = Object.keys(entity.op || {})
 
         const opfrags =
-          (['load', 'list', 'create', 'update', 'remove']
+          (OPS
             .reduce((a: any, opname: string) =>
             (a['# #' + camelify(opname) + 'Op'] =
               !opnames.includes(opname) ? '' : (_slot: any) => {
@@ -40,6 +43,7 @@ const Entity = cmp(function Entity(props: any) {
             ProjectName: Name,
             EntityName: entity.Name,
             entityname: entity.name,
+            '# #Aliases': aliases(props.ctx$.fs(), ff, Name, opnames),
             ...opfrags,
           }
         })
@@ -49,6 +53,23 @@ const Entity = cmp(function Entity(props: any) {
 })
 
 
+// Only what the emitted operations use: elixir warns on an unused alias.
+function aliases(fs: any, ff: string, Name: string, opnames: string[]): string {
+  const optext = OPS.filter((opname) => opnames.includes(opname))
+    .map((opname) => String(fs.readFileSync(
+      ff + 'Entity' + camelify(opname) + 'Op.fragment.ex', 'utf8')))
+    .join('\n')
+  const uses = (name: string) => new RegExp('\\b' + name + '\\.').test(optext)
+  const core = ['EntityBase', ...['Context', 'Pipeline'].filter(uses)]
+
+  return [
+    ...(uses('S') ? ['alias Voxgig.Struct, as: S'] : []),
+    ...(uses('H') ? ['alias ' + Name + '.Helpers, as: H'] : []),
+    'alias ' + Name + (1 === core.length ? '.' + core[0] : '.{' + core.join(', ') + '}'),
+  ].join('\n  ')
+}
+
+
 export {
   Entity
 }

package/project/.sdk/src/cmp/elixir/MainEntity_elixir.ts

@@ -1,19 +1,21 @@
 
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, elixirAccessor, entityCollection } from '@voxgig/sdkgen'
 
 
 // Emit an entity factory function into the main SDK module (at its slot):
 //   def widget(client, entopts \\ nil), do: Solardemo.Entity.Widget.new(client, entopts)
+// A reserved word (`end`) is not a function name: see elixirAccessor.
 const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
   const { model } = props.ctx$
 
   const Name = model.const.Name
+  const accessor = elixirAccessor(entity, entityCollection(model))
 
   Content(`
   @doc "Entity factory for ${entity.name}."
-  def ${entity.name}(client, entopts \\\\ nil) do
+  def ${accessor}(client, entopts \\\\ nil) do
     ${Name}.Entity.${entity.Name}.new(client, entopts)
   end
 `)

package/project/.sdk/src/cmp/elixir/Main_elixir.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each,
   File, Folder, Content, Copy, Fragment,
+  inactiveFeatureExcludes,
   pluginExcludes,
   targetFeatures,
 } from '@voxgig/sdkgen'
@@ -54,7 +55,7 @@ const Main = cmp(async function Main(props: any) {
 
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//, /lib\/projectname\//],
+    exclude: [/src\//, /lib\/projectname\//, ...inactiveFeatureExcludes(props.ctx$, target)],
     replace: {
       ...stdrep,
     }
@@ -64,7 +65,10 @@ const Main = cmp(async function Main(props: any) {
     Copy({
       from: 'tm/' + target.name + '/lib/projectname',
       to: model.const.name,
-      exclude: [...pluginExcludes(model)],
+      exclude: [
+        ...inactiveFeatureExcludes(props.ctx$, target, 'tm/' + target.name + '/lib/projectname'),
+        ...pluginExcludes(model),
+      ],
       replace: {
         ...stdrep,
       }

package/project/.sdk/src/cmp/elixir/Package_elixir.ts

@@ -44,6 +44,11 @@ const Package = cmp(async function Package(props: any) {
     ]
   end`
 
+  // Hex fails a build that lists a missing file, so the docs are listed only
+  // when the readme phase writes them.
+  const docs = false === target.phase?.readme?.active ? [] : ['README.md', 'REFERENCE.md']
+  const files = ['lib', 'mix.exs', 'LICENSE', ...docs]
+
   File({ name: 'mix.exs' }, () => {
     Content(`defmodule ${Name}.MixProject do
   use Mix.Project
@@ -71,8 +76,10 @@ ${depsBlock}
   defp elixirc_paths(:test), do: ["lib", "test/support", "test/vendor"]
   defp elixirc_paths(_), do: ["lib"]
 
+  # Hex ships only these files; its default list leaves REFERENCE.md out.
   defp package do
     [
+      files: [${files.map((f) => JSON.stringify(f)).join(', ')}],
       licenses: ["MIT"],
       links: %{"Homepage" => ${JSON.stringify(repoUrl)}}
     ]

package/project/.sdk/src/cmp/elixir/PrepareAuth_elixir.ts

@@ -114,11 +114,11 @@ end
     ? `      query = S.getprop(spec, "query")`
     : `      headers = S.getprop(spec, "headers")`
 
-  const clear = query
-    ? 'S.delprop(query, @cred_name)'
+  const clear = (name: string) => query
+    ? `S.delprop(query, ${name})`
     : cookie
-      ? 'apply_cookie(headers, nil)'
-      : 'S.delprop(headers, @cred_name)'
+      ? `apply_cookie(headers, ${name}, nil)`
+      : `S.delprop(headers, ${name})`
 
   const preamble = `  def prepare_auth_impl(ctx) do
     spec = S.getprop(ctx, "spec")
@@ -131,9 +131,16 @@ ${bag}
 
       # Public APIs that need no auth omit the options.auth block entirely.
       if S.getprop(options, "auth") == nil do
-        ${clear}
+        ${clear('@cred_name')}
         {spec, nil}
       else
+        name = auth_name(options)
+
+        # A credential left under the declared name would travel beside the renamed one.
+        if name != @cred_name do
+          ${clear('@cred_name')}
+        end
+
         apikey = S.getprop(options, @option_apikey, @not_found)
 
 `
@@ -151,7 +158,7 @@ ${bag}
           no_secret = not is_binary(secret) or secret == @not_found or secret == ""
 
           if no_apikey do
-            S.delprop(headers, @cred_name)
+            S.delprop(headers, name)
           else
             ap = S.getpath(options, "auth.prefix")
             auth_prefix = if is_binary(ap), do: ap, else: ""
@@ -160,13 +167,13 @@ ${bag}
             # own registration covers.
             ${spec.Name}.Utility.clean_add(ctx, b64)
             hv = if auth_prefix != "", do: auth_prefix <> " " <> b64, else: b64
-            S.setprop(headers, @cred_name, hv)
+            S.setprop(headers, name, hv)
           end
         else
-${indent(place(spec, clear), 1)}
+${indent(place(spec, clear('name')), 1)}
         end
 `
-    : place(spec, clear)
+    : place(spec, clear('name'))
 
   return head + attrs + preamble + body + `
         {spec, nil}
@@ -191,7 +198,7 @@ function place(spec: AuthSpec, clear: string): string {
           # thing any API reads: the prefix is a header convention, so
           # options.auth.prefix is dropped here deliberately rather than
           # silently concatenated.
-          S.setprop(query, @cred_name, apikey_val)
+          S.setprop(query, name, apikey_val)
         end
 `
   }
@@ -200,7 +207,7 @@ function place(spec: AuthSpec, clear: string): string {
     return guard + `          apikey_val = if is_binary(apikey), do: apikey, else: ""
           # NO PREFIX IN A COOKIE either - a cookie carries a bare
           # \`name=value\` pair, not a header's scheme-prefixed credential.
-          apply_cookie(headers, apikey_val)
+          apply_cookie(headers, name, apikey_val)
         end
 `
   }
@@ -210,14 +217,24 @@ function place(spec: AuthSpec, clear: string): string {
           apikey_val = if is_binary(apikey), do: apikey, else: ""
           # Empty prefix (raw apiKey credential) must not add a leading space.
           hv = if auth_prefix != "", do: auth_prefix <> " " <> apikey_val, else: apikey_val
-          S.setprop(headers, @cred_name, hv)
+          S.setprop(headers, name, hv)
         end
 `
 }
 
 
 function helpers(spec: AuthSpec): string {
-  const optsMap = `  # The client's options as a MAP, cloned. The clone is load-bearing: the
+  const authName = `  # The client's auth.name option, when set, replaces the name the API declares.
+  defp auth_name(options) do
+    case S.getpath(options, "auth.name") do
+      given when is_binary(given) and given != "" -> ${'header' === spec.where ? 'String.downcase(given)' : 'given'}
+      _ -> @cred_name
+    end
+  end
+
+`
+
+  const optsMap = authName + `  # The client's options as a MAP, cloned. The clone is load-bearing: the
   # secrets feature rewrites options.apikey on the live client, and
   # prepare_auth must read a snapshot rather than the node the feature is
   # mutating. Same body as ${spec.Name}.Utility's own private opts_map/1.
@@ -236,27 +253,20 @@ function helpers(spec: AuthSpec): string {
   // cookies the caller set - so the pair is spliced in and out rather than
   // the header assigned over. Splicing also makes this idempotent: a
   // retried request cannot end up carrying the credential twice.
-  return optsMap + `  # The cookie header minus our own pair, every other cookie untouched.
-  defp cookies_without_cred(headers) do
+  return optsMap + `  # The cookie header minus the named pair, every other cookie untouched.
+  defp cookies_without_cred(headers, name) do
     existing = S.getprop(headers, @cookie_header)
 
     if is_binary(existing) and existing != "" do
-      existing
-      |> String.split(";")
-      |> Enum.map(&String.trim/1)
-      |> Enum.reject(fn piece ->
-        piece == "" or piece == @cred_name or
-          String.starts_with?(piece, @cred_name <> "=")
-      end)
-      |> Enum.join("; ")
+      Enum.join(${spec.Name}.Utility.cookie_keep(existing, [name]), "; ")
     else
       ""
     end
   end
 
-  # Remove our pair, leaving the rest of the cookie header in place.
-  defp apply_cookie(headers, nil) do
-    rest = cookies_without_cred(headers)
+  # Remove the named pair, leaving the rest of the cookie header in place.
+  defp apply_cookie(headers, name, nil) do
+    rest = cookies_without_cred(headers, name)
 
     if rest == "" do
       S.delprop(headers, @cookie_header)
@@ -265,10 +275,10 @@ function helpers(spec: AuthSpec): string {
     end
   end
 
-  # Set our pair, leaving the rest of the cookie header in place.
-  defp apply_cookie(headers, value) do
-    rest = cookies_without_cred(headers)
-    pair = @cred_name <> "=" <> value
+  # Set the named pair, leaving the rest of the cookie header in place.
+  defp apply_cookie(headers, name, value) do
+    rest = cookies_without_cred(headers, name)
+    pair = name <> "=" <> value
     S.setprop(headers, @cookie_header, if(rest == "", do: pair, else: rest <> "; " <> pair))
   end
 

package/project/.sdk/src/cmp/elixir/ReadmeEntity_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, opNeedsAction, elixirAccessor, entityCollection, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,7 +7,7 @@ import {
 } from '@voxgig/apidef'
 
 // Type names come from the shared canonToType 'elixir' column (single source of truth).
-import { elixirLit } from './utility_elixir'
+import { elixirLit, elixirListArgs } from './utility_elixir'
 
 
 // Operation method spelling for the Elixir target: each op is a function on
@@ -18,6 +18,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(entity)',         desc: 'List entities, optionally matching the given criteria.' },
   create: { method: 'create(entity, data)', desc: 'Create a new entity with the given data.' },
   update: { method: 'update(entity, data)', desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(entity, data)',  desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(entity, match)', desc: 'Remove the matching entity.' },
 }
 
@@ -47,8 +48,11 @@ takes an entity handle built from the client:
 
   publishedEntities.map((entity: any) => {
     const EName = entity.Name
-    const eVar = entity.name
+    const eVar = exampleVarName(entity.name, 'elixir')
+    const eCall = elixirAccessor(entity, entityCollection(model))
     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)
 
@@ -63,7 +67,7 @@ takes an entity handle built from the client:
 `)
     }
 
-    Content(`Create a handle: \`${eVar} = ${Name}.${eVar}(sdk)\`
+    Content(`Create a handle: \`${eVar} = ${Name}.${eCall}(sdk)\`
 
 `)
 
@@ -102,7 +106,7 @@ takes an entity handle built from the client:
 `)
     }
 
-    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) =>
@@ -115,25 +119,25 @@ takes an entity handle built from the client:
       Content(`#### Example: Load
 
 \`\`\`elixir
-${eVar} = ${Name}.${eVar}(sdk)
-record = ${Name}.Entity.${EName}.load(${eVar}, ${loadArg})
+${eVar} = ${Name}.${eCall}(sdk)
+${eVar} = ${Name}.Entity.${EName}.load(${eVar}, ${loadArg})
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`elixir
-${eVar} = ${Name}.${eVar}(sdk)
-records = ${Name}.Entity.${EName}.list(${eVar})
+${eVar} = ${Name}.${eCall}(sdk)
+${eVar}s = ${Name}.Entity.${EName}.list(${eVar}${elixirListArgs(entity, Name)})
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear — with a real,
       // executable literal.
@@ -142,8 +146,8 @@ records = ${Name}.Entity.${EName}.list(${eVar})
       Content(`#### Example: Create
 
 \`\`\`elixir
-${eVar} = ${Name}.${eVar}(sdk)
-record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
+${eVar} = ${Name}.${eCall}(sdk)
+${eVar} = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
 `)
       createItems.map((it: any) => {
         Content(`  "${it.name}" => ${elixirLit(it.type, 'example_' + it.name)},  # ${canonToType(it.type, target.name)}

package/project/.sdk/src/cmp/elixir/ReadmeExplanation_elixir.ts

@@ -17,7 +17,8 @@ that every later pipeline stage observes — the immutable-Elixir way to honour
 the shared-mutable hook contract.
 
 Build inputs from native Elixir maps with \`${model.Name}.Helpers.deep/1\`,
-and read fields off results with \`Voxgig.Struct.getprop/2\`.
+and read fields off a record, which an entity's \`data_get/1\` returns, with
+\`Voxgig.Struct.getprop/2\`.
 
 ### Module structure
 

package/project/.sdk/src/cmp/elixir/ReadmeHowto_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, pickExampleEntity, opRequestShape, elixirAccessor, entityCollection, exampleVarName, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { elixirLit } from './utility_elixir'
+import { elixirLit, elixirString } from './utility_elixir'
 
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
@@ -20,26 +20,34 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // when NO entity exposes any op (a direct()-only SDK).
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
-  const eVar = exampleEntity ? exampleEntity.name : 'entity'
+  const eVar = exampleEntity ? exampleVarName(exampleEntity.name, 'elixir') : 'entity'
+  const eCall = exampleEntity ? elixirAccessor(exampleEntity, entityCollection(model)) : 'entity'
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'H.deep(%{})'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `H.deep(%{"${idF}" => "test01"})` : 'H.deep(%{})'
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = `H.deep(%{${chosen.map((it: any) => `${elixirString(it.name)} => ${elixirLit(it.type)}`).join(', ')}})`
+  } 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 = `H.deep(%{${chosen.map((it: any) => `"${it.name}" => ${elixirLit(it.type)}`).join(', ')}})`
+    testArg = `H.deep(%{${chosen.map((it: any) => `${elixirString(it.name)} => ${elixirLit(it.type)}`).join(', ')}})`
   }
 
-  const resVar = 'list' === primaryOp ? 'records' : 'record'
   const testModeExample = primaryOp
-    ? `# Entity ops return the bare record (raise on error).
-${eVar} = ${Name}.${eVar}(sdk)
-${resVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${testArg})
-IO.inspect(${resVar})`
+    ? `# Entity ops return the entity, and list one per record (raise on error).
+${eVar} = ${Name}.${eCall}(sdk)
+${'list' === primaryOp
+  ? `${eVar}s = ${Name}.Entity.${eName}.list(${eVar}, ${testArg})
+for i <- 0..(Voxgig.Struct.size(${eVar}s) - 1)//1 do
+  IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(Voxgig.Struct.getelem(${eVar}s, i))))
+end`
+  : `${eVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${testArg})
+IO.puts(Voxgig.Struct.jsonify(${Name}.Entity.${eName}.data_get(${eVar})))`}`
     : `result = ${Name}.direct(sdk, H.deep(%{"path" => "/api/resource", "method" => "GET"}))
 IO.inspect(result)`
 

package/project/.sdk/src/cmp/elixir/ReadmeInstall_elixir.ts

@@ -33,9 +33,9 @@ mix deps.get
 
   // Publish pending: not yet on Hex. Install from the git release tag or a
   // local path checkout.
-  const { repoUrl, releasesUrl } = repoInfo(model)
+  const { hostName, repoUrl, tagsUrl } = repoInfo(model)
   Content(`This package is not yet published to [Hex](https://hex.pm). Install it from
-the GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl}))
+the ${hostName} release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl}))
 by adding a git dependency to your \`mix.exs\`:
 
 \`\`\`elixir

package/project/.sdk/src/cmp/elixir/ReadmeIntro_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, elixirAccessor, entityCollection, 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 || ''
 
   Content(`# ${model.Name} ${target.title} SDK
@@ -30,13 +30,13 @@ following idiomatic, functional Elixir conventions.
   const exampleEntity = Object.values(entity || {})
     .find((e: any) => e.active !== false) as any
   const example = exampleEntity
-    ? `for example \`${model.const.Name}.${exampleEntity.name}(sdk)\` — each`
+    ? `for example \`${model.const.Name}.${elixirAccessor(exampleEntity, entityCollection(model))}(sdk)\` — 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 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/elixir/ReadmeModel_elixir.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, elixirAccessor, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -21,13 +21,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 \\\\ nil) :: map()` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `list` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: list()` | List entities matching the criteria. Raises on error. |',
-    create: '| `create` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Create a new entity. Raises on error. |',
-    update: '| `update` | `(entity, reqdata, ctrl \\\\ nil) :: map()` | Update an existing entity. Raises on error. |',
-    remove: '| `remove` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: map()` | Remove an entity. Raises on error. |',
+    load: '| `load` | `(entity, reqmatch, ctrl \\\\ nil) :: entity` | Load a single entity by match criteria, and return it. Raises on error. |',
+    list: '| `list` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: list()` | List entities matching the criteria, one per record. Raises on error. |',
+    create: '| `create` | `(entity, reqdata, ctrl \\\\ nil) :: entity` | Create a new entity, and return it. Raises on error. |',
+    update: '| `update` | `(entity, reqdata, ctrl \\\\ nil) :: entity` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `patch` | `(entity, reqdata, ctrl \\\\ nil) :: entity` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `remove` | `(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: entity` | Remove an entity, and return it marked as deleted. Raises on error. |',
   }
-  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)
@@ -72,7 +73,7 @@ Creates a test-mode client with mock transport. Both arguments may be \`nil\`.
 
   each(entityList, (ent: any) => {
     const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
-    Content(`| \`${ent.name}\` | \`(client, entopts \\\\ nil) :: entity\` | Create ${article} ${ent.Name} entity handle. |
+    Content(`| \`${elixirAccessor(ent, entityCollection(model))}\` | \`(client, entopts \\\\ nil) :: entity\` | Create ${article} ${ent.Name} entity handle. |
 `)
   })
 
@@ -93,9 +94,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (a value node — a map for
-single-entity ops, a list for \`list\`) and raise a \`${Name}.Error\` on
-failure. Wrap calls in \`try\`/\`rescue\` to handle errors.
+Entity operations return the entity, and \`list\` a list of entities, one per
+record; an entity module's \`data_get/1\` reads an entity's record. They raise
+a \`${Name}.Error\` on failure, so wrap calls in \`try\`/\`rescue\` to handle
+errors.
 
 The \`direct/2\` escape hatch never raises — it returns a result node you
 branch on via \`Voxgig.Struct.getprop(result, "ok")\`: