@voxgig/sdkgen 2.0.2 → 3.1.0

package/project/.sdk/src/cmp/csharp/TestEntity_csharp.ts

@@ -17,7 +17,7 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -54,8 +54,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
   }
 
   const Name = model.const.Name
-  const PROJUPPER = nom(model.const, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
-  const ENTUPPER = entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJUPPER = envName(model)
+  const ENTUPPER = envToken(entity.name)
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
@@ -358,7 +358,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
   Content(`
         var ${datavar}Result = ${entvar}.Create(${datavar}, null);
-        ${datavar} = Helpers.ToMapAny(${datavar}Result);
+        ${datavar} = Helpers.ToMapAny(${datavar}Result is IEntity ce ? ce.Data() : ${datavar}Result);
         Assert.True(${datavar} != null, "expected create result to be a map");
 `)
   if (null != ctx.entity.id) {
@@ -500,7 +500,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
   Content(`
         var ${resdatavar}Result = ${entvar}.Update(${datavar}Up, null);
-        var ${resdatavar} = Helpers.ToMapAny(${resdatavar}Result);
+        var ${resdatavar} = Helpers.ToMapAny(${resdatavar}Result is IEntity ue ? ue.Data() : ${resdatavar}Result);
         Assert.True(${resdatavar} != null, "expected update result to be a map");
 `)
   if (hasEntIdU) {
@@ -569,7 +569,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
             ["id"] = ${srcdatavar}!["id"],
         };
         var ${datavar}Loaded = ${entvar}.Load(${matchvar}, null);
-        var ${datavar}LoadResult = Helpers.ToMapAny(${datavar}Loaded);
+        var ${datavar}LoadResult = Helpers.ToMapAny(${datavar}Loaded is IEntity le ? le.Data() : ${datavar}Loaded);
         Assert.True(${datavar}LoadResult != null, "expected load result to be a map");
         Assert.True(StructRunner.DeepEqual(${datavar}LoadResult!["id"], ${srcdatavar}["id"]),
             "expected load result id to match");

package/project/.sdk/src/cmp/csharp/fragment/EntityBase.fragment.cs

@@ -19,6 +19,22 @@ public abstract class ProjectNameEntityBase : IEntity
     protected Dictionary<string, object?> match = new();
     protected Context entctx;
 
+    // Every operation resolves to the entity; `remove` additionally marks
+    // it. The instance KEEPS the data it held — a caller can still read what
+    // was deleted — but it is no longer a live record. See AGENTS.md.
+    private bool _deleted = false;
+
+    public void MarkDeleted()
+    {
+        this._deleted = true;
+    }
+
+    public bool Deleted()
+    {
+        return this._deleted;
+    }
+
+
     protected ProjectNameEntityBase(ProjectNameSDK client,
         Dictionary<string, object?>? entopts, string name)
     {
@@ -167,7 +183,28 @@ public abstract class ProjectNameEntityBase : IEntity
 
         postDone();
 
-        return utility.Done(ctx);
+        var outv = utility.Done(ctx);
+
+        // An operation resolves to the ENTITY, not the raw data. Entities are
+        // stateful: postDone 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 MakeResult 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".
+        var opname = ctx.Op?.Name;
+
+        if (ctx.Result != null && ctx.Result.Ok && "list" != opname)
+        {
+            if ("remove" == opname)
+            {
+                this.MarkDeleted();
+            }
+            return this;
+        }
+
+        return outv;
     }
 
     // Streaming operations. Runs `action` through the full pipeline and returns

package/project/.sdk/src/cmp/csharp/fragment/Main.fragment.cs

@@ -8,6 +8,15 @@ namespace ProjectNameSdk;
 
 public class ProjectNameSDK
 {
+    // NOTE: type references in EXPRESSION position are `global::`-qualified
+    // throughout this class. Entity accessors are PascalCase methods declared
+    // on it (see MainEntity_csharp), so an entity named `utility` declares
+    // `Utility(...)` here and C# then resolves the simple name `Utility` in an
+    // expression to the METHOD, not the type: "'X.Utility(...)' is a method,
+    // which is not valid in the given context". Qualifying makes the class
+    // immune to that whatever the API names its entities. Type POSITIONS
+    // (field and return types) are unaffected and stay unqualified.
+
     public string Mode = "live";
     private Dictionary<string, object?> _options;
     private readonly Utility _utility;
@@ -18,7 +27,7 @@ public class ProjectNameSDK
     {
         _utility = new Utility();
 
-        var config = SdkConfig.MakeConfig();
+        var config = global::ProjectNameSdk.SdkConfig.MakeConfig();
 
         _rootctx = _utility.MakeContext(new Dictionary<string, object?>
         {
@@ -31,8 +40,8 @@ public class ProjectNameSDK
 
         _options = _utility.MakeOptions(_rootctx);
 
-        if (Equals(StructUtils.GetPath(_options,
-            StructUtils.Jt("feature", "test", "active")), true))
+        if (Equals(global::Voxgig.Struct.StructUtils.GetPath(_options,
+            global::Voxgig.Struct.StructUtils.Jt("feature", "test", "active")), true))
         {
             Mode = "test";
         }
@@ -45,25 +54,25 @@ public class ProjectNameSDK
         // features (retry/cache/netsim/proxy/ratelimit) wrap whatever is
         // current, so `test` must be added before them to sit at the base of
         // the chain.
-        var featureOpts = Helpers.ToMapAny(StructUtils.GetProp(_options, "feature"))
+        var featureOpts = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(_options, "feature"))
             ?? new Dictionary<string, object?>();
-        var featureOrder = StructUtils.GetPath(_options,
-            StructUtils.Jt("__derived__", "featureorder")) as List<object?>
+        var featureOrder = global::Voxgig.Struct.StructUtils.GetPath(_options,
+            global::Voxgig.Struct.StructUtils.Jt("__derived__", "featureorder")) as List<object?>
             ?? new List<object?>();
         foreach (var fnameObj in featureOrder)
         {
             var fname = fnameObj as string ?? "";
-            var fopts = Helpers.ToMapAny(StructUtils.GetProp(featureOpts, fname));
+            var fopts = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(featureOpts, fname));
             if (fopts != null &&
                 fopts.TryGetValue("active", out var active) &&
                 active is bool ab && ab)
             {
-                _utility.FeatureAdd(_rootctx, SdkConfig.MakeFeature(fname));
+                _utility.FeatureAdd(_rootctx, global::ProjectNameSdk.SdkConfig.MakeFeature(fname));
             }
         }
 
         // Add extension features.
-        if (StructUtils.GetProp(_options, "extend") is List<object?> extList)
+        if (global::Voxgig.Struct.StructUtils.GetProp(_options, "extend") is List<object?> extList)
         {
             foreach (var f in extList)
             {
@@ -85,13 +94,13 @@ public class ProjectNameSDK
 
     public Dictionary<string, object?> OptionsMap()
     {
-        return StructUtils.Clone(_options) as Dictionary<string, object?>
+        return global::Voxgig.Struct.StructUtils.Clone(_options) as Dictionary<string, object?>
             ?? new Dictionary<string, object?>();
     }
 
     public Utility GetUtility()
     {
-        return Utility.Copy(_utility);
+        return global::ProjectNameSdk.Utility.Copy(_utility);
     }
 
     public Context GetRootCtx()
@@ -105,7 +114,7 @@ public class ProjectNameSDK
 
         fetchargs ??= new Dictionary<string, object?>();
 
-        var ctrl = Helpers.ToMapAny(StructUtils.GetProp(fetchargs, "ctrl"))
+        var ctrl = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "ctrl"))
             ?? new Dictionary<string, object?>();
 
         var ctx = utility.MakeContext(new Dictionary<string, object?>
@@ -116,23 +125,23 @@ public class ProjectNameSDK
 
         var options = _options;
 
-        var path = StructUtils.GetProp(fetchargs, "path") as string ?? "";
-        var method = StructUtils.GetProp(fetchargs, "method") as string ?? "";
+        var path = global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "path") as string ?? "";
+        var method = global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "method") as string ?? "";
         if (method == "")
         {
             method = "GET";
         }
 
-        var pathParams = Helpers.ToMapAny(StructUtils.GetProp(fetchargs, "params"))
+        var pathParams = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "params"))
             ?? new Dictionary<string, object?>();
-        var query = Helpers.ToMapAny(StructUtils.GetProp(fetchargs, "query"))
+        var query = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "query"))
             ?? new Dictionary<string, object?>();
 
         var headers = utility.PrepareHeaders(ctx);
 
-        var basev = StructUtils.GetProp(options, "base") as string ?? "";
-        var prefix = StructUtils.GetProp(options, "prefix") as string ?? "";
-        var suffix = StructUtils.GetProp(options, "suffix") as string ?? "";
+        var basev = global::Voxgig.Struct.StructUtils.GetProp(options, "base") as string ?? "";
+        var prefix = global::Voxgig.Struct.StructUtils.GetProp(options, "prefix") as string ?? "";
+        var suffix = global::Voxgig.Struct.StructUtils.GetProp(options, "suffix") as string ?? "";
 
         ctx.Spec = new Spec(new Dictionary<string, object?>
         {
@@ -144,12 +153,12 @@ public class ProjectNameSDK
             ["params"] = pathParams,
             ["query"] = query,
             ["headers"] = headers,
-            ["body"] = StructUtils.GetProp(fetchargs, "body"),
+            ["body"] = global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "body"),
             ["step"] = "start",
         });
 
         // Merge user-provided headers.
-        if (StructUtils.GetProp(fetchargs, "headers") is Dictionary<string, object?> uhm)
+        if (global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "headers") is Dictionary<string, object?> uhm)
         {
             foreach (var kv in uhm)
             {
@@ -178,13 +187,13 @@ public class ProjectNameSDK
     // Is this raw-access op permitted by the SDK's allow.op option?
     private bool OpAllowed(string op)
     {
-        return StructUtils.GetPath(_options, StructUtils.Jt("allow", "op"))
+        return global::Voxgig.Struct.StructUtils.GetPath(_options, global::Voxgig.Struct.StructUtils.Jt("allow", "op"))
             is string allow && allow.Contains(op);
     }
 
     private Dictionary<string, object?> OpDenied(string op)
     {
-        var allow = StructUtils.GetPath(_options, StructUtils.Jt("allow", "op"))
+        var allow = global::Voxgig.Struct.StructUtils.GetPath(_options, global::Voxgig.Struct.StructUtils.Jt("allow", "op"))
             as string ?? "";
         return new Dictionary<string, object?>
         {
@@ -219,7 +228,7 @@ public class ProjectNameSDK
 
         fetchargs ??= new Dictionary<string, object?>();
 
-        var ctrl = Helpers.ToMapAny(StructUtils.GetProp(fetchargs, "ctrl"))
+        var ctrl = global::ProjectNameSdk.Helpers.ToMapAny(global::Voxgig.Struct.StructUtils.GetProp(fetchargs, "ctrl"))
             ?? new Dictionary<string, object?>();
 
         var ctx = utility.MakeContext(new Dictionary<string, object?>
@@ -255,8 +264,8 @@ public class ProjectNameSDK
 
         if (fetched is Dictionary<string, object?> fm)
         {
-            var status = Helpers.ToInt(StructUtils.GetProp(fm, "status"));
-            var headers = StructUtils.GetProp(fm, "headers");
+            var status = global::ProjectNameSdk.Helpers.ToInt(global::Voxgig.Struct.StructUtils.GetProp(fm, "status"));
+            var headers = global::Voxgig.Struct.StructUtils.GetProp(fm, "headers");
 
             // No-body responses (204, 304) and explicit zero content-length
             // must skip JSON parsing - calling json() on an empty body errors.
@@ -264,12 +273,12 @@ public class ProjectNameSDK
             if (headers is Dictionary<string, object?> hm &&
                 hm.TryGetValue("content-length", out var cl) && cl != null)
             {
-                contentLength = StructUtils.Stringify(cl);
+                contentLength = global::Voxgig.Struct.StructUtils.Stringify(cl);
             }
             var noBody = status == 204 || status == 304 || contentLength == "0";
 
             object? jsonData = null;
-            if (!noBody && StructUtils.GetProp(fm, "json") is Func<object?> jf)
+            if (!noBody && global::Voxgig.Struct.StructUtils.GetProp(fm, "json") is Func<object?> jf)
             {
                 // jf() returns null on parse error in our fetcher.
                 jsonData = jf();
@@ -333,12 +342,12 @@ public class ProjectNameSDK
         // ok:false with no err — so returning early on status would discard
         // the server's own diagnostics, which are the only useful part of
         // that response.
-        var errors = StructUtils.GetPath(res, StructUtils.Jt("data", "errors"))
+        var errors = global::Voxgig.Struct.StructUtils.GetPath(res, global::Voxgig.Struct.StructUtils.Jt("data", "errors"))
             as List<object?>;
 
         if (null != errors && 0 < errors.Count)
         {
-            var msg = StructUtils.GetProp(errors[0], "message") as string;
+            var msg = global::Voxgig.Struct.StructUtils.GetProp(errors[0], "message") as string;
             if (string.IsNullOrEmpty(msg))
             {
                 msg = "graphql error";
@@ -356,14 +365,14 @@ public class ProjectNameSDK
     public static ProjectNameSDK TestSDK(Dictionary<string, object?>? testopts,
         Dictionary<string, object?>? sdkopts)
     {
-        sdkopts = StructUtils.Clone(sdkopts ?? new Dictionary<string, object?>())
+        sdkopts = global::Voxgig.Struct.StructUtils.Clone(sdkopts ?? new Dictionary<string, object?>())
             as Dictionary<string, object?> ?? new Dictionary<string, object?>();
 
-        testopts = StructUtils.Clone(testopts ?? new Dictionary<string, object?>())
+        testopts = global::Voxgig.Struct.StructUtils.Clone(testopts ?? new Dictionary<string, object?>())
             as Dictionary<string, object?> ?? new Dictionary<string, object?>();
         testopts["active"] = true;
 
-        StructUtils.SetPath(sdkopts, StructUtils.Jt("feature", "test"), testopts);
+        global::Voxgig.Struct.StructUtils.SetPath(sdkopts, global::Voxgig.Struct.StructUtils.Jt("feature", "test"), testopts);
 
         var sdk = new ProjectNameSDK(sdkopts)
         {

package/project/.sdk/src/cmp/dart/Package_dart.ts

@@ -7,6 +7,7 @@ import {
   pkgDescription,
   keywords,
   repoInfo,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -39,7 +40,7 @@ const Package = cmp(async function Package(props: any) {
     Content(`name: ${dartPackageName(model)}
 description: >-
   ${pkgDescription(model, target.name)}
-version: 0.0.1
+version: ${packageVersion(model, target.name)}
 homepage: ${repoUrl}
 repository: ${repoUrl}
 issue_tracker: ${issuesUrl}

package/project/.sdk/src/cmp/dart/ReadmeEntity_dart.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,
@@ -22,6 +22,17 @@ function dartLit(type: any, placeholder: string = 'example'): string {
 
 
 // Op method spellings + descriptions (language-agnostic wording).
+// 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('ts', 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.' },
@@ -132,7 +143,7 @@ final ${eVar} = await client.${entity.Name}().load(${loadArg});
       Content(`#### Example: List
 
 \`\`\`dart
-final ${eVar}s = await client.${entity.Name}().list();
+final ${eVar}s = await client.${entity.Name}().list(${listMatchArg(entity)});
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/dart/ReadmeHowto_dart.ts

@@ -46,7 +46,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 throw on error.
+    ? `// Entity ops return the ENTITY and throws on error;
+// call data() for the record.
 final ${eVar} = await client.${eName}().${primaryOp}(${testArg});
 // ${eVar} contains the mock response record
 print(${eVar});`

package/project/.sdk/src/cmp/dart/ReadmeInstall_dart.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isPublished, repoInfo } from '@voxgig/sdkgen'
+import { cmp, Content, isPublished, repoInfo, packageVersion } from '@voxgig/sdkgen'
 
 import { dartPackageName } from './Package_dart'
 
@@ -19,7 +19,7 @@ Or add it to your \`pubspec.yaml\`:
 
 \`\`\`yaml
 dependencies:
-  ${pkg}: ^0.0.1
+  ${pkg}: ^${packageVersion(model, target.name)}
 \`\`\`
 
 `)
@@ -39,7 +39,7 @@ dependencies:
     git:
       url: ${repoUrl}
       path: ${target.name}
-      ref: ${target.name}/v0.0.1
+      ref: ${target.name}/v${packageVersion(model, target.name)}
 \`\`\`
 
 Or depend on a local source checkout:

package/project/.sdk/src/cmp/dart/ReadmeModel_dart.ts

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

package/project/.sdk/src/cmp/dart/ReadmeQuick_dart.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,
@@ -10,6 +10,17 @@ import {
 import { dartPackageName } from './Package_dart'
 
 
+// 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('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -74,7 +85,7 @@ it and read each record's data via \`.data()\`.
 
 \`\`\`dart
 try {
-  final ${eVar}s = await client.${eName}().list();
+  final ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)});
   for (final item in ${eVar}s) {
     print(item.data());
   }
@@ -108,7 +119,7 @@ try {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record (a \`Map\`) and throws on error.
+\`load()\` returns the ENTITY — call data() for the record — and throws on error.
 
 \`\`\`dart
 try {
@@ -135,7 +146,7 @@ try {
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record (a \`Map\`) and throws on error.
+\`load()\` returns the ENTITY — call data() for the record — and throws on error.
 
 \`\`\`dart
 try {
@@ -167,7 +178,7 @@ try {
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `created['${dataIdF}']`
+      ? `created.data()['${dataIdF}']`
       : dartLit(idParamType(opname), 'example_id')
 
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
@@ -176,7 +187,7 @@ try {
 \`\`\`dart
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record (a Map)
+        Content(`// Create — returns the ENTITY (call data() for the record)
 final created = await client.${eName}().create({${examplePairs('create').join(', ')}});
 
 `)

package/project/.sdk/src/cmp/dart/ReadmeRef_dart.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,
@@ -23,6 +23,17 @@ function dartLit(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('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, [ctrl]) -> Future<dynamic>',
@@ -268,7 +279,7 @@ final result = await client.${ent.Name}().${opname}(${arg});
           }
           else if ('list' === opname) {
             Content(`\`\`\`dart
-final results = await client.${ent.Name}().list();
+final results = await client.${ent.Name}().list(${listMatchArg(ent)});
 for (final ${eVar} in results) {
   print(${eVar}.data());
 }

package/project/.sdk/src/cmp/dart/ReadmeTopQuick_dart.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,
@@ -23,6 +23,17 @@ function dartLit(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('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
+}
+
+
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -55,7 +66,7 @@ Future<void> main() async {
 
     if (opnames.includes('list')) {
       Content(`  // List all ${eName.toLowerCase()}s (returns a list of entities, throws on error)
-  final ${eVar}s = await client.${eName}().list();
+  final ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)});
   for (final item in ${eVar}s) {
     print(item.data());
   }

package/project/.sdk/src/cmp/dart/TestDirect_dart.ts

@@ -16,7 +16,7 @@ import {
   Slot,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -35,8 +35,8 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const ff = projectPath('src/cmp/dart/fragment/')
 
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
-  const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
+  const PROJECTNAME = envName(model)
+  const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive

package/project/.sdk/src/cmp/dart/TestEntity_dart.ts

@@ -23,7 +23,7 @@ import {
   Slot,
   cmp,
   each,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -50,8 +50,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
   const entity: ModelEntity = props.entity
 
-  const PROJENVNAME = nom(model.const, 'NAME').replace(/[^A-Z_]/g, '_')
-  const ENTENVNAME = nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')
+  const PROJENVNAME = envName(model)
+  const ENTENVNAME = envToken(entity.name)
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
     ? `\n    '${PROJENVNAME}_APIKEY': 'NONE',`
@@ -333,7 +333,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
   const hasEntIdC = null != entity.id
 
   Content(`
-      ${datavar} = await ${entvar}.create(${datavar});
+      ${datavar} = (await ${entvar}.create(${datavar})).data();
 `)
   if (hasEntIdC) {
     Content(`      ok(null != ${datavar}['id']);
@@ -373,7 +373,7 @@ const generateList: OpGen = (ctx, step, index) => {
   })
 
   Content(`
-      final ${listvar} = await ${entvar}.list(${matchvar});
+      final ${listvar} = (await ${entvar}.list(${matchvar})).map((e) => e.data()).toList();
 `)
   const allSteps = flow.step
   for (let vI = 0; vI < step.valid.length; vI++) {
@@ -460,7 +460,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-      final ${resdatavar} = await ${entvar}.update(${updvar});
+      final ${resdatavar} = (await ${entvar}.update(${updvar})).data();
 `)
   if (hasEntIdU) {
     Content(`      ok(${resdatavar}['id'] == ${updvar}['id']);
@@ -550,13 +550,13 @@ const generateLoad: OpGen = (ctx, step, index) => {
   if (hasEntId) {
     Content(`      final ${matchvar} = <String, dynamic>{};
       ${matchvar}['id'] = ${srcdatavar}['id'];
-      final ${datavar} = await ${entvar}.load(${matchvar});
+      final ${datavar} = (await ${entvar}.load(${matchvar})).data();
       ok(${datavar}['id'] == ${srcdatavar}['id']);
 `)
   }
   else {
     Content(`      final ${matchvar} = <String, dynamic>{};
-      final ${datavar} = await ${entvar}.load(${matchvar});
+      final ${datavar} = (await ${entvar}.load(${matchvar})).data();
       ok(null != ${datavar});
 `)
   }