@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/src/cmp/go/EntityTypes_go.ts

@@ -1,30 +1,5 @@
 
 
-// Typed-model generator (Go target).
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one file, entity/types.go, in
-// the `entity` package, with a Go `type <Name> struct { ... }` per entity plus
-// a request/match struct per active op. Field/param sentinels ($STRING,
-// $INTEGER, ...) are turned into real Go types by the shared sdkgen helper
-// `canonToType` (source of truth: @voxgig/apidef VALID_CANON).
-//
-// PORT NOTES (Go specifics vs the TS reference):
-//   * Types live in the SAME package as the entity methods (`entity`), so the
-//     generated typed accessors reference them without an import (task step B).
-//   * Go has no method overloading and go-cli / go-mcp dispatch entities
-//     dynamically through the untyped `core.ProjectNameEntity` interface
-//     (Load/List/... (map[string]any) (any, error)). That interface — and the
-//     untyped concrete methods that satisfy it — are therefore KEPT unchanged.
-//     Typed access is delivered ADDITIVELY: the op fragments emit `LoadTyped`
-//     / `ListTyped` / ... alongside the untyped methods, and Entity.fragment.go
-//     emits `DataTyped` / `MatchTyped`. All are thin typed wrappers over the
-//     untyped runtime (identical behaviour), converting at the typed boundary
-//     via the JSON-round-trip helpers emitted at the bottom of this file.
-//   * `list` typed op returns []<Name>; other typed ops return <Name>.
-//   * op WITH params -> a struct of those params (reqd:false -> pointer +
-//     ,omitempty). op WITHOUT params -> a struct mirroring the entity fields
-//     with every field optional (Go's analog of TS `Partial<Name>`).
 
 import {
   cmp, each,
@@ -47,8 +22,6 @@ function cap(s: string): string {
 }
 
 
-// A model field/param name -> an exported Go field identifier:
-//   advice -> Advice, some_field -> SomeField, id -> Id.
 function goField(name: string): string {
   const out = String(name)
     .replace(/[^A-Za-z0-9]+/g, ' ')
@@ -57,30 +30,10 @@ function goField(name: string): string {
     .filter(Boolean)
     .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
     .join('')
-  // Go identifiers can't start with a digit.
   return /^[A-Za-z_]/.test(out) ? out : 'F' + out
 }
 
 
-// The json struct tag is the WIRE CONTRACT: it decides the key requests
-// marshal under and the key responses populate from.
-//
-// Can this spec-derived name be carried in a Go json struct tag AT ALL?
-//
-// It cannot always be. `encoding/json`'s isValidTag accepts letters, digits and
-// a fixed punctuation set; a name containing a double quote, a backtick or a
-// backslash is REJECTED, and Go then silently falls back to the Go FIELD name.
-// Verified against go1.24 — for a field named `na"me`:
-//
-//   raw literal      `json:"na"me"`        -> marshals as {"na": ...}   (truncated)
-//   escaped literal  "json:\"na\\\"me\""   -> marshals as {"NaMe": ...} (tag ignored)
-//
-// So there is no encoding that preserves such a name. An earlier version here
-// stripped the offending characters, which is worse than either: it silently
-// changed the wire contract, marshalling under a key the API never uses and
-// never populating from the real response key. Names that cannot be
-// represented are skipped with a warning instead — the same treatment
-// csharp/java give names with no legal identifier form.
 const GO_TAG_PUNCT = '!#$%&()*+-./:;<=>?@[]^_{|}~ '
 
 function goTaggable(name: string): boolean {
@@ -113,15 +66,6 @@ function fieldLine(name: string, sentinel: any, optional: boolean, ident?: strin
 }
 
 
-// Collision-free Go field identifiers for one struct's members.
-//
-// goField() is lossy — it strips every non-alphanumeric character — so
-// `some_field`, `some-field` and `someField` all map to `SomeField`. Emitting
-// them into the same struct is a "field redeclared" compile error, and Go is
-// the only target exposed to it (ts/py/… keep the raw key). Later duplicates
-// get a numeric suffix; the FIRST occurrence keeps the natural name, and the
-// json tag always keeps the original wire name, so behaviour is unchanged.
-// Deterministic: members arrive in sorted-key order from opRequestShape/each.
 function uniqueGoFields(members: { name: string }[]): string[] {
   const taken: Record<string, boolean> = {}
   return members.map((m) => {
@@ -174,18 +118,8 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // collection, so inactive entities still get generated entity code that
   // references these typed names. The typed model must cover them too.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  // Emit for every entity that gets an entity file. Main_go.ts / Entity_go.ts
-  // iterate entities WITHOUT an `active` filter and reference the typed data
-  // type `<Name>` in every *_entity.go, so a struct is required for each or the
-  // package won't compile. deriveEntityNames() selects on `name` (always
-  // present) and derives the lazily-set PascalCase `Name` up front, so the
-  // struct set is deterministic and matches the *_entity.go set regardless of
-  // which component runs first.
   const entityList = deriveEntityNames(entity)
 
-  // Surface duplicate generated type names (two entities with the same
-  // PascalCase Name) — they would redeclare a type in statically-typed
-  // targets. Detection only; renaming is a model-level decision.
   warnEntityTypeCollisions(entity, log, LANG)
 
   Folder({ name: 'entity' }, () => {
@@ -194,8 +128,8 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 
       Content(`// Typed models for the ${model.const.Name} SDK.
 //
-// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
-// params (op.<name>.points[].args.params[]). Field/param types come from the
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields{} and per-op
+// params (op.<name>.points[].g.params[]). Field/param types come from the
 // canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
 // @voxgig/apidef VALID_CANON). Do not edit by hand.
 package entity
@@ -211,9 +145,8 @@ import (
       entityList.forEach((ent: any) => {
         const Name = ent.Name
         const fields = (ent.fields ? each(ent.fields) : [])
-          .filter((f: any) => f.active !== false)
+          .filter((f: any) => f.a !== false)
 
-        // Entity data model: one field per model field. req:false -> pointer.
         Content(`// ${Name} is the typed data model for the ${ent.name} entity.
 type ${Name} struct {
 `)
@@ -221,16 +154,12 @@ type ${Name} struct {
           (f: any) => skipUntaggable(f, Name, log))
         const fieldIdents = uniqueGoFields(taggable)
         taggable.forEach((f: any, i: number) => {
-          Content(fieldLine(f.name, f.type, false === f.req, fieldIdents[i]))
+          Content(fieldLine(f.n, f.t, false === f.r, fieldIdents[i]))
         })
         Content(`}
 
 `)
 
-        // Per active op: a request/match struct (same package as the entity
-        // methods, so no import is needed there). Members and their optionality
-        // come from the shared partiality policy (opRequestShape); this file
-        // only renders them as a Go struct (optional -> pointer + ,omitempty).
         const ops = ent.op || {}
         ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
           if (null == ops[opname]) {

package/project/.sdk/src/cmp/go/Entity_go.ts

@@ -19,8 +19,6 @@ const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
 
-  // Module name: concatenated lowercase
-  // Go module path == repo path on GitHub (org from model.origin).
   const gomodule = goModule(model, target.name)
 
   // Collision-free entity CLASS name (see entityClassName): normally
@@ -37,7 +35,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/go/fragment/')
 
-  // Entity files go to entity/ folder with snake_case names
   Folder({ name: 'entity' }, () => {
 
     File({ name: entity.name + '_entity.' + target.ext }, () => {
@@ -74,8 +71,6 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class/constructor tokens are decoupled from the EntityName data-type
-          // token in Entity.fragment.go so the class can be renamed independently.
           EntyClass: cls,
           NewEntyClass: 'New' + cls,
 

package/project/.sdk/src/cmp/go/Main_go.ts

@@ -53,13 +53,6 @@ const Main = cmp(async function Main(props: any) {
 
   Gitignore({})
 
-  // Copy tm/go files with replacements.
-  //
-  // Rewrite the placeholder `github.com/voxgig/struct` import (used in the
-  // template since it's a self-contained module there) to its in-SDK path.
-  // The struct package is inlined under `<gomodule>/utility/struct` so the
-  // module is fully self-contained — no external go.mod required by
-  // downstream consumers.
   Copy({
     from: 'tm/' + target.name,
     // pluginExcludes: the generate-time plugin trim (an INACTIVE plugin
@@ -76,24 +69,10 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // Typed models: entity/types.go (package entity), emitted alongside the
-  // generated *_entity.go files so the typed accessors resolve without imports.
   EntityTypes({ target })
 
-  // utility/prepare_auth.go is GENERATED, not templated: where the
-  // credential goes (header / query / cookie, and under what name) is a
-  // fact about the API, and tm/ can only hold one answer. See
-  // PrepareAuth_go.
-  //
-  // AT ROOT LEVEL, and outside the `core` Folder below. Go's layout is flat
-  // at the target root, and the component opens `utility` itself - the same
-  // path `Copy({from:'tm/go'})` used for the template it replaces. Calling
-  // it beside Config, inside `Folder({name:'core'})`, would emit
-  // core/utility/prepare_auth.go instead: a package nothing imports, while
-  // registerAll keeps binding whatever utility/ actually holds.
   PrepareAuth({ target })
 
-  // Generate main SDK file in core/ folder
   Folder({ name: 'core' }, () => {
 
     File({ name: model.name + '_sdk.' + target.ext }, () => {
@@ -121,7 +100,6 @@ s.utility.FeatureHook(s.rootctx, "${name}")
           }
         },
 
-        // Entities - injected at SLOT
         () => {
           each(entity, (entity: ModelEntity) => {
             const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -143,7 +121,6 @@ var UtilityRegistrar func(u *Utility)
 var NewBaseFeatureFunc func() Feature
 
 `)
-      // Feature constructor function vars (non-base)
       each(feature, (feat: any) => {
         if (feat.name !== 'base') {
           const fname = goFeatureName(feat)
@@ -153,7 +130,6 @@ var NewBaseFeatureFunc func() Feature
         }
       })
 
-      // Entity constructor function vars
       each(entity, (ent: any) => {
         Content(`var New${ent.Name}EntityFunc func(client *${model.const.Name}SDK, entopts map[string]any) ${model.const.Name}Entity
 
@@ -162,7 +138,6 @@ var NewBaseFeatureFunc func() Feature
     })
   })
 
-  // Generate root package file
   const hasEntities = Object.keys(entity || {}).length > 0
   const entityImport = hasEntities ? `\n\t"${gomodule}/entity"` : ''
   File({ name: model.name + '.' + target.ext }, () => {
@@ -195,13 +170,11 @@ type BaseFeature = feature.BaseFeature
 func init() {
 `)
 
-    // Register feature constructors - base is always present
     Content(`	core.NewBaseFeatureFunc = func() core.Feature {
 		return feature.NewBaseFeature()
 	}
 `)
 
-    // Register non-base feature constructors
     each(feature, (feat: any) => {
       if (feat.name !== 'base') {
         const fname = goFeatureName(feat)
@@ -212,7 +185,6 @@ func init() {
       }
     })
 
-    // Register entity constructors
     each(entity, (ent: any) => {
       Content(`	core.New${ent.Name}EntityFunc = func(client *core.${model.const.Name}SDK, entopts map[string]any) core.${model.const.Name}Entity {
 		return entity.New${entityClassName(ent, entityCollection(model))}(client, entopts)

package/project/.sdk/src/cmp/go/Package_go.ts

@@ -18,11 +18,6 @@ const Package = cmp(async function Package(props: any) {
 
   const model: Model = ctx$.model
 
-  // Module path and language version both come from the model — see
-  // goModule / goVersion. Neither is derivable from the slug alone: the repo
-  // may not be named `<slug>-sdk`, and the hardcoded `go 1.20` this used to
-  // emit could not compile sdkgen's own `log` feature (it imports log/slog,
-  // which needs 1.21).
   const gomodule = goModule(model, target.name)
 
   File({ name: 'go.mod' }, () => {
@@ -35,8 +30,6 @@ go ${goVersion(model, target.name)}
     const deps: Record<string, string> = {}
     const replaceDirs: Record<string, string> = {}
     for (const d of collectDeps(model, target.name, target.deps, ctx$.log)) {
-      // Target-level deps default to 'v0.0.0' when version is absent;
-      // feature deps require an explicit version.
       deps[d.name] = d.source === 'target' ? (d.version || 'v0.0.0') : d.version
       if (d.source === 'target' && d.raw?.replace) {
         replaceDirs[d.name] = d.raw.replace

package/project/.sdk/src/cmp/go/PrepareAuth_go.ts

@@ -18,26 +18,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. This is the go peer of PrepareAuth_ts; read that
-// one first, it carries the full account of the defect.
-//
-// This was a static file at `tm/go/utility/prepare_auth.go` that hardcoded
-//
-//   const headerAuth = "authorization"
-//
-// apidef has always resolved the scheme's `in` and `name` into
-// `main.kit.info.security` — joplin's says `in: "query", name: "token"` —
-// and generation dropped both, so the SDK sent a header the API does not
-// read and never sent the query parameter it does.
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value fixed at generation
-// time. Go makes that stricter than most targets: an unused local is a
-// COMPILE ERROR, so a file that resolved `authPrefix` and then dropped it
-// for a query placement would not build at all.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -54,16 +34,6 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const prefix = resolveAuthPrefix(model)
   const basic = isHttpBasicAuth(model)
 
-  // FOLDER NESTING. Main_go opens NO folder around this call: go's layout is
-  // flat at the target root (core/, utility/, feature/, entity/, test/), the
-  // template this replaces lived at `tm/go/utility/prepare_auth.go`, and
-  // `Copy({from:'tm/go'})` lands it at `<root>/utility/`. So the `utility`
-  // folder is opened HERE, exactly as EntityTypes_go opens `entity`.
-  //
-  // The call site matters as much: Config is inside `Folder({name:'core'})`,
-  // and putting PrepareAuth beside it would write `core/utility/prepare_auth.go`
-  // — a second `package utility` nobody imports, while the registrar keeps
-  // calling whatever `utility/` still holds. Main_go calls this at ROOT level.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({ gomodule, active, where, name, prefix, basic }))
@@ -84,9 +54,6 @@ type AuthSpec = {
 
 function render(spec: AuthSpec): string {
 
-  // NO AUTH AT ALL. A public API's SDK gets a prepareAuth that is honest
-  // about it rather than one that deletes a header nobody set. `vs` is left
-  // out of the imports deliberately — go rejects an unused import.
   if (!spec.active) {
     return `package utility
 
@@ -209,19 +176,6 @@ ${place(spec.where)}
 }
 
 
-// The credential's key, as it goes into the bag.
-//
-// A HEADER name is lowercased. HTTP header names are case-insensitive
-// (RFC 9110 5.1) and go's `req.Header.Set` canonicalises on the wire, so
-// nothing changes over the socket — but this SDK's own header map is keyed
-// in lowercase throughout (`content-type`, and the `authorization` that the
-// generated pipeline/feature/secrets tests assert on), and the shipped
-// `prepare_auth.go` said `"authorization"`. Emitting the resolver's
-// title-cased default here would have left every header SDK's own test
-// suite failing on a purely cosmetic difference.
-//
-// A QUERY parameter and a COOKIE name are case-SENSITIVE, so those go in
-// verbatim: `?token=` is not `?Token=`.
 function credLiteral(where: string, name: string): string {
   return 'header' === where ? String(name).toLowerCase() : String(name)
 }
@@ -246,9 +200,6 @@ function clear(where: string): string {
 
 function place(where: string): string {
   if ('query' === where) {
-    // NO PREFIX IN A QUERY STRING. `?token=Bearer%20abc` is not a thing any
-    // API reads; the prefix is a header convention and is dropped here
-    // deliberately rather than silently concatenated.
     return `		apikeyVal := ""
 		if av, ok := apikey.(string); ok {
 			apikeyVal = av
@@ -257,8 +208,6 @@ function place(where: string): string {
   }
 
   if ('cookie' === where) {
-    // Append, never replace: the cookie header may already carry pairs this
-    // SDK did not set, and clobbering it would drop them.
     return `		apikeyVal := ""
 		if av, ok := apikey.(string); ok {
 			apikeyVal = av
@@ -302,19 +251,6 @@ export {
 }
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING. That helper is
-// also false whenever the SPEC declares no security scheme
-// (`main.kit.info.auth: false`) — a statement about the DEFINITION, not a
-// ban on ever sending a credential. `optspec` still declares `apikey` and
-// makeOptions fills `options.auth` from its defaults, so the runtime
-// `options.auth == null` guard never fired and those SDKs have always sent
-// the credential. Gating the body on `isAuthActive` does not trim dead
-// code, it removes working authentication — which
-// `go: auth null suppresses the credential` catches, and which takes the
-// secrets feature down with it.
-//
-// `main.kit.config.auth.active: false` is the project saying "no credential,
-// ever", and it is the only signal that can be honoured before runtime.
 function isAuthActive_go(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })

package/project/.sdk/src/cmp/go/ReadmeEntity_go.ts

@@ -41,14 +41,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
   publishedEntities.map((entity: any) => {
-    // ACTIVE ops only — an inactive op generates no method, so an example
-    // calling it would not compile.
     const opnames = entityOps(entity)
-    const fields = entity.fields || []
-    // Model-driven id key: null when this entity has no id-like field.
+    const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
-    // camelCase Go identifier (a `status_embed_config` entity must not bind a
-    // snake_case Go variable, and a `type`/`range` entity not a Go keyword).
     const eVar = goVarName(entity.name)
 
     Content(`
@@ -92,8 +87,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
       each(fields, (field: any) => {
-        const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+        const desc = field.sh || ''
+        Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${desc} |
 `)
       })
 

package/project/.sdk/src/cmp/go/ReadmeExamplesTest_go.ts

@@ -6,36 +6,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits go/test/readme_examples_test.go — a COMPLETENESS GATE over every
-// ```go block in ALL THREE docs that ship go examples:
-//   - the root README.md (top-level, multi-language quick start)
-//   - the per-language go/README.md
-//   - the per-language go/REFERENCE.md
-//
-// For every ```go block, tagged by (source doc, index), it exercises the
-// block against the real generated SDK:
-//
-//   - Fragments (statement snippets) are wrapped in a function with a SEEDED
-//     test-mode `client` in scope and `go build`-checked. Any stray `import`
-//     line inside the fragment is stripped and constructor calls are rewritten
-//     to the seeded test client (so undefined-variable placeholders like
-//     sdk.TestSDK(testopts, sdkopts) still type-check). A call to a method
-//     that does not exist, a wrong argument count/type, or `.data`/`.ok` field
-//     access on a bare entity-op result fails to compile — and so fails.
-//   - Complete programs (a block with `func main`) are built as-is (the
-//     documented, possibly live, form must compile) AND a test-mode variant —
-//     its constructor rewritten to a seeded `sdk.TestSDK(...)` — is RUN with
-//     `go run`. A genuine runtime panic (nil pointer, nil map, index,
-//     interface conversion) FAILS the test; a tolerated not-found domain
-//     error does not.
-//   - Illustrative blocks are the ONLY blocks skipped, and the class is
-//     NARROW: a bare signature (a `func` line with no body) or a comment-only
-//     / `/* ... */` placeholder. Everything else must compile or run.
-//
-// Completeness: per doc, total == compiled + illustration is asserted. A block
-// that is neither compiled nor a recognized illustration — e.g. real code
-// hidden behind a `/* ... */` comment that the old logic silently skipped —
-// FAILS the gate, so no compilable example can escape the check.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { ctx$: { model } } = props
 

package/project/.sdk/src/cmp/go/ReadmeHowto_go.ts

@@ -10,7 +10,6 @@ import {
 import { goVarName } from './utility_go'
 
 
-// A type-correct Go literal for a field's canonical type.
 function goLit(type: any): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -28,7 +27,6 @@ function cap(s: string): string {
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
-  // Go module path == repo path on GitHub (org from model.origin).
   const gomodule = goModule(model, target.name)
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
@@ -40,7 +38,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // camelCase Go identifier (never snake_case or flattened lowercase,
   // never a Go keyword).
   const eLower = exampleEntity ? goVarName(exampleEntity.name) : 'entity'
-  // Model-driven id key: null when the entity has no id-like field.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'nil'

package/project/.sdk/src/cmp/go/ReadmeIntro_go.ts

@@ -37,13 +37,6 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const opList = (opNames.length ? opNames : ['list', 'load'])
     .map((o) => '`' + cap(o) + '`').join(', ')
 
-  // Sibling surfaces, MODEL-DRIVEN. This line used to hardcode "the CLI, and
-  // MCP server" — those are the `go-cli` and `go-mcp` targets, and this project
-  // has neither. So both per-language READMEs advertised surfaces nothing here
-  // generates, while the top-level Surfaces table (which does gate on active
-  // targets) listed only ts/ and go/. Name what is actually active, and drop
-  // the sentence entirely when this is the only surface, so it cannot outrun
-  // the model again.
   const targets = getModelPath(model, `main.${KIT}.target`) || {}
   const siblings = Object.entries(targets)
     .filter(([name, t]: any) => name !== target.name && false !== t.active)

package/project/.sdk/src/cmp/go/ReadmeModel_go.ts

@@ -33,9 +33,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const opRows = ['load', 'list', 'create', 'update', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
-  // Model-driven Result-shape rows: only describe the operations that
-  // actually exist. Record-returning ops (Load/Create/Update/Remove) share
-  // one row; List has its own — never name a missing op.
   const recordOps = ['load', 'create', 'update', 'remove'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o.charAt(0).toUpperCase() + o.slice(1) + '`')
   const resultRows: string[] = []
@@ -43,7 +40,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   if (opUnion.has('list')) resultRows.push('| `List` | a `[]any` of entity records |')
   const resultShapeRows = resultRows.join('\n')
 
-  // Go module path == repo path on GitHub (org from model.origin).
   const gomodule = goModule(model, target.name)
 
   const apikeyOptionRow = isAuthActive(model)
@@ -57,11 +53,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const firstWithOp = entityList.find((e: any) => entityPrimaryOp(e) != null)
   const firstPrimaryOp = firstWithOp ? entityPrimaryOp(firstWithOp) : null
   const firstEntityName = firstWithOp ? ((firstWithOp as any).Name || 'Entity') : 'Entity'
-  // camelCase Go identifier (never snake_case or flattened lowercase,
-  // never a Go keyword).
   const firstEntityVar = goVarName((firstWithOp as any)?.name || 'entity')
-  // Model-driven id key: null when the example entity has no id-like field, so
-  // the Result-shape illustration passes a nil match.
   const firstIdF = firstWithOp ? entityIdField(firstWithOp) : null
   const firstPrimaryMethod = firstPrimaryOp
     ? firstPrimaryOp.charAt(0).toUpperCase() + firstPrimaryOp.slice(1)
@@ -71,8 +63,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     ? (firstIdF ? `map[string]any{"${firstIdF}": "example_id"}` : 'nil')
     : 'map[string]any{/* fields */}'
 
-  // The Result-shape call illustration, shown only when some entity exposes an
-  // op. A direct()-only SDK (no entity ops) omits it — there is no op to call.
   const resultCallExample = firstPrimaryOp
     ? `Check \`err\` first, then use the value directly (or the typed
 \`...Typed\` variants, which return the entity's model struct and a typed
@@ -153,18 +143,17 @@ ${resultCallExample}Only \`Direct()\` returns a response envelope — a \`map[st
 
 `)
 
-  // Entities summary
   Content(`### Entities
 
 `)
   each(entityList, (ent: any) => {
-    const fields = ent.fields || []
+    const fields = Object.values(ent.fields || {})
     const opnames = Object.keys(ent.op || {})
     const ops = ent.op || {}
     const points = each(ops).map((op: any) =>
       op.points ? each(op.points) : []
     ).flat()
-    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+    const path = points.length > 0 ? (points[0] as any).o || '' : ''
 
     Content(`#### ${ent.Name}
 
@@ -172,7 +161,7 @@ ${resultCallExample}Only \`Direct()\` returns a response envelope — a \`map[st
 | --- | --- |
 `)
     each(fields, (field: any) => {
-      Content(`| \`"${field.name}"\` | ${field.short || ''} |
+      Content(`| \`"${field.n}"\` | ${field.sh || ''} |
 `)
     })
 

package/project/.sdk/src/cmp/go/ReadmeQuick_go.ts

@@ -10,16 +10,10 @@ import {
 import { exampleValue, goVarName } from './utility_go'
 
 
-// Emits the go/README.md Quickstart as ONE complete, compilable program.
-// Every entity operation returns `(value, error)` where `value` is the
-// data itself — NOT a `{ok, data, ...}` envelope (only Direct returns
-// that). So examples check `err` and use the value directly. The whole
-// program is compiled by the README snippet test (readme_examples_test.go).
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Go module path == repo path on GitHub (org from model.origin).
   const gomodule = goModule(model, target.name)
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
@@ -42,20 +36,12 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       ? `sdk.New()`
       : `sdk.New${model.const.Name}SDK(map[string]any{${goServerField}\n    })`)
 
-  // Build the body of main() from the operations the example entity
-  // supports. Each op names a fresh value var, so `:=` always declares a
-  // new variable (reusing `err`), and every var is used (printed).
   const body: string[] = []
   let usesFmt = false
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    // camelCase variable name — a `status_embed_config` entity must not bind
-    // a snake_case Go variable, and a `Type`/`Range` entity must not bind a
-    // Go keyword (`type, err := ...` fails `go build`).
     const eLower = goVarName(exampleEntity.name)
-    // ACTIVE ops only — an inactive op generates no method, so an example
-    // calling it would not compile.
     const opnames = entityOps(exampleEntity)
 
     // Model-driven id key: null when the entity has no id-like field (a
@@ -63,12 +49,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     // update omits the id member.
     const idF = entityIdField(exampleEntity)
 
-    // Model-driven example members for an op body, from the SAME op shape the
-    // request types are built from (opRequestShape), so create/update
-    // reference REAL writable fields, not a hardcoded "name", and every value
-    // is a type-correct Go literal (exampleValue). ids are rendered
-    // separately as the match key for update/remove; a REQUIRED id stays for
-    // create (dropping it makes the payload incomplete).
     const exampleFields = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
@@ -162,7 +142,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     }
   }
 
-  // Drop trailing blank lines from the body.
   while (body.length > 0 && body[body.length - 1] === '') {
     body.pop()
   }