@voxgig/sdkgen 4.21.0 → 4.23.0

package/src/cmp/FeatureDocs.ts

@@ -5,13 +5,6 @@ import { each } from 'jostraca'
 import { KIT, getModelPath } from '../types'
 
 
-// Shared feature facts, derived from the model, for the three doc surfaces
-// that describe features: the root README summary, the per-target README
-// section, and REFERENCE.md.
-//
-// ONE SOURCE. The feature set, its defaults and its ordering constraints all
-// come from `main.kit.feature`, so a feature added to the model documents
-// itself everywhere rather than in whichever file someone remembered.
 
 type FeatureDoc = {
   name: string
@@ -21,20 +14,10 @@ type FeatureDoc = {
   wraps: boolean
   options: Array<{ name: string, value: string }>
 
-  // Options the feature accepts but does not default: callbacks, injected
-  // clocks, values the caller either supplies or does not. Declared in
-  // `config.optspec` because a DEFAULTS map cannot describe an option that
-  // has no default — which is why the tables built from `config.options`
-  // alone were incomplete, and had to say so.
   extras: Array<{ name: string, type: string }>
 }
 
 
-// `transport` says how a feature attaches, and that is the whole of the
-// ordering story:
-//   wrap  wraps the transport chain — activation order IS nesting order
-//   base  installs the base transport others wrap (test)
-//   none  pipeline hooks only; order does not affect it
 function isWrapping(feat: any): boolean {
   return 'wrap' === feat.transport
 }
@@ -74,11 +57,6 @@ function renderValue(v: any): string {
 }
 
 
-// Every feature the model declares active, in a stable order, with its
-// options and their defaults.
-// With a target, also drops features that do not APPLY to it: a target
-// README must not document a feature that target has no implementation
-// for. Without one (the repo-level README) every active feature is listed.
 function featureDocs(model: any, target?: any): FeatureDoc[] {
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
@@ -94,9 +72,6 @@ function featureDocs(model: any, target?: any): FeatureDoc[] {
 
       const extra = (f.config && f.config.optspec) || {}
       const extras = Object.keys(extra)
-        // A name in both is documented by its DEFAULT; `config.optspec`
-        // only sharpened its type (netsim's `latency`, a number that is
-        // also a { min, max } map), and a reader wants the default.
         .filter((k) => null == opts[k])
         .sort()
         .map((k) => ({ name: k, type: sentinelName(extra[k]) }))
@@ -116,18 +91,6 @@ function featureDocs(model: any, target?: any): FeatureDoc[] {
 
 
 
-// Targets that compose transport features in a FIXED catalog order rather
-// than the order the caller activates them in.
-//
-// Every other target derives `__derived__.featureorder` from the options and
-// adds features in that order, so an ordered activation list is what fixes
-// nesting. lean has no featureorder at all — SdkFeatures.featureNames is a
-// fixed array — and its resolveFeatureOpts accepts only a map, silently
-// replacing a list with an empty one. Telling a lean reader to activate
-// features as an ordered list would therefore disable every feature they
-// asked for.
-//
-// Verify with: grep -rl featureorder tm/<target>
 const FIXED_ORDER_TARGETS = ['lean']
 
 function honoursActivationOrder(target: any): boolean {

package/src/cmp/PublishWorkflow.ts

@@ -10,40 +10,6 @@ import {
 import { packageName, packageVersion, repoInfo } from '../helpers/packageMeta'
 
 
-// PUBLISHING AN npm TARGET FROM GITHUB ACTIONS, WITH NO TOKEN.
-//
-// A generated SDK is published from CI, and the credential is the whole
-// problem: an NPM_TOKEN in repository secrets is long-lived, copyable, and
-// readable by every workflow in the repo. GitHub OIDC Trusted Publishing
-// replaces it — npm exchanges a short-lived OIDC token minted for one job in
-// one repository for a publish credential, and attaches SLSA provenance on
-// the way through.
-//
-// DISPATCH, NOT A TAG PUSH. The deploy Makefile in this same repo publishes
-// with a vault-injected token, and a tag-triggered workflow racing it would
-// publish the same version twice from two mechanisms. A dispatch is a
-// deliberate act by someone who can see the result, which is what a release
-// should be.
-//
-// IT TAGS WHAT IT PUBLISHED. A release that reaches the registry but leaves
-// no ref behind cannot be answered later: `@voxgig-sdk/github-sdk@0.0.3` went
-// out by dispatch and the repository had only v0.0.1 and v0.0.2, so nothing
-// in git said which tree the published tarball came from, and nothing
-// downstream could pin the SDK by tag. npm's trusted publisher is bound to
-// ONE workflow file, so the tag has to be cut inside this one -- and a ref
-// pushed with GITHUB_TOKEN starts no further workflow run, so it cannot be
-// delegated to a tag-triggered publisher either.
-//
-// THE WORKFLOW FILE NAME IS PART OF THE TRUST CONFIGURATION. npm binds a
-// trusted publisher to the repository AND the workflow filename, so renaming
-// this file silently breaks publishing until the npm side is updated to
-// match. That is also why one file per target: `publish-ts.yml` can be
-// trusted for the ts package without granting anything to another target's.
-//
-// SET-UP IS A MAINTAINER TASK, so what a human must do once is written to
-// `.sdk/PUBLISHING.md` — beside the generator, not into the target's own
-// docs, which describe the SDK to the people who INSTALL it and have no
-// business being told how this repo releases.
 const PublishWorkflow = cmp(function PublishWorkflow(props: any) {
   const { ctx$ } = props
   const { model } = ctx$
@@ -93,23 +59,6 @@ const PublishWorkflow = cmp(function PublishWorkflow(props: any) {
 })
 
 
-// WHICH TAG A TARGET'S RELEASE CARRIES.
-//
-// A repo here publishes more than one npm package -- `ts/` and `js/` are
-// separate packages from separate folders, on a lockstep version -- so a bare
-// `v<version>` cut by each would be two targets racing for one tag name, and
-// the loser would fail a release that had already published.
-//
-// The convention is the toolchain's own. @voxgig/apidef tags `v<version>` for
-// its npm package and `go/v<version>` for its Go module; the generated root
-// Makefile tags `<target>/v<version>` for every port. So: the ecosystem's
-// PRIMARY npm target owns the bare tag, and any other npm target is prefixed
-// with its own name.
-//
-// Resolved by comparing package names rather than hardcoding 'ts', so that a
-// project that renamed or replaced its primary target still gets one bare tag
-// -- and if none matches, every target is prefixed, which is wrong in no way
-// that loses a release.
 function isPrimaryNpm(model: any, target: any, npmTargets: any[]): boolean {
   if (1 === npmTargets.length) {
     return true
@@ -127,13 +76,6 @@ function releaseTag(model: any, target: any, npmTargets: any[]): string {
 function publishWorkflow(model: any, target: any, npmTargets: any[]): string {
   const name = target.name
   const tag = releaseTag(model, target, npmTargets)
-  // BY TARGET, NOT BY ECOSYSTEM. `packageName(model, 'npm')` resolves the
-  // ecosystem's PRIMARY target — ts — so every npm target's workflow named
-  // the ts package: publish-js.yml claimed `@voxgig-sdk/github-sdk` while
-  // `js/` publishes `@voxgig-sdk/github-js`. It would have checked the wrong
-  // package on the registry and told a maintainer to trust the wrong one,
-  // while `npm publish` shipped the right one — confidently wrong in three
-  // places at once.
   const pkg = packageName(model, name)
 
   return `# Generated by @voxgig/sdkgen. Do not edit.
@@ -342,8 +284,6 @@ jobs:
 
 
 function publishingDoc(model: any, targets: any[], repoUrl: string): string {
-  // The doc's worked example uses the FIRST npm target; the table names each
-  // target's own package, resolved per target.
   const pkg = packageName(model, targets[0].name)
   const repo = String(repoUrl || '')
     .replace(/^git\+/, '')

package/src/cmp/ReadmeErrors.ts

@@ -12,21 +12,6 @@ import type { ExampleLang, PrimaryCall } from '../helpers/opExample'
 import { safeVarName, exampleVarName } from '../helpers/naming'
 
 
-// Error handling is one of the everyday developer tasks, so it gets its
-// own user-facing section rather than being buried in the pipeline
-// explanation. The convention differs by language in two ways:
-//
-//   1. Entity operations (load/list/create/update/remove) either THROW
-//      (ts, js, py, php, rb) or return an error value (go, lua).
-//   2. The low-level `direct()`/`prepare()` escape hatch does NOT always
-//      follow the entity-op convention. In go/lua it returns (value, err);
-//      in ts/js it returns the value or an `Error`; in py/php/rb it returns
-//      the result envelope — branch on `ok`, and read `err` on failure.
-//
-// The entity-op snippet is rendered from the entity's PRIMARY op (never a
-// hardcoded `load`, which a create-only entity lacks) with a type-correct
-// match id (a numeric id renders `1`, not "example_id"). Targets not listed
-// here (ts, js) use DEFAULT_LANG.
 type LangErrors = {
   // prose + snippet for the entity-op convention, given the pre-rendered
   // primary-op invocation and its op name.
@@ -239,8 +224,6 @@ const ReadmeErrors = cmp(function ReadmeErrors(props: any) {
 
   if (ex && primaryOp) {
     const eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
-    // Sanitise the variable name against the target's reserved words (a
-    // `Delete` entity must not bind `const delete = ...`).
     const eLower = exampleVarName(eName.toLowerCase(), target.name)
     const idF = entityIdField(ex)
     const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)

package/src/cmp/ReadmeExplanation.ts

@@ -21,12 +21,8 @@ function cap(s: string): string {
 }
 
 
-// The four sections below differ by target language but share an identical
-// structure, so the per-language prose lives in one table rather than in
-// parallel if/else chains. Targets not listed here (ts, js, ...) use
-// DEFAULT_LANG.
 type LangExplain = {
-  featureKind: string // what a "feature" is in this language
+  featureKind: string
   // stateful-entity explanation + example, driven by the entity's PRIMARY op
   // (`op`) — never a hardcoded `load` a create-only entity lacks. `arg` is the
   // pre-rendered, language-correct call argument; `matchIdF` is the id key when
@@ -37,7 +33,7 @@ type LangExplain = {
     op: string, arg: string,
     matchIdF: string | null, idLit: string,
   ) => string
-  direct: string      // direct/prepare explanation
+  direct: string
 }
 
 
@@ -241,8 +237,6 @@ const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
   let eName = 'Entity', eLower = 'entity', stateArg = '', matchIdF: string | null = null, idLit = ''
   if (hasEntityExample) {
     eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
-    // Sanitise against the target's reserved words (a `Delete` entity must
-    // not bind `const delete = ...`).
     eLower = exampleVarName(eName.toLowerCase(), target.name)
     const idF = entityIdField(ex)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
@@ -297,7 +291,6 @@ in this language.
 `)
 
 
-  // Features and hooks
   Content(`### Features and hooks
 
 `)
@@ -322,7 +315,6 @@ were added, so later features can override earlier ones.
 `)
 
 
-  // Target-specific explanation
   const ReadmeExplanation_sdk =
     requirePath(ctx$, `./cmp/${target.name}/ReadmeExplanation_${target.name}`, { ignore: true })
 
@@ -340,7 +332,6 @@ were added, so later features can override earlier ones.
   }
 
 
-  // Direct vs entity access
   Content(`### Direct vs entity access
 
 The entity interface handles URL construction, parameter placement,

package/src/cmp/ReadmeFeatures.ts

@@ -5,16 +5,6 @@ import { featureDocs, honoursActivationOrder } from './FeatureDocs'
 import type { FeatureDoc } from './FeatureDocs'
 
 
-// The `## Features` section of a target README: one subsection per feature
-// the SDK actually ships.
-//
-// WHY IT IS SHARED AND NOT PER-LANGUAGE. Every target activates features the
-// same way — a `feature` entry in the client options — and the options and
-// their defaults come from the model, so the substance is identical in all
-// twenty-five languages. Only the literal syntax of the options map differs,
-// and that is already shown once, in the Options section above. A per-target
-// `ReadmeFeatures_<lang>.ts` may override this to add idiomatic snippets;
-// none is required for the section to be correct.
 const ReadmeFeatures = cmp(function ReadmeFeatures(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$

package/src/cmp/ReadmeRefFeatures.ts

@@ -4,17 +4,6 @@ import { featureDocs, honoursActivationOrder } from './FeatureDocs'
 import type { FeatureDoc } from './FeatureDocs'
 
 
-// The feature reference, appended to every REFERENCE.md.
-//
-// REFERENCE.md is otherwise generated per-language, because the constructor
-// signature, op spelling and code fence differ. Feature CONFIGURATION does
-// not: the option names and defaults are model facts, identical in every
-// target. So this section is written once and appended to all of them, rather
-// than copied into twenty-five ReadmeRef_<lang>.ts files where it would drift.
-//
-// Covers what a reference has to cover and a README does not: every option
-// with its default, what the feature does at runtime, and the considerations
-// — ordering, interaction, and cost — that decide whether to switch it on.
 const ReadmeRefFeatures = cmp(function ReadmeRefFeatures(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
@@ -78,14 +67,6 @@ ${f.title}.
 
 `)
 
-    // THE TABLE IS THE MODEL'S OPTIONS, and the model now carries both
-    // halves of them. It used to carry one: `config.options` is a DEFAULTS
-    // map, so the options with no default — cost's `sink`, audit's `sink`,
-    // every injected clock — could not appear in it, and this table had to
-    // admit it was not exhaustive. `config.optspec` declares those with a
-    // type instead of a default, and they are listed below the defaults.
-    // Same declaration the generated option spec validates against, so a
-    // documented option and a validated option cannot be different sets.
 
 
     if (0 < f.options.length) {

package/src/cmp/ReadmeStation.ts

@@ -9,30 +9,11 @@ import {
 import { envName, packageName } from '../helpers/packageMeta'
 
 
-// The "Use with Station" README section (station design §9.4): rendered
-// ONLY when the project's model carries the station feature (installed
-// via `package add @voxgig/sdkgen-station`) — a project without it sees
-// nothing. Leads with the DECLARATIVE flow — a `station.json` block and
-// `station.sdk()` (declarative design §11 item 3) — keeps the imperative
-// `connect()` form as the retrofit path, and documents the
-// instance-derived secret/env-var name (declarative design §3.4, §5.1:
-// the same envtoken grammar as sdkgen's envName, applied to the INSTANCE
-// name, so the untagged instance keeps the env var this README already
-// documents to the byte). Store configuration is sekreto's
-// documentation, deliberately not restated here (one canonical source);
-// the error codes live in sdkgen's one catalog page, linked rather than
-// restated for the same reason.
 
 // Targets where station.connect(SDK) is the idiomatic binding; everything
 // else uses inverted binding through the SDK's own constructor.
 const CONNECT_TARGETS = ['ts', 'js', 'py', 'rb', 'php', 'lua', 'perl']
 
-// Targets whose module system has an init hook that actually runs
-// (station design §6.2 path 1): there, linking the generated package
-// fills the process-global factory table and `station.sdk()` needs no
-// application code. Everywhere else the README must say
-// `Station.provide` (path 2) plainly rather than imply an import is
-// enough — a Java import is a compile-time alias that runs nothing.
 const SELF_REGISTER_TARGETS =
   ['ts', 'js', 'go', 'py', 'rb', 'php', 'lua', 'perl', 'elixir', 'clojure']
 

package/src/cmp/ReadmeTop.ts

@@ -46,19 +46,11 @@ function tsExampleLiteral(type: any): string {
 }
 
 
-// Per-language install commands rendered in the top-level "Try it"
-// section. The per-language `ReadmeInstall_<lang>.ts` templates exist
-// but emit extra prose ("Or install from source: ..."); for the
-// landing-page README we want a single copy-paste line per language.
 function installCommand(target: any, model: any): string {
-  // Delegate to the single source of truth so the README install command can
-  // never drift from the real published package name (see helpers/packageMeta).
   return pkgInstall(model, target.name)
 }
 
 
-// Pick the language we lead the README with — first entry from the
-// docs-ordered SDK targets. Returns undefined if there are no targets.
 function pickLeadTarget(sdkTargets: any[]): any | undefined {
   return sdkTargets[0]
 }
@@ -68,17 +60,11 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
   const { ctx$ } = props
   const { model } = ctx$
 
-  // Ensure the Name/NAME case variants exist (apidef usually sets these,
-  // but guard so the header never renders "undefined SDK"). Entity/feature
-  // names are guarded the same way below.
   if (model.name && !model.Name) names(model, model.name)
 
   const info = (model.main && model.main[KIT] && model.main[KIT].info) || {}
   const def = (model.main && model.main.def) || {}
 
-  // Plain-text title — prefer the OpenAPI `info.title` when it's
-  // recognisably the product name (e.g. "Aare.guru API"), fall back
-  // to the normalised SDK Name.
   const productName = info.title || `${model.Name} API`
 
   const tagline = info.tagline
@@ -92,10 +78,6 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
   const docsUrl = info.docs_url || ''
   const entityDesc = info.entity_desc || {}
 
-  // Spec-derived (apidef): a short "what this API is" blurb and a link back
-  // to the API's own website. Both surface right under the title, before
-  // the unofficial-SDK disclosure, so a reader immediately sees what the
-  // underlying API is and where it comes from.
   const apiSummary = (info.summary || '').trim()
   const apiWebsite = (info.website || '').trim()
   const websiteLine = apiWebsite
@@ -127,17 +109,12 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
   const hasMcp = activeTargets.some((t: any) => t.name === 'go-mcp')
 
 
-  // Canonical docs order from main.kit.config.docs_order (with a
-  // schema-supplied default of ['ts','py','php','go','rb','lua']).
-  // Targets present but not listed get appended in spec-defined order,
-  // so adding a new target never silently disappears from the docs.
   const docsOrder: string[] = (getModelPath(model, `main.${KIT}.config.docs_order`,
     { only_active: false, required: false }) as any) || []
 
   const orderOf = (name: string): number => {
     const i = docsOrder.indexOf(name)
     if (i !== -1) return i
-    // Unlisted targets go after the languages; keep the CLI then MCP last.
     if (name === 'go-cli') return docsOrder.length + 1
     if (name === 'go-mcp') return docsOrder.length + 2
     return docsOrder.length
@@ -148,8 +125,6 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
     .slice()
     .sort((a: any, b: any) => orderOf(a.name) - orderOf(b.name))
 
-  // Every installable port for the Packages table — including the go-cli and
-  // go-mcp binaries, which publish as Go modules via git tags.
   const pkgTargets = activeTargets
     .slice()
     .sort((a: any, b: any) => orderOf(a.name) - orderOf(b.name))
@@ -159,8 +134,6 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
 
   File({ name: 'README.md' }, () => {
 
-    // 1. H1 + one-line value prop, then the API's own purpose + website
-    // (spec-derived), then the unofficial / non-affiliation disclosure.
     Content(`# ${model.Name} SDK
 
 ${tagline}
@@ -199,20 +172,9 @@ Learn more about Voxgig SDKs at [voxgig.com/sdk](${VOXGIG_SDK}).
 `)
     }
 
-    // Positioning line, only when we actually have multiple SDK targets.
     if (sdkTargets.length > 1) {
       const surfaces = []
       surfaces.push(`${langList} SDKs`)
-      // Only surfaces a target actually GENERATES, each gated on the target
-      // that generates it.
-      //
-      // The REPL entry used to be gated on hasJsLike — a ts or js target merely
-      // EXISTING — which is wrong twice over: a ts/js SDK is a library and
-      // ships no REPL, so every project with one advertised a surface it did
-      // not have; and the target that really does emit a REPL is go-cli
-      // (cmp/go-cli/fragment/main.fragment.go: `func repl(...)`, a prompt, and
-      // /help and /quit), so a project WITH a REPL and without ts/js was not
-      // credited for it. Gating it on hasCli fixes both directions.
       if (hasCli) surfaces.push('a CLI with an interactive REPL')
       if (hasMcp) surfaces.push('an MCP server for AI agents')
       const surfaceList = surfaces.length > 1
@@ -230,14 +192,13 @@ Learn more about Voxgig SDKs at [voxgig.com/sdk](${VOXGIG_SDK}).
     // Named here, in one line, with the detail left to each target's README.
     const features = featureDocs(model)
     if (0 < features.length) {
-      Content(`> **Features:** ${features.map((f: any) => '`' + f.name + '`').join(', ')} — opt-in,
+      Content(`> **Features:** ${features.map((f: any) => '`' + f.n + '`').join(', ')} — opt-in,
 > inactive until switched on, and configured per client. See the Features
 > section of any SDK README below for what each one does.
 
 `)
     }
 
-    // 2. About / what the API is
     if (aboutMd) {
       Content(`## About ${productName}
 
@@ -250,19 +211,12 @@ ${aboutMd.trim()}
 `)
     }
 
-    // 2b. Entities-first framing: the API surface is a small set of semantic,
-    // Capitalised entities — NOT raw URL paths/queries — which is the core
-    // mental model the SDK is built around (model-driven; lists real entities).
     if (activeEntities.length > 0) {
       const entNames = activeEntities.map((e: any) => e.Name)
       const entCount = entNames.length
       const entList = entCount > 1
         ? entNames.slice(0, -1).join(', ') + ' and ' + entNames[entNames.length - 1]
         : entNames[0]
-      // Only enumerate the entity names inline when the set is small enough that
-      // the list clarifies the mental model rather than becoming a wall of names
-      // at the top of the README. Larger APIs get a count and a pointer to the
-      // Entities table below — and we never assert a "small set" when it isn't.
       const NAME_INLINE_MAX = 6
       const inlineNames = entCount <= NAME_INLINE_MAX
       const surface = inlineNames
@@ -281,11 +235,6 @@ ${aboutMd.trim()}
       // only remove (or nothing), the op line is omitted entirely.
       const primaryOp = entityPrimaryOp(exEnt)
       let exCall = ''
-      // 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. The model knows which params are required; matchArg
-      // renders exactly those.
       const exIdField = entityIdField(exEnt)
       const exListArg = matchArg('ts', exEnt, 'list', exIdField,
         idLiteral(exEnt, 'list', exIdField))
@@ -306,15 +255,11 @@ ${aboutMd.trim()}
           .filter((it: any) =>
             (it.name !== exIdF && it.name !== 'id') || !it.optional)
         const required = shapeItems.filter((it: any) => !it.optional)
-        // ALL required fields must appear or the literal is not assignable to
-        // the typed CreateData/UpdateData; cap only the optional fallback.
         const chosen = required.length ? required : shapeItems.slice(0, 3)
         const bodyLines = chosen.map((it: any) => `  ${it.name}: ${tsExampleLiteral(it.type)},`)
         const body = bodyLines.length ? `\n${bodyLines.join('\n')}\n` : ''
         exCall = `const ${exLower} = await client.${ex}().${primaryOp}({${body}})`
       }
-      // Model-driven op list — only the operations the entities actually expose
-      // (advice may be list+load only; never claim create/update/remove exist).
       const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
       const opSet = new Set<string>()
       activeEntities.forEach((e: any) => Object.keys(e.op || {})
@@ -338,8 +283,6 @@ rather than reasoning about raw HTTP routes and query parameters.
 `)
     }
 
-    // 2c. Offline unit testing — a headline feature: every SDK ships a mock
-    // transport, so it belongs high up, right after the entity model.
     if (sdkTargets.length > 0) {
       Content(`## Offline unit testing
 
@@ -382,10 +325,8 @@ network, and no credentials:
           if (!cmd) return
           cell = '`' + cmd + '`'
         } else if ('tag' === state) {
-          // Tag-only port (go): the vendor command IS the real install.
           cell = '`' + vendorCommand(model, tgt.name) + '`'
         } else {
-          // pending / inactive: point at the git tag, never a 404 command.
           cell = `publish pending — [install from git tag](${tagsUrl})`
         }
         Content(`| ${tgt.title} | \`${packageName(model, tgt.name)}\` | ${cell} |
@@ -395,7 +336,6 @@ network, and no credentials:
 `)
     }
 
-    // 4. Quickstart in the lead language
     if (leadTarget) {
       Content(`## Quickstart
 
@@ -413,7 +353,6 @@ See the [${leadTarget.title} README](${leadTarget.name}/README.md) for the full
 `)
     }
 
-    // 5. Surface table
     if (sdkTargets.length > 0 || hasCli || hasMcp) {
       Content(`## Surfaces
 
@@ -437,7 +376,6 @@ See the [${leadTarget.title} README](${leadTarget.name}/README.md) for the full
 `)
     }
 
-    // 6. MCP / agent usage — only if MCP target is enabled
     if (hasMcp) {
       Content(`## Use it from an AI agent (MCP)
 
@@ -464,7 +402,6 @@ Then add it to your agent's MCP config (Claude Desktop, Cursor, etc.):
 `)
     }
 
-    // 7. Entities table
     if (activeEntities.length > 0) {
       Content(`## Entities
 
@@ -477,13 +414,8 @@ The API exposes ${activeEntities.length === 1 ? 'one entity' : activeEntities.le
       activeEntities.map((ent: any) => {
         const ops = ent.op || {}
         const opNames = Object.keys(ops).filter((o: string) => (ops as any)[o]?.active !== false)
-        // Never emit a blank description cell: fall back to an ops-derived line.
         const entdesc = entityDesc[ent.name] || ent.short || ent.desc ||
           `The ${ent.Name} entity${opNames.length ? ' (' + opNames.join(', ') + ')' : ''}.`
-        // The entity's canonical route — never a folded-in custom action.
-        // Ops iterate in sorted-key order, so this used to take `create`'s
-        // first point, and an entity with a `/{id}/forbid` action route
-        // advertised THAT as its API path.
         const path = entityPath(ent)
         Content(`| **${ent.Name}** | ${entdesc} | \`${path}\` |
 `)
@@ -501,7 +433,6 @@ own list above for exactly which it supports.
 `)
     }
 
-    // 8. Quickstart in the other languages (lead is already covered above)
     const otherTargets = sdkTargets.filter((t: any) => leadTarget && t.name !== leadTarget.name)
     if (otherTargets.length > 0) {
       Content(`## Quickstart in other languages
@@ -521,8 +452,6 @@ own list above for exactly which it supports.
       })
     }
 
-    // 10. Direct and prepare — a common everyday task (the low-level
-    // escape hatch for endpoints the entity model doesn't cover).
     Content(`## Direct and prepare
 
 For endpoints the entity model doesn't cover, use the low-level methods:
@@ -535,7 +464,6 @@ Both accept a map with \`path\`, \`method\`, \`params\`, \`query\`,
 
 `)
 
-    // 11. How-to guides — keep, useful for the engineer reader
     Content(`## How-to guides
 
 ### Make a direct API call
@@ -552,9 +480,6 @@ When the entity interface does not cover an endpoint, use \`direct\`:
       }
     })
 
-    // 11b. Advanced — the pipeline model and feature hooks are internal
-    // machinery: useful when extending the SDK, but not part of everyday
-    // use, so they live below the task-focused sections above.
     Content(`## Advanced
 
 > Everyday use only needs the sections above. This explains the internals
@@ -624,7 +549,6 @@ The full story: [voxgig.com/sdk/custom](https://voxgig.com/sdk/custom).
 
 `)
 
-    // 12. Per-language docs links
     if (sdkTargets.length > 0) {
       Content(`## Per-language documentation
 
@@ -637,8 +561,6 @@ The full story: [voxgig.com/sdk/custom](https://voxgig.com/sdk/custom).
 `)
     }
 
-    // 13. Upstream API — always disclose the OpenAPI origin and where the
-    // spec(s) live; contact/servers links come from the OpenAPI info block.
     const upstreamUrl = (info.contact && info.contact.url)
       || (info.servers && info.servers[0] && info.servers[0].url)
       || homepage
@@ -671,7 +593,6 @@ The OpenAPI spec(s) this SDK was generated from are kept in the
     Content(`
 `)
 
-    // 13b. Security
     Content(`## Security
 
 Please report security issues to ${SECURITY_EMAIL}. See [SECURITY.md](SECURITY.md).
@@ -679,7 +600,6 @@ Do not open public issues for suspected vulnerabilities.
 
 `)
 
-    // 14. Provenance footer
     Content(`---
 
 Generated from the ${productName} OpenAPI spec by [@voxgig/sdkgen](${SDKGEN_REPO}).

package/src/cmp/ReadmeUnions.ts

@@ -6,21 +6,6 @@ import {
 } from '../types'
 
 
-// Fields whose type could not be narrowed because the API definition describes
-// them with an UNTAGGED union: `oneOf`/`anyOf` branches carrying no
-// `discriminator`, so the specification never states which variant a given
-// value is. apidef records the widest such union it finds beneath each field
-// (see ModelField.union); this section reports them.
-//
-// Without this, those fields read as a modelling failure — a `groups` field
-// typed as a bare array looks like the generator gave up, when in fact the
-// definition offers nothing to narrow it to. Saying so is the difference
-// between an SDK that looks unfinished and one that documents the API it was
-// given.
-//
-// Two-branch unions are NOT reported: `oneOf: [string, number]` is a routine
-// either/or, an open type for it surprises nobody, and listing every one would
-// bury the cases that matter.
 const MIN_REPORTED_BRANCHES = 3
 
 
@@ -43,7 +28,7 @@ const ReadmeUnions = cmp(function ReadmeUnions(props: any) {
       }
       rows.push({
         entity: ent.name,
-        field: field.name,
+        field: field.n,
         branches: union.branches,
         depth: union.depth,
       })