@voxgig/sdkgen 2.0.2 → 3.1.0

package/project/.sdk/src/cmp/php/ReadmeQuick_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps, phpEntityAccessor } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -82,7 +82,7 @@ $client = ${ctor};
 \`\`\`php
 try {
     // list() returns an array of ${eName} records — iterate directly.
-    $${eName.toLowerCase()}s = $client->${eName}()->list();
+    $${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list();
     foreach ($${eName.toLowerCase()}s as $item) {
         echo ${itemPrint} . "\\n";
     }
@@ -120,8 +120,8 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 
 \`\`\`php
 try {
-    // load() returns the bare ${neName} record (throws on error).
-    $${neVar} = $client->${neName}()->load([${neMatch.join(', ')}]);
+    // load() returns the ENTITY — call data_get() for the ${neName} record (throws on error).
+    $${neVar} = $client->${phpEntityAccessor(neName)}()->load([${neMatch.join(', ')}]);
     print_r($${neVar});
 } catch (\\Throwable $err) {
     echo "Error: " . $err->getMessage();
@@ -148,8 +148,8 @@ try {
 
 \`\`\`php
 try {
-    // load() returns the bare ${eName} record (throws on error).
-    $${eName.toLowerCase()} = $client->${eName}()->load(${loadArg});
+    // load() returns the ENTITY — call data_get() for the ${eName} record (throws on error).
+    $${eName.toLowerCase()} = $client->${phpEntityAccessor(eName)}()->load(${loadArg});
     print_r($${eName.toLowerCase()});
 } catch (\\Throwable $err) {
     echo "Error: " . $err->getMessage();
@@ -187,7 +187,7 @@ try {
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `$created["${dataIdF}"]`
+      ? `$created->data_get()["${dataIdF}"]`
       : phpLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
@@ -196,16 +196,16 @@ try {
 \`\`\`php
 `)
       if (opnames.includes('create')) {
-        Content(`// create() returns the bare created ${eName} record.
-$created = $client->${eName}()->create([${examplePairs('create').join(', ')}]);
+        Content(`// create() returns the ENTITY — call data_get() for the created ${eName} record.
+$created = $client->${phpEntityAccessor(eName)}()->create([${examplePairs('create').join(', ')}]);
 
 `)
       }
       if (opnames.includes('update')) {
         const updatePairs = (idF ? [`"${idF}" => ${idValueFor('update')}`] : []).concat(examplePairs('update'))
         const fromCreated = null != dataIdF && opnames.includes('create')
-        Content(`// Update${fromCreated ? ` — index the bare record directly ($created["${dataIdF}"]).` : ''}
-$client->${eName}()->update([${updatePairs.join(', ')}]);
+        Content(`// Update${fromCreated ? ` — index the record via data_get() ($created->data_get()["${dataIdF}"]).` : ''}
+$client->${phpEntityAccessor(eName)}()->update([${updatePairs.join(', ')}]);
 
 `)
       }
@@ -220,7 +220,7 @@ $client->${eName}()->update([${updatePairs.join(', ')}]);
             ? `"${it.name}" => ${idValueFor('remove')}`
             : `"${it.name}" => ${phpLit(it.type, 'example_' + it.name)}`)
         Content(`// Remove
-$client->${eName}()->remove(${removePairs.length ? `[${removePairs.join(', ')}]` : ''});
+$client->${phpEntityAccessor(eName)}()->remove(${removePairs.length ? `[${removePairs.join(', ')}]` : ''});
 `)
       }
       Content(`\`\`\`

package/project/.sdk/src/cmp/php/ReadmeRef_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -186,7 +186,7 @@ Prepare a fetch definition without sending the request. Returns the
       }
 
       Content(`\`\`\`php
-$${ent.name} = $client->${ent.Name}();
+$${ent.name} = $client->${phpEntityAccessor(ent.Name)}();
 \`\`\`
 
 `)
@@ -270,14 +270,14 @@ ${info.desc}
                   it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')}]`
               : ''
             Content(`\`\`\`php
-$result = $client->${ent.Name}()->${opname}(${arg});
+$result = $client->${phpEntityAccessor(ent.Name)}()->${opname}(${arg});
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`php
-$results = $client->${ent.Name}()->list();
+$results = $client->${phpEntityAccessor(ent.Name)}()->list();
 \`\`\`
 
 `)
@@ -289,7 +289,7 @@ $results = $client->${ent.Name}()->list();
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
             Content(`\`\`\`php
-$result = $client->${ent.Name}()->create([
+$result = $client->${phpEntityAccessor(ent.Name)}()->create([
 `)
             createItems.map((it: any) => {
               Content(`  "${it.name}" => null, // ${canonToType(it.type, target.name)}
@@ -311,7 +311,7 @@ $result = $client->${ent.Name}()->create([
               `  "${it.name}" => ${phpLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`php
-$result = $client->${ent.Name}()->update([
+$result = $client->${phpEntityAccessor(ent.Name)}()->update([
 ${updateLines}  // Fields to update
 ]);
 \`\`\`

package/project/.sdk/src/cmp/php/ReadmeTopQuick_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -51,7 +51,7 @@ $client = ${ctor};
 
     if (opnames.includes('list')) {
       Content(`// List all ${eName.toLowerCase()}s (returns an array; throws on error)
-$${eName.toLowerCase()}s = $client->${eName}()->list();
+$${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list();
 print_r($${eName.toLowerCase()}s);
 `)
       hasCall = true
@@ -71,8 +71,8 @@ print_r($${eName.toLowerCase()}s);
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}]`
         : ''
       Content(`
-// Load a specific ${eName.toLowerCase()} (returns the bare record; throws on error)
-$${eName.toLowerCase()} = $client->${eName}()->load(${loadArg});
+// Load a specific ${eName.toLowerCase()} (returns the ENTITY; call data_get() for the record; throws on error)
+$${eName.toLowerCase()} = $client->${phpEntityAccessor(eName)}()->load(${loadArg});
 print_r($${eName.toLowerCase()});
 `)
       hasCall = true

package/project/.sdk/src/cmp/php/ReadmeTopTest_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -60,7 +60,7 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
 $client = ${model.const.Name}SDK::test([
     "entity" => ["${ename}" => ["test01" => ${recBody}]],
 ]);
-$${eVar} = $client->${eName}()->${primaryOp}(${callArg});
+$${eVar} = $client->${phpEntityAccessor(eName)}()->${primaryOp}(${callArg});
 \`\`\`
 `)
   } else {

package/project/.sdk/src/cmp/php/TestDirect_php.ts

@@ -11,7 +11,7 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -60,7 +60,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const target = props.target
   const entity: ModelEntity = props.entity
 
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJECTNAME = envName(model)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -125,7 +125,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     ? loadParams.map((p: any) => `            $params["${p.name}"] = ${JSON.stringify(p.example)};`).join('\n')
     : ''
 
-  const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
+  const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
   File({ name: entity.Name + 'DirectTest.' + target.ext }, () => {
 

package/project/.sdk/src/cmp/php/TestEntity_php.ts

@@ -24,7 +24,8 @@ import {
   buildIdNames,
   getMatchEntries,
   isAuthActive,
-  entityDataIdField,
+  entityDataIdField, envName, envToken,
+  phpEntityAccessor,
 } from '@voxgig/sdkgen'
 
 
@@ -61,15 +62,16 @@ const TestEntity = cmp(function TestEntity(props: any) {
     return
   }
 
-  // PHP method names are case-insensitive — an entity literally named 'test'
-  // collides with the static `test()` test-mode constructor on the SDK class.
-  // Mirror the mangling done in MainEntity_php.ts.
+  // The accessor may be mangled to avoid colliding with an SDK class member.
+  // This used to carry its own copy of the rule, which only knew about `test`
+  // — so an entity named `graph_ql` emitted `$client->GraphQl(null)` here,
+  // which PHP resolves (case-insensitively) to the SDK's own
+  // `graphql(string $query)` and fails with "Argument #1 must be of type
+  // string, null given". One helper, one answer.
   const entName = nom(entity, 'Name')
-  const accessor = 'test' === entName.toLowerCase()
-    ? entName + '_'
-    : entName
+  const accessor = phpEntityAccessor(entName)
 
-  const PROJUPPER = nom(model.const, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJUPPER = envName(model)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -167,7 +169,7 @@ ${hasList ? `
         // The basic flow consumes synthetic IDs from the fixture. In live mode
         // without an *_ENTID env override, those IDs hit the live API and 4xx.
         if (!empty($setup["synthetic_only"])) {
-            $this->markTestSkipped("live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID JSON to run live");
+            $this->markTestSkipped("live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID JSON to run live");
             return;
         }
         $client = $setup["client"];
@@ -238,17 +240,17 @@ ${hasList ? `
     Content(`    // Detect ENTID env override before envOverride consumes it. When live
     // mode is on without a real override, the basic test runs against synthetic
     // IDs from the fixture and 4xx's. Surface this so the test can skip.
-    $entid_env_raw = getenv("${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID");
+    $entid_env_raw = getenv("${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID");
     $idmap_overridden = $entid_env_raw !== false && str_starts_with(trim($entid_env_raw), "{");
 
     $env = Runner::env_override([
-        "${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID" => $idmap,
+        "${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID" => $idmap,
         "${PROJUPPER}_TEST_LIVE" => "FALSE",
         "${PROJUPPER}_TEST_EXPLAIN" => "FALSE",${apikeyEnvEntry}
     ]);
 
     $idmap_resolved = Helpers::to_map(
-        $env["${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID"]);
+        $env["${PROJUPPER}_TEST_${envToken(entity.name)}_ENTID"]);
     if ($idmap_resolved === null) {
         $idmap_resolved = Helpers::to_map($idmap);
     }
@@ -333,7 +335,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
   Content(`
         $${datavar}_result = $${entvar}->create($${datavar}, null);
-        $${datavar} = Helpers::to_map($${datavar}_result);
+        $${datavar} = Helpers::to_map(is_object($${datavar}_result) && method_exists($${datavar}_result, 'data_get') ? $${datavar}_result->data_get() : $${datavar}_result);
         $this->assertNotNull($${datavar});
 `)
   if (null != ctx.entity.id) {
@@ -467,7 +469,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
   Content(`
         $${resdatavar}_result = $${entvar}->update($${datavar}_up, null);
-        $${resdatavar} = Helpers::to_map($${resdatavar}_result);
+        $${resdatavar} = Helpers::to_map(is_object($${resdatavar}_result) && method_exists($${resdatavar}_result, 'data_get') ? $${resdatavar}_result->data_get() : $${resdatavar}_result);
         $this->assertNotNull($${resdatavar});
 `)
   if (hasEntIdU) {
@@ -532,7 +534,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
             "id" => $${srcdatavar}["id"],
         ];
         $${datavar}_loaded = $${entvar}->load($${matchvar}, null);
-        $${datavar}_load_result = Helpers::to_map($${datavar}_loaded);
+        $${datavar}_load_result = Helpers::to_map(is_object($${datavar}_loaded) && method_exists($${datavar}_loaded, 'data_get') ? $${datavar}_loaded->data_get() : $${datavar}_loaded);
         $this->assertNotNull($${datavar}_load_result);
         $this->assertEquals($${datavar}_load_result["id"], $${srcdatavar}["id"]);
 `)

package/project/.sdk/src/cmp/php/fragment/Entity.fragment.php

@@ -277,6 +277,25 @@ class EntyClass
 
         $post_done();
 
-        return ($utility->done)($ctx);
+        $out = ($utility->done)($ctx);
+
+        // An operation resolves to the ENTITY, not the raw data. Entities are
+        // stateful: post_done has just absorbed resdata/resmatch into this
+        // instance, and the caller reaches the record through data(). Two
+        // structural exceptions: `list` resolves to the ARRAY of entity
+        // instances make_result built, and a failed op with throwing disabled
+        // hands back the error payload unchanged. `remove` additionally marks
+        // the entity deleted; it KEEPS its data, so a caller can still read
+        // what was removed. See AGENTS.md "Entity operations return ENTITIES".
+        $opname = $ctx->op === null ? null : $ctx->op->name;
+
+        if ($ctx->result !== null && $ctx->result->ok && $opname !== 'list') {
+            if ($opname === 'remove') {
+                $this->markDeleted();
+            }
+            return $this;
+        }
+
+        return $out;
     }
 }

package/project/.sdk/src/cmp/php/fragment/SdkError.fragment.php

@@ -9,6 +9,12 @@ class ProjectNameError extends \Exception
     public string $msg;
     public string $sdk;
 
+    // HTTP status of the response that caused this error, or -1 when the
+    // request never got one. PROMOTED to the top level: it used to be
+    // reachable only at `err->result->status`, so every consumer coupled
+    // itself to the internal shape of `result`.
+    public int $status = -1;
+
     public function __construct(string $code = "", string $msg = "")
     {
         parent::__construct($msg);
@@ -17,6 +23,11 @@ class ProjectNameError extends \Exception
         $this->sdk = "ProjectName";
     }
 
+    public function notFound(): bool
+    {
+        return 404 === $this->status;
+    }
+
     public function error(): string
     {
         return "{$this->sdk}: {$this->code}: {$this->msg}";

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

@@ -6,7 +6,8 @@ import {
   collectDeps,
   pkgDescription,
   keywords,
-  repoInfo,
+  repoInfo, packageName,
+  packageVersion
 } from '@voxgig/sdkgen'
 
 
@@ -26,7 +27,7 @@ const Package = cmp(async function Package(props: any) {
   // package (the `${model.name}_sdk/` dir) is unchanged.
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
-  const distName = `${ns}-${pkgBase}`
+  const distName = packageName(model, 'py')
   const { repoUrl, issuesUrl } = repoInfo(model)
   const kw = keywords(model).map((k) => `"${k}"`).join(', ')
 
@@ -37,7 +38,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "${distName}"
-version = "0.0.1"
+version = "${packageVersion(model, target.name)}"
 description = "${pkgDescription(model, 'py')}"
 readme = "README.md"
 license = "MIT"

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -25,6 +25,17 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
 // methods with optional ctrl. The op descriptions are language-agnostic.
+// A `list()` on a NESTED entity needs its parent path params. The
+// quickstart used to emit `client.Moon().list()` for an entity at
+// `/planet/{planet_id}/moon`, which 404s against a live server from a
+// half-built URL — indistinguishable from "no such record". The model
+// already marks those params `reqd: true`; matchArg renders exactly them.
+function listMatchArg(ent: any): string {
+  const idF = entityIdField(ent)
+  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
 const OP_DESC: Record<string, { method: string, desc: string }> = {
   load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
   list:   { method: 'list()',        desc: 'List entities, optionally matching the given criteria.' },
@@ -138,7 +149,7 @@ ${eVar} = client.${entity.Name}().load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`python
-${eVar}s = client.${entity.Name}().list()
+${eVar}s = client.${entity.Name}().list(${listMatchArg(entity)})
 \`\`\`
 
 `)

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

@@ -54,7 +54,8 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // The op-driven test-mode line, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
   const testModeExample = primaryOp
-    ? `# Entity ops return the bare record and raise on error.
+    ? `# Entity ops return the ENTITY and raises on error;
+// call data_get() for the record.
 ${eVar} = client.${eName}().${primaryOp}(${testArg})
 # ${eVar} contains the mock response record`
     : `result = client.direct({"path": "/api/resource", "method": "GET"})

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

@@ -94,7 +94,7 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result data (a \`dict\` for single-entity
+Entity operations return the ENTITY (call data_get() for the record) (a \`dict\` for single-entity
 ops, a \`list\` for \`list\`) and raise on error. Wrap calls in
 \`try\`/\`except\` to handle failures.
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,17 @@ import {
 } from '@voxgig/apidef'
 
 
+// A `list()` on a NESTED entity needs its parent path params. The
+// quickstart used to emit `client.Moon().list()` for an entity at
+// `/planet/{planet_id}/moon`, which 404s against a live server from a
+// half-built URL — indistinguishable from "no such record". The model
+// already marks those params `reqd: true`; matchArg renders exactly them.
+function listMatchArg(ent: any): string {
+  const idF = entityIdField(ent)
+  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -78,7 +89,7 @@ error — iterate it directly.
 
 \`\`\`python
 try:
-    ${eVar}s = client.${eName}().list()
+    ${eVar}s = client.${eName}().list(${listMatchArg(exampleEntity)})
     for ${eVar} in ${eVar}s:
         print(${eVar})
 except Exception as err:
@@ -111,7 +122,7 @@ except Exception as err:
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record (a \`dict\`) and raises on error.
+\`load()\` returns the ENTITY — call data_get() for the record — and raises on error.
 
 \`\`\`python
 try:
@@ -139,7 +150,7 @@ except Exception as err:
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record (a \`dict\`) and raises on error.
+\`load()\` returns the ENTITY — call data_get() for the record — and raises on error.
 
 \`\`\`python
 try:
@@ -180,7 +191,7 @@ except Exception as err:
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `created["${dataIdF}"]`
+      ? `created.data_get()["${dataIdF}"]`
       : pyLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
@@ -189,7 +200,7 @@ except Exception as err:
 \`\`\`python
 `)
       if (opnames.includes('create')) {
-        Content(`# Create — returns the bare created record (a dict)
+        Content(`# Create — returns the ENTITY (call data_get() for the record)
 created = client.${eName}().create({${examplePairs('create').join(', ')}})
 
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -20,6 +20,17 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
+// A `list()` on a NESTED entity needs its parent path params. The
+// quickstart used to emit `client.Moon().list()` for an entity at
+// `/planet/{planet_id}/moon`, which 404s against a live server from a
+// half-built URL — indistinguishable from "no such record". The model
+// already marks those params `reqd: true`; matchArg renders exactly them.
+function listMatchArg(ent: any): string {
+  const idF = entityIdField(ent)
+  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, ctrl=None) -> dict',
@@ -253,7 +264,7 @@ ${info.desc}
 
 `)
 
-          // Show example. Entity ops return the bare result and raise on
+          // Show example. Entity ops return the ENTITY and raise on
           // error; direct() is the only method that returns a result dict.
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
@@ -276,7 +287,7 @@ result = client.${ent.Name}().${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`python
-results = client.${ent.Name}().list()
+results = client.${ent.Name}().list(${listMatchArg(ent)})
 for ${eVar} in results:
     print(${eVar})
 \`\`\`

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -22,6 +22,17 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
+// A `list()` on a NESTED entity needs its parent path params. The
+// quickstart used to emit `client.Moon().list()` for an entity at
+// `/planet/{planet_id}/moon`, which 404s against a live server from a
+// half-built URL — indistinguishable from "no such record". The model
+// already marks those params `reqd: true`; matchArg renders exactly them.
+function listMatchArg(ent: any): string {
+  const idF = entityIdField(ent)
+  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -56,7 +67,7 @@ client = ${ctor}
 
     if (opnames.includes('list')) {
       Content(`# List all ${eName.toLowerCase()}s (returns a list, raises on error)
-${eVar}s = client.${eName}().list()
+${eVar}s = client.${eName}().list(${listMatchArg(exampleEntity)})
 for ${eVar} in ${eVar}s:
     print(${eVar})
 `)

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

@@ -11,7 +11,7 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -60,7 +60,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const target = props.target
   const entity: ModelEntity = props.entity
 
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJECTNAME = envName(model)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -128,7 +128,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     ? loadParams.map((p: any) => `            params["${p.name}"] = ${JSON.stringify(p.example)}`).join('\n')
     : ''
 
-  const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
+  const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
   File({ name: 'test_' + entity.name + '_direct.' + target.ext }, () => {