@voxgig/sdkgen 2.0.1 → 3.0.0

package/project/.sdk/src/cmp/haskell/ReadmeModel_haskell.ts

@@ -21,11 +21,11 @@ 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: '| `eLoad` | `Value -> Value -> IO Value` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `eList` | `Value -> Value -> IO Value` | List entities matching the criteria. Raises on error. |',
-    create: '| `eCreate` | `Value -> Value -> IO Value` | Create a new entity. Raises on error. |',
-    update: '| `eUpdate` | `Value -> Value -> IO Value` | Update an existing entity. Raises on error. |',
-    remove: '| `eRemove` | `Value -> Value -> IO Value` | Remove an entity. Raises on error. |',
+    load: '| `eLoad` | `Value -> Value -> IO Entity` | Load a single entity by match criteria. Resolves to the entity. Raises on error. |',
+    list: '| `eList` | `Value -> Value -> IO [Entity]` | List entities matching the criteria. Resolves to one entity per record. Raises on error. |',
+    create: '| `eCreate` | `Value -> Value -> IO Entity` | Create a new entity. Resolves to the entity. Raises on error. |',
+    update: '| `eUpdate` | `Value -> Value -> IO Entity` | Update an existing entity. Resolves to the entity. Raises on error. |',
+    remove: '| `eRemove` | `Value -> Value -> IO Entity` | Remove an entity. Resolves to the entity, marked deleted. Raises on error. |',
   }
   const opRows = ['load', 'list', 'create', 'update', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
@@ -103,9 +103,11 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the bare result \`Value\` (a map for single-entity
-ops, a list for \`eList\`) and raise on error. Wrap calls in
-\`Control.Exception.try\` to handle failures.
+Entity operations resolve to the ENTITY, not the raw record \u2014 \`eList\` to
+one entity per record \u2014 and raise on error. The record is reached through
+\`eDataGet\`, which returns the entity's data container. \`eRemove\` resolves to
+the entity marked deleted (\`eDeleted\`); it keeps the data it held. Wrap calls
+in \`Control.Exception.try\` to handle failures.
 
 The \`direct\` escape hatch never raises — it returns a result \`Value\`
 you branch on via its \`ok\` field (read with \`getp result "ok"\`):

package/project/.sdk/src/cmp/haskell/ReadmeQuick_haskell.ts

@@ -90,14 +90,15 @@ to recover from failures.
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`eList ent match ctrl\` returns a list \`Value\` and raises on error.
+\`eList ent match ctrl\` resolves to one ENTITY per record and raises on
+error. Read a record with \`eDataGet\`.
 
 \`\`\`haskell
   ent <- Sdk.${eFn} sdk VNoval
   match <- emptyMap
   ctrl <- emptyMap
   ${eFn}s <- Sdk.eList ent match ctrl
-  print ${eFn}s
+  mapM_ (\\en -> print =<< Sdk.eDataGet en) ${eFn}s
 \`\`\`
 
 `)
@@ -123,14 +124,15 @@ to recover from failures.
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`eLoad\` returns the bare record and raises on error.
+\`eLoad\` resolves to the ENTITY and raises on error; \`eDataGet\` gives the
+record.
 
 \`\`\`haskell
   ${neFn}Ent <- Sdk.${neFn} sdk VNoval
   m <- jo [${neMatch.join(', ')}]
   ctrl2 <- emptyMap
   ${neFn} <- Sdk.eLoad ${neFn}Ent m ctrl2
-  print ${neFn}
+  print =<< Sdk.eDataGet ${neFn}
 \`\`\`
 
 `)
@@ -148,14 +150,15 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`eLoad ent match ctrl\` returns the bare record and raises on error.
+\`eLoad ent match ctrl\` resolves to the ENTITY and raises on error;
+\`eDataGet\` gives the record.
 
 \`\`\`haskell
   ent2 <- Sdk.${eFn} sdk VNoval
   m <- jo ${loadArg}
   ctrl2 <- emptyMap
   ${eFn} <- Sdk.eLoad ent2 m ctrl2
-  print ${eFn}
+  print =<< Sdk.eDataGet ${eFn}
 \`\`\`
 
 `)
@@ -192,7 +195,7 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
   d <- jo [${examplePairs('create').join(', ')}]
   cctrl <- emptyMap
   created <- Sdk.eCreate createEnt d cctrl
-  print created
+  print =<< Sdk.eDataGet created
 \`\`\`
 
 `)
@@ -204,7 +207,7 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
   upd <- jo [${updatePairs.join(', ')}]
   uctrl <- emptyMap
   updated <- Sdk.eUpdate updateEnt upd uctrl
-  print updated
+  print =<< Sdk.eDataGet updated
 \`\`\`
 
 `)
@@ -221,8 +224,9 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
   removeEnt <- Sdk.${eFn} sdk VNoval
   rm <- jo [${removePairs.length ? removePairs.join(', ') : ''}]
   rctrl <- emptyMap
-  _ <- Sdk.eRemove removeEnt rm rctrl
-  return ()
+  -- Resolves to the entity, marked deleted; it keeps the data it held.
+  removed <- Sdk.eRemove removeEnt rm rctrl
+  print =<< readIORef (Sdk.eDeleted removed)
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/haskell/ReadmeRef_haskell.ts

@@ -33,29 +33,29 @@ function hsType(type: any): string {
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'eLoad ent match ctrl :: IO Value',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    sig: 'eLoad ent match ctrl :: IO Entity',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Resolves to the ENTITY (read the record with `eDataGet`) and raises on error.',
   },
   list: {
-    sig: 'eList ent match ctrl :: IO Value',
-    returns: 'a list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — pass an empty map to list all records. Returns a list `Value` and raises on error.',
+    sig: 'eList ent match ctrl :: IO [Entity]',
+    returns: 'one entity per record',
+    desc: 'List entities matching the given criteria. The match is optional \u2014 pass an empty map to list all records. Resolves to one ENTITY per record and raises on error.',
   },
   create: {
-    sig: 'eCreate ent data ctrl :: IO Value',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    sig: 'eCreate ent data ctrl :: IO Entity',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Resolves to the ENTITY (read the record with `eDataGet`) and raises on error.',
   },
   update: {
-    sig: 'eUpdate ent data ctrl :: IO Value',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+    sig: 'eUpdate ent data ctrl :: IO Entity',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the ENTITY (read the record with `eDataGet`) and raises on error.',
   },
   remove: {
-    sig: 'eRemove ent match ctrl :: IO Value',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    sig: 'eRemove ent match ctrl :: IO Entity',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Resolves to the ENTITY, marked deleted (`eDeleted`); it keeps the data it held. Raises on error.',
   },
 }
 
@@ -278,7 +278,8 @@ ${info.desc}
   ent <- Sdk.${eFn} sdk VNoval
   match <- emptyMap
   ctrl <- emptyMap
-  results <- Sdk.eList ent match ctrl
+  results <- Sdk.eList ent match ctrl   -- one ENTITY per record
+  datas <- mapM Sdk.eDataGet results
 \`\`\`
 
 `)
@@ -297,7 +298,8 @@ ${info.desc}
             })
             Content(`]
   ctrl <- emptyMap
-  result <- Sdk.eCreate ent d ctrl
+  result <- Sdk.eCreate ent d ctrl   -- the ENTITY
+  d2 <- Sdk.eDataGet result
 \`\`\`
 
 `)
@@ -318,7 +320,8 @@ ${info.desc}
     [${updateLines}
     ]  -- fields to update
   ctrl <- emptyMap
-  result <- Sdk.eUpdate ent d ctrl
+  result <- Sdk.eUpdate ent d ctrl   -- the ENTITY
+  d2 <- Sdk.eDataGet result
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/haskell/ReadmeTopQuick_haskell.ts

@@ -63,12 +63,12 @@ main = do
 
     if (opnames.includes('list')) {
       Content(`
-  -- List all ${eName.toLowerCase()}s (returns a list Value, raises on error)
+  -- List all ${eName.toLowerCase()}s (one ENTITY per record, raises on error)
   ent <- Sdk.${eFn} sdk VNoval
   match <- emptyMap
   ctrl <- emptyMap
   ${eFn}s <- Sdk.eList ent match ctrl
-  print ${eFn}s
+  mapM_ (\\en -> print =<< Sdk.eDataGet en) ${eFn}s
 `)
     }
 
@@ -83,12 +83,12 @@ main = do
             it.name === idF ? 'example_id' : 'example_' + it.name)})`).join(', ')}]`
         : '[]'
       Content(`
-  -- Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+  -- Load a specific ${eName.toLowerCase()} (returns the ENTITY, raises on error)
   ent2 <- Sdk.${eFn} sdk VNoval
   m <- jo ${loadArg}
   ctrl2 <- emptyMap
   ${eFn} <- Sdk.eLoad ent2 m ctrl2
-  print ${eFn}
+  print =<< Sdk.eDataGet ${eFn}
 `)
     }
   }

package/project/.sdk/src/cmp/haskell/Test_haskell.ts

@@ -81,7 +81,10 @@ ${basicFn} c = do
     ent <- C.${fn} sdk VNoval
     em1 <- emptyMap; em2 <- emptyMap
     lst <- eList ent em1 em2
-    pure (islist lst)
+    -- \`list\` resolves to one ENTITY per record; the record is reached
+    -- through eDataGet. See AGENTS.md "Entity operations return ENTITIES".
+    ok <- mapM (\\en -> ismap <$> eDataGet en) lst
+    pure (all id ok)
 `
         }
         if (hasLoad) {
@@ -95,8 +98,9 @@ ${basicFn} c = do
       (id0 : _) -> do
         m <- jo [("id", VStr id0)]; ctrl <- emptyMap
         loaded <- eLoad ent m ctrl
-        lid <- getp loaded "id"
-        pure (ismap loaded && vstring lid == id0)
+        ld <- eDataGet loaded
+        lid <- getp ld "id"
+        pure (ismap ld && vstring lid == id0)
 `
         }
         if (hasCreate) {
@@ -106,8 +110,9 @@ ${basicFn} c = do
     d <- newRefData fixture "${e.name}"
     ctrl <- emptyMap
     created <- eCreate ent d ctrl
-    cid <- getp created "id"
-    pure (ismap created && not (isNoval cid))
+    cd <- eDataGet created
+    cid <- getp cd "id"
+    pure (ismap cd && not (isNoval cid))
 `
         }
         if (hasCreate && hasUpdate) {
@@ -117,12 +122,14 @@ ${basicFn} c = do
     d <- newRefData fixture "${e.name}"
     ctrl <- emptyMap
     created <- eCreate ent d ctrl
-    cid <- getp created "id"
+    cd <- eDataGet created
+    cid <- getp cd "id"
     upd <- jo [("id", cid), ("${updField}", VStr "UpdatedMark")]
     ctrl2 <- emptyMap
     updated <- eUpdate ent upd ctrl2
-    uv <- getp updated "${updField}"
-    pure (ismap updated && vstring uv == "UpdatedMark")
+    ud <- eDataGet updated
+    uv <- getp ud "${updField}"
+    pure (ismap ud && vstring uv == "UpdatedMark")
 `
         }
         if (hasCreate && hasRemove) {
@@ -132,10 +139,15 @@ ${basicFn} c = do
     d <- newRefData fixture "${e.name}"
     ctrl <- emptyMap
     created <- eCreate ent d ctrl
-    cid <- getp created "id"
+    cd <- eDataGet created
+    cid <- getp cd "id"
     rm <- jo [("id", cid)]; ctrl2 <- emptyMap
-    _ <- eRemove ent rm ctrl2
-    pure True
+    -- \`remove\` resolves to the entity, marked. It KEEPS the data it held.
+    removed <- eRemove ent rm ctrl2
+    gone <- readIORef (eDeleted removed)
+    rd <- eDataGet removed
+    rid <- getp rd "id"
+    pure (gone && vstring rid == vstring cid)
 `
         }
         // An op-less entity (no list/load/create — e.g. a bare path entity)

package/project/.sdk/src/cmp/java/Package_java.ts

@@ -4,6 +4,7 @@ import {
   File,
   cmp,
   collectDeps,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -51,7 +52,7 @@ const Package = cmp(async function Package(props: any) {
 
   <groupId>${groupId}</groupId>
   <artifactId>${artifactId}</artifactId>
-  <version>0.0.1</version>
+  <version>${packageVersion(model, target.name)}</version>
   <name>${model.const.Name} SDK</name>
   <description>${model.const.Name} client SDK for Java (generated by @voxgig/sdkgen).</description>
 

package/project/.sdk/src/cmp/java/ReadmeHowto_java.ts

@@ -51,7 +51,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() for the record.
 Object ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null);
 // ${eVar} holds the mock response record
 System.out.println(${eVar});`

package/project/.sdk/src/cmp/java/ReadmeInstall_java.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isPublished, repoInfo } from '@voxgig/sdkgen'
+import { cmp, Content, isPublished, repoInfo, packageVersion } from '@voxgig/sdkgen'
 
 import { mavenGroupId } from './utility_java'
 
@@ -18,7 +18,7 @@ const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
 <dependency>
   <groupId>${groupId}</groupId>
   <artifactId>${artifactId}</artifactId>
-  <version>0.0.1</version>
+  <version>${packageVersion(model, target.name)}</version>
 </dependency>
 \`\`\`
 

package/project/.sdk/src/cmp/java/ReadmeModel_java.ts

@@ -93,7 +93,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, an aggregate \`List\` for \`list\`) as \`Object\` and raise on error. Wrap
 calls in \`try\`/\`catch\` to handle failures.
 

package/project/.sdk/src/cmp/java/ReadmeQuick_java.ts

@@ -123,7 +123,7 @@ catch (RuntimeException err) {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record (as \`Object\`) and raises on error.
+\`load()\` returns the ENTITY — call data() for the record — and raises on error.
 
 \`\`\`java
 try {
@@ -151,7 +151,7 @@ catch (RuntimeException err) {
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record (as \`Object\`) and raises on error.
+\`load()\` returns the ENTITY — call data() for the record — and raises on error.
 
 \`\`\`java
 try {
@@ -191,7 +191,7 @@ catch (RuntimeException err) {
 \`\`\`java
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record (as Object)
+        Content(`// Create — returns the ENTITY (call data() for the record)
 Object created = client.${accessor}(null).create(Map.of(${examplePairs('create').join(', ')}), null);
 
 `)

package/project/.sdk/src/cmp/java/TestDirect_java.ts

@@ -11,7 +11,7 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -70,7 +70,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const entity: ModelEntity = props.entity
   const javapackage: string = props.javapackage
 
-  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJECTNAME = envName(model)
   const SDK = model.const.Name + 'SDK'
 
   const authActive = isAuthActive(model)
@@ -132,7 +132,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     : ''
 
   // Build the ENTID env var name for this entity
-  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/java/TestEntity_java.ts

@@ -17,7 +17,7 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
-  isAuthActive,
+  isAuthActive, envName, envToken
 } from '@voxgig/sdkgen'
 
 
@@ -58,8 +58,8 @@ const TestEntity = cmp(function TestEntity(props: any) {
     return
   }
 
-  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 entidEnvVar = `${PROJUPPER}_TEST_${ENTUPPER}_ENTID`
 
   const SDK = model.const.Name + 'SDK'
@@ -339,7 +339,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
   Content(`
     Object ${datavar}Result = ${entvar}.create(${datavar}, null);
-    ${datavar} = Helpers.toMapAny(${datavar}Result);
+    ${datavar} = Helpers.toMapAny(${datavar}Result instanceof SdkEntity ? ((SdkEntity) ${datavar}Result).data() : ${datavar}Result);
     assertNotNull(${datavar}, "expected create result to be a map");
 `)
   if (null != ctx.entity.id) {
@@ -479,7 +479,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
   Content(`
     Object ${resdatavar}Result = ${entvar}.update(${datavar}Up, null);
-    Map<String, Object> ${resdatavar} = Helpers.toMapAny(${resdatavar}Result);
+    Map<String, Object> ${resdatavar} = Helpers.toMapAny(${resdatavar}Result instanceof SdkEntity ? ((SdkEntity) ${resdatavar}Result).data() : ${resdatavar}Result);
     assertNotNull(${resdatavar}, "expected update result to be a map");
 `)
   if (hasEntIdU) {
@@ -546,7 +546,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
   if (hasEntId) {
     Content(`    ${matchvar}.put("id", ${srcdatavar}.get("id"));
     Object ${datavar}Loaded = ${entvar}.load(${matchvar}, null);
-    Map<String, Object> ${datavar}LoadResult = Helpers.toMapAny(${datavar}Loaded);
+    Map<String, Object> ${datavar}LoadResult = Helpers.toMapAny(${datavar}Loaded instanceof SdkEntity ? ((SdkEntity) ${datavar}Loaded).data() : ${datavar}Loaded);
     assertNotNull(${datavar}LoadResult, "expected load result to be a map");
     assertEquals(${srcdatavar}.get("id"), ${datavar}LoadResult.get("id"),
         "expected load result id to match");

package/project/.sdk/src/cmp/java/fragment/EntityBase.fragment.java

@@ -34,6 +34,20 @@ public abstract class EntityBase implements SdkEntity {
   protected Map<String, Object> match = new LinkedHashMap<>();
   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 boolean deleted = false;
+
+  public void markDeleted() {
+    this.deleted = true;
+  }
+
+  public boolean deleted() {
+    return this.deleted;
+  }
+
+
   protected EntityBase(String name, SdkClient client, Map<String, Object> entopts) {
     if (entopts == null) {
       entopts = new LinkedHashMap<>();
@@ -127,7 +141,26 @@ public abstract class EntityBase implements SdkEntity {
 
       postDone.run();
 
-      return utility.done.apply(ctx);
+      Object out = utility.done.apply(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".
+      String opname = ctx.op == null ? null : ctx.op.name;
+
+      if (ctx.result != null && ctx.result.ok && !"list".equals(opname)) {
+        if ("remove".equals(opname)) {
+          this.markDeleted();
+        }
+        return this;
+      }
+
+      return out;
     }
     catch (RuntimeException err) {
       // An error already finalised by makeError (e.g. via done) must not

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

@@ -13,6 +13,18 @@ public class SdkError extends RuntimeException {
   public transient Object result;
   public transient Object spec;
 
+  /**
+   * 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 boolean notFound() {
+    return 404 == this.status;
+  }
+
   public SdkError(String code, String msg, Context ctx) {
     super(msg);
     this.code = code == null ? "" : code;

package/project/.sdk/src/cmp/js/Main_js.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
-  entityClassName, entityCollection,
+  entityClassName, entityCollection, srcFeatureExcludes,
 } from '@voxgig/sdkgen'
 
 
@@ -43,6 +43,9 @@ const Main = cmp(async function Main(props: any) {
 
   Copy({
     from: 'tm/' + target.name,
+    // Root copies src/feature/<name>/ per ACTIVE feature; keep this blanket
+    // copy from restoring one that was switched off after `target add`.
+    exclude: srcFeatureExcludes(model),
     replace: {
       ...props.ctx$.stdrep,
     }

package/project/.sdk/src/cmp/js/Package_js.ts

@@ -11,6 +11,7 @@ import {
   repoInfo,
   PUBLISHER,
   PUBLISHER_URL,
+  packageVersion,
 } from '@voxgig/sdkgen'
 
 
@@ -56,7 +57,7 @@ const Package = cmp(async function Package(props: any) {
     // The ts target publishes the canonical scoped npm name; the js target
     // appends `-js` so the two never collide on npm.
     name: packageName(model, 'js'),
-    version: `0.0.1`,
+    version: packageVersion(model, target.name),
     description: pkgDescription(model, target.name),
     keywords: keywords(model),
     homepage: `${repoUrl}#readme`,
@@ -64,6 +65,11 @@ const Package = cmp(async function Package(props: any) {
     bugs: { url: issuesUrl },
     main: `src/${SdkName}SDK.js`,
     type: 'commonjs',
+
+    // What actually ships. Without `files`, `npm publish` packs the test
+    // suite and the build scaffolding too. The js target runs from `src`
+    // directly (no build step), so that is the whole package.
+    files: ['src'],
     scripts: {
       'test': 'node --test \'test/**/*.test.js\'',
       'test-some': 'node --experimental-test-isolation=none ' +

package/project/.sdk/src/cmp/js/ReadmeEntity_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -12,6 +12,17 @@ import { exampleValue } from './utility_js'
 // 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('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(match)',   desc: 'List entities matching the criteria.' },
@@ -124,7 +135,7 @@ const ${eVar} = await client.${entity.Name}().load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`ts
-const ${eVar}s = await client.${entity.Name}().list()
+const ${eVar}s = await client.${entity.Name}().list(${listMatchArg(entity)})
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/js/ReadmeHowto_js.ts

@@ -62,7 +62,8 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // and omits the stateful section (there is no op to retain state across).
   const testModeExample = primaryOp
     ? `const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
-// ${eVar} is a bare entity populated with mock response data
+// ${eVar} is the entity, populated with mock response data
+// — call ${eVar}.data() for the record itself
 console.log(${eVar})`
     : `const result = await client.direct({ path: '/api/resource', method: 'GET' })
 console.log(result)`

package/project/.sdk/src/cmp/js/ReadmeQuick_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityOps, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityOps, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,6 +10,17 @@ import {
 import { exampleValue } from './utility_js'
 
 
+// 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
 
@@ -98,7 +109,7 @@ console.log(${eVar})
 ### List ${eName} Records
 
 \`\`\`js
-const ${eVar}s = await client.${eName}().list()
+const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
 for (const ${eVar} of ${eVar}s) {
   console.log(${eVar})
 }