@voxgig/sdkgen-infrapack 0.0.12 → 0.0.14

package/.sdk/src/cmp/seneca-provider/Extras_seneca-provider.ts

@@ -6,45 +6,11 @@ import {
 } from '@voxgig/sdkgen'
 
 
-// The rest of the seneca-provider package: its test suite, CI workflow and
-// README. Split out of Main only for size — everything here is driven by the
-// same `provider` shape Main builds from the model.
-//
-// The tests are the reason this target is worth generating at all. A provider
-// is thin, and the thin part is exactly where the mistakes are: a cmd that
-// forgets a parent path param, an entity that comes back under the wrong
-// canon, a 404 that should have been `null` and instead threw. All three are
-// checked below, offline, against the SDK's own mock transport — so a
-// generated provider is verified without a server.
-
-
-// WHERE A FETCHED SDK CHECKOUT LIVES, inside this repo.
-//
-// Fixed, and the same under every layout, which is the whole point: it is
-// what lets the generated docs, the live-test instructions and `make regen`
-// name the SDK source without naming anyone's directory layout. Gitignored —
-// the checkout is derived from the pin and disposable, so committing it would
-// vendor the SDK into a repo that already depends on it.
-//
-// NOT a git submodule. A submodule pins a COMMIT and puts the pin in git's
-// own plumbing, where updating it is a second repository operation and a
-// stale one is invisible in a normal diff. The pin here is an ordinary
-// committed file naming a TAG, regenerated from the model like everything
-// else, so it moves with the SDK version it belongs to and shows up in review.
+
+
 const SDK_SRC_DIR = '.sdksrc'
 
 
-// The SDK this provider was generated from: repository, release tag, and the
-// published package the tag corresponds to.
-//
-// Committed, and REGENERATED — so it cannot drift from the dependency in
-// package.json, which comes from the same model version. The tag is
-// `v<version>` because that is what the SDK's publish workflow cuts for its
-// primary npm target.
-//
-// This is the file that makes the repo independently buildable: with it, the
-// SDK that generates this provider can be fetched from scratch, at the exact
-// revision that generated it, by a script that knows nothing else.
 const SdkPin = cmp(function SdkPin(props: any) {
   const { provider } = props
 
@@ -73,37 +39,15 @@ const SdkPin = cmp(function SdkPin(props: any) {
 // Does this entity's load op have a real identifying param (path or
 // required query), e.g. GET /result?trace_id=? A paramless GET has none.
 function loadHasKey(e: any): boolean {
-  // FROM WHAT THE HANDLER ACTUALLY SENDS (Main's addressKeys), not from the
-  // route's shape. A route can carry parameters and still be a singleton
-  // read: github's `interaction` is `/user/interaction-limits`, and its
-  // sibling `webhook_config` reads one config per app — both are called as
-  // `load({})`, so every id hits the same record and a not-found test
-  // against them asserts the opposite of the truth. Asking the route
-  // whether it has any parameter said yes for both.
   return true === (e.idaddressed || {}).load
 }
 
 
-// CAN A REMOVE DELETE WHAT A CREATE JUST MADE? A round-trip that ends by
-// asserting the record is gone needs one that can address it.
-//
-// github's `action` is a tag bucket whose ops address different resources:
-// keyed `archive_format` from its download route, removed by
-// `hosted_runner_id` and `org_id`. The remove therefore deleted whichever
-// record the store yielded first — usually a SEEDED one — and the round-trip
-// failed on its own record surviving, intermittently, because the created
-// id is random and its position in iteration order decides.
 function removeAddresses(e: any): boolean {
   return true === (e.idaddressed || {}).remove
 }
 
 
-// WOULD THIS CMD REFUSE? A cmd whose only route addresses a different
-// resource does not send the request (Main's `misaddressed`), so a test that
-// drives it reaches the refusal and nothing beyond — a parent-key guard, a
-// round-trip's update leg, a plain-save assertion. Each such test is skipped
-// here and the refusal is pinned by its own `<entity>-<cmd>-refused`.
-// What a refusing cmd's route DOES address, for the message and the note.
 function addressNames(e: any, cmd: string): string[] {
   const keys = (e.opParents || {})[cmd] || []
   return 0 < keys.length ? keys : ['nothing more specific']
@@ -115,13 +59,6 @@ function cmdRefuses(e: any, cmd: string): boolean {
 }
 
 
-// The name of the entity a parent path param addresses, or '' when the model
-// has none of that name.
-//
-// From `e.parentOf`, which Main derives PER KEY. `e.parentEntity` describes
-// only the FIRST parent, so an entity nested two levels deep had every one of
-// its parents resolved to the innermost one — addressing the wrong record, or
-// none.
 function parentName(e: any, key: string): string {
   const byKey = (e.parentOf || {})[key]
   if (null != byKey && '' !== byKey) {
@@ -143,20 +80,68 @@ function parentSeed(e: any, key: string): string {
 }
 
 
-// `key: 'value', ` pairs for an entity's parent path params, ready to splice
-// into an object literal. Empty for a top-level entity, so the same emitter
-// serves both.
-//
-// OFFLINE the value is the seeded parent id, which exists because the seed put
-// it there. LIVE it is a local VARIABLE, emitted as ES shorthand: a real server
-// holds whatever records it holds, and a fixture id written into a live test is
-// a 404 waiting to happen. That is not hypothetical — seeding the live nested
-// create is exactly how the first version of this failed, with
-// `create: request: 404` against a parent that only ever existed in the mock.
+// A parameter name as a local variable: an API definition can hyphenate.
+function paramVar(p: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(p) ? p :
+    'p_' + p.replace(/[^A-Za-z0-9_$]/g, '_')
+}
+
+
+function regexLiteral(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\\/]/g, '\\$&')
+}
+
+
+// `key: value` for one parent, from the live variable or the seed.
+function parentPair(e: any, p: string, live: boolean): string {
+  if (!live) {
+    return `${jsKey(p)}: '${parentSeed(e, p)}', `
+  }
+  const v = paramVar(p)
+  return v === p ? `${p}, ` : `${jsKey(p)}: ${v}, `
+}
+
+
 function parentPairs(e: any, live: boolean): string {
-  return e.parents
-    .map((p: string) => live ? `${p}, ` : `${p}: '${parentSeed(e, p)}', `)
-    .join('')
+  return e.parents.map((p: string) => parentPair(e, p, live)).join('')
+}
+
+
+// A field the record owns: not Seneca's id, not a parent path param. The API's
+// key is the record's own only when a create has to supply it — an
+// API-assigned id is not the caller's to send, and a required key is.
+function ownField(e: any, f: any): boolean {
+  if (f.name === e.rk) {
+    return true === e.rkoncreate
+  }
+  return 'id' !== f.name && !e.parents.includes(f.name)
+}
+
+
+// A field an UPDATE may change. Never the key: rewriting that addresses, or
+// renames, a different record than the one loaded.
+function changeField(e: any, f: any): boolean {
+  return f.name !== e.rk && ownField(e, f)
+}
+
+
+// Where a configured `apikey` goes on the wire, from the model's security
+// declaration. Empty for an API that declares no authentication.
+function credentialWire(provider: any): string {
+  if (!provider.authActive) {
+    return ''
+  }
+  if (provider.authBasic) {
+    return `\`${provider.authName}: Basic <base64 of apikey:secret>\``
+  }
+  const prefix = '' === provider.authPrefix ? '' : provider.authPrefix + ' '
+  if ('header' === provider.authIn) {
+    return `\`${provider.authName}: ${prefix}<apikey>\``
+  }
+  if ('query' === provider.authIn) {
+    return `the \`${provider.authName}\` query parameter`
+  }
+  return `the \`${provider.authName}\` ${provider.authIn}`
 }
 
 
@@ -185,13 +170,6 @@ function entIdLiteral(e: any, suffix: string): string {
   const vals = parts.map((p: string) =>
     e.parents.includes(p) ? parentSeed(e, p) : `${e.name}${suffix}`)
 
-  // THE SUFFIX MUST SURVIVE, or `-nosuch` names the record that exists.
-  //
-  // A part that is also a parent key takes the parent's seeded value, which
-  // ignores the suffix — and for github's repo BOTH parts are parent keys,
-  // so `entIdLiteral(e, '-nosuch')` returned `owner0/repo0`. The not-found
-  // test then loaded the seeded record and asserted it was null. The last
-  // part is the record's own key, so that is where the suffix belongs.
   if ('' !== suffix && !vals.some((v: string) => v.endsWith(suffix))) {
     vals[vals.length - 1] = vals[vals.length - 1] + suffix
   }
@@ -239,64 +217,18 @@ function queryPairs(e: any, live: boolean): string {
     return parentPairs(e, live)
   }
 
-  // ONLY THE PARTS TRAVEL INSIDE THE ID. A required key that is not one of
-  // them still has to be passed, and dropping every parent because SOME of
-  // them are parts left github's api_insights_summary_stat — keyed
-  // `actor_type/actor_id`, and requiring a `min_timestamp` besides — called
-  // without the timestamp its own handler guards. Its three read tests
-  // failed on the guard rather than on anything they were written to check.
   const rest = e.parents.filter((p: string) => !parts.includes(p))
 
-  return rest
-    .map((p: string) => live ? `${p}, ` : `${p}: '${parentSeed(e, p)}', `)
-    .join('')
+  return rest.map((p: string) => parentPair(e, p, live)).join('')
 }
 
 
-// CAN A CREATED RECORD'S COMPOSITE ID BE REBUILT? Only if every part is
-// recoverable, and for a composite entity that is not a given.
-//
-// A create supplies the parts one of two ways: as path parameters of the
-// create route, or in the response. github's repo has NEITHER for its
-// `repo` part — `POST /user/repos` takes no path parameters, and the
-// response names the repository `name`, never `repo`. So there is no honest
-// way to know the id of a repo the API just made, and a create/update/remove
-// round-trip cannot be written against it.
-//
-// THIS IS A MODEL GAP, NOT A TEST TO FORCE. What is missing is a mapping
-// from a path parameter to the response field that carries it (`repo` ->
-// `name`); apidef knows the parameter and the field but nothing relates
-// them. Emitting the round-trip anyway produced a 404 on the update leg that
-// pointed at the mock rather than at the cause, so the honest thing is to
-// leave it out and say why in the generated file.
-//
-// load, load-missing and the malformed-id test are all still emitted: those
-// address an existing record, where the id comes from the caller.
 function compositeRoundTrip(e: any): boolean {
   const parts = idPartsOf(e)
   if (0 === parts.length) {
     return true
   }
 
-  // EVERY PART PLACED, AND PLACED AT THE TOP LEVEL.
-  //
-  // Placed at all: the model must say where a response carries the part, or a
-  // created record's id cannot be rebuilt by anything.
-  //
-  // Top level: only for the OFFLINE round-trip, and only because of how this
-  // transport matches a write. It takes the keys it matches on from the
-  // request BODY, and a write's addressing parameters no longer travel there
-  // — they go in the entity match, which is what stopped them displacing a
-  // nested response field. So an update finds nothing to pin the record by.
-  //
-  // Widening the transport's key set to the point's required parameters was
-  // tried and over-constrains reads: PullEntity's basic load began matching
-  // on a parameter it had never constrained, and answered 404. The proper
-  // fix is for the transport to take a write's addressing keys from the
-  // resolved path parameters specifically, which is a change to shared
-  // machinery that wants its own validation pass.
-  //
-  // Reads, lists and removes round-trip through a nested part today.
   const from = e.idfrom || {}
   return parts.every((p: string) => {
     const path = from[p]
@@ -327,18 +259,6 @@ function liveParentsResolvable(provider: any, e: any): boolean {
 }
 
 
-// A DECLARED identifier derived from an entity name.
-//
-// apidef canonizes an entity name to `[A-Za-z_0-9]` — `canonize` strips
-// everything else, so hyphens and dots never reach the model and `a-b` and
-// `a_b` arrive as the same `a_b`. The one shape that survives and is NOT a
-// legal identifier is a LEADING DIGIT, which real resources produce:
-// `3ds-sessions` canonizes to `3ds_session`, `2fa-tokens` to `2fa_token`.
-//
-// A DECLARATION cannot be bracket-quoted the way a property access can — the
-// same constraint `guardName` in Main documents — so it is prefixed instead.
-// Only a leading digit is touched, so every ordinary entity keeps the name it
-// has always generated.
 function entVar(name: string, suffix = ''): string {
   return /^[0-9]/.test(name) ? `e_${name}${suffix}` : `${name}${suffix}`
 }
@@ -364,7 +284,7 @@ ${ind}    .list\$()
 
 ${ind}  if (0 === ${pv}.length) return t.skip('no ${pe.name} to attach a ${e.name} to')
 
-${ind}  const ${p} = ${pv}[0].${pe.idf || 'id'}
+${ind}  const ${paramVar(p)} = ${pv}[0].id
 
 `
   }).join('')
@@ -377,26 +297,12 @@ ${ind}  const ${p} = ${pv}[0].${pe.idf || 'id'}
 // is dropped rather than asserted vacuously.
 function mutableField(e: any): string {
   const f = (e.fields || []).find((f: any) =>
-    f.name !== e.idf && 'id' !== f.name &&
-    !e.parents.includes(f.name) && 'string' === f.kind)
+    changeField(e, f) && 'string' === f.kind)
 
   return f ? f.name : ''
 }
 
 
-// A create -> load -> update -> remove round-trip for one entity.
-//
-// Emitted for any entity declaring BOTH save and remove, in both modes: once
-// offline against the SDK's mock transport, once live behind the server probe.
-// The write path is where a provider actually breaks — a save that forgets a
-// parent key, an update that creates a second record instead of amending the
-// first — and it was covered by nothing until this existed. The hand-written
-// provider this target was modelled on had exactly these tests, live; dropping
-// them on the first regeneration left every cmd.save and cmd.remove action in
-// the generated plugin unexecuted by its own suite.
-//
-// The created id is never asserted to a VALUE: both the mock and a real API
-// assign it themselves and ignore any the SDK sends.
 function crudTest(provider: any, e: any, mode: 'offline' | 'live'): string {
   const live = 'live' === mode
   const pairs = parentPairs(e, live)
@@ -407,39 +313,21 @@ function crudTest(provider: any, e: any, mode: 'offline' | 'live'): string {
   // query and entity always spell the id `id`. The provider translates to
   // whatever the API calls it.
   const idf = 'id'
-  const mut = mutableField(e)
+  // The update leg needs a route that updates one record; without one a
+  // save on a loaded entity would create again.
+  const mut = e.canonicalOps.includes('update') && !cmdRefuses(e, 'update') ?
+    mutableField(e) : ''
 
   const ind = live ? '    ' : '  '
   const mk = live ? 'makeSeneca(liveOpts())' : 'makeSeneca()'
   const setup = live ? liveParentSetup(provider, e, ind) : ''
 
-  const made = 0 < e.fields.filter((f: any) =>
-    f.name !== idf && 'id' !== f.name && !e.parents.includes(f.name)).length ?
+  const made = 0 < e.fields.filter((f: any) => ownField(e, f)).length ?
     seedLiteral(e, 'crud') : ''
 
-  // A COMPOSITE RECORD MUST BE CREATED IN THE SHAPE IT COMES BACK IN.
-  //
-  // The offline transport echoes what a create sent, so a create that sends
-  // its parts flat produces a record whose id cannot be read back — `from`
-  // looks for github's owner at `owner.login` and finds a bare string. The
-  // parts therefore go in at their `from` paths, appended AFTER the field
-  // literal so they win over the flat pair the seed emitted.
-  //
-  // The record key gets its own value rather than the seed's, so a created
-  // record is distinguishable from a seeded one in the same store.
   const idmake = 0 === idPartsOf(e).length ? '' :
     ', ' + idFromPairs(e, '-crud')
 
-  // NOT EVERY WRITABLE ENTITY IS READABLE. github's `app` declares create,
-  // update, remove and list — and no load at all, because the API offers no
-  // route that reads one app back. The round-trip read `ent.load$(...)` on
-  // nine such entities, got the null the provider correctly returns for a
-  // cmd it does not implement, and died on `loaded.id` — so the write path
-  // those tests existed to cover went unexercised.
-  //
-  // What can be checked still is: the update runs on the created entity
-  // itself, and the remove runs. What cannot be checked is stated in the
-  // file rather than quietly dropped.
   const hasLoad = e.cmds.includes('load')
 
   const body = hasLoad ? `${ind}  try {
@@ -489,8 +377,11 @@ ${ind}  }
 ${live ? `${ind}  if (!live) return t.skip(noServer())\n` : ''}${ind}  const seneca = await ${mk}
 ${ind}  const ent = seneca.entity('provider/${provider.lower}/${e.name}')
 
-${setup}${ind}  // Seneca's convention: an entity WITHOUT an id is a create. The API
-${ind}  // assigns the id itself, so the saved record comes back with one it chose.
+${setup}${ind}  // Seneca's convention: an entity WITHOUT an id is a create.${true === e.rkoncreate ?
+    ` This API
+${ind}  // keys ${e.name} records by \`${e.rk}\` and the create request requires it, so
+${ind}  // it is sent and comes back as the record's id.` : ` The API
+${ind}  // assigns the id itself, so the saved record comes back with one it chose.`}
 ${ind}  const made = await ent.make$({ ${pairs}${made}${idmake} }).save$()
 
 ${ind}  assert.ok(null != made.${idf})
@@ -507,12 +398,6 @@ ${body}${ind}})
 }
 
 
-// A source literal for one field, by kind.
-//
-// `$ARRAY` and `$OBJECT` are in the model's sentinel vocabulary and used to
-// fall through to the string branch, so a list field came out as
-// `tags: 'quick-tags'` — a type-incorrect body that a validating server
-// rejects, and a fixture that quietly stopped exercising non-scalar payloads.
 function fieldLiteral(f: any, tag: string): string {
   switch (f.kind) {
     case 'number': return '12345'
@@ -529,8 +414,7 @@ function fieldLiteral(f: any, tag: string): string {
 // shares with the seed.
 function seedLiteral(e: any, tag: string): string {
   return (e.fields || [])
-    .filter((f: any) =>
-      f.name !== e.idf && 'id' !== f.name && !e.parents.includes(f.name))
+    .filter((f: any) => ownField(e, f))
     .map((f: any) => `${jsKey(f.name)}: ${fieldLiteral(f, tag)}`)
     .join(', ')
 }
@@ -550,26 +434,10 @@ function seedRecord(e: any, idx: number): Record<string, any> {
     if (f.name === rkey) {
       out[f.name] = `${e.name}${idx}`
     }
-    // AN `id` THAT IS NOT THE ADDRESSING KEY IS SEEDED DISTINCTLY. Seeding
-    // both the same value made the offline suite unable to tell a provider
-    // that addresses records correctly from one that confuses the API's own
-    // `id` with the key its routes take — the seed agreed with either. Real
-    // GitHub never returns that: a pull has a global database `id` AND a
-    // repo-scoped `number`, and they differ.
     else if ('id' === f.name) {
       out[f.name] = `${e.name}-apiid-${idx}`
     }
     else if (e.parents.includes(f.name)) {
-      // A nested entity's parent id must match a record the parent seeds, or
-      // the offline store answers nothing and every nested test reads as a
-      // false pass. Reuses parentSeed's fallback rather than f.parentEntity
-      // directly: when no entity in the model shares this key's name (the
-      // common case for a scoping param like `user_id` with no `user`
-      // entity, or a same-named response field that means something else
-      // entirely, like GitHub's `owner`), f.parentEntity is '' and seeding
-      // '0' desynced the record from every query built against the SAME
-      // key via parentSeed (parentPairs, crudTest, ...) — 0 results, or a
-      // seeded field asserted against the wrong literal.
       out[f.name] = parentSeed(e, f.name)
     }
     else if ('number' === f.kind) {
@@ -589,39 +457,12 @@ function seedRecord(e: any, idx: number): Record<string, any> {
     }
   }
 
-  // THE ADDRESSING KEY IS ALWAYS PRESENT, even when the response schema has
-  // no field of that name.
-  //
-  // The offline transport is a store, and it can only answer a request by
-  // matching the request's own parameters against a stored record
-  // (TestFeature.buildArgs). github reads an org's artifact retention from
-  // `/orgs/{org}/actions/permissions/artifact-and-log-retention`, whose body
-  // is `{days, maximum_allowed_days}` — no org anywhere in it. The loop
-  // above stamps the key only onto a field that already exists, so such a
-  // record was seeded with nothing the provider addresses it by, every
-  // offline load of it answered 404, and forty-one generated tests failed on
-  // a null they could not have avoided.
-  //
-  // This is a property of the mock, not a claim about the API: a real
-  // response need not echo the path parameter that selected it, which is
-  // why the handler carries the request's own values across into the id
-  // rather than reading them back off the body.
   if ('' !== String(rkey) && null == out[rkey] &&
     0 === (Array.isArray(e.idparts) ? e.idparts.length : 0)) {
     out[rkey] = e.parents.includes(rkey) ?
       parentSeed(e, rkey) : `${e.name}${idx}`
   }
 
-  // THE SEED MODELS THE REAL RESPONSE, through the same `from` mapping the
-  // runtime reads. github's repo owner goes to `owner.login` and its name to
-  // `name`, because that is where the API puts them — so a record the mock
-  // returns is identifiable by exactly the code that identifies a real one.
-  //
-  // This only works because the offline transport now matches a request
-  // parameter against `id.from` as well as against its own name
-  // (TestFeature.buildArgs). Seeding this shape before that landed made
-  // every composite record unfindable: the mock looked for a field called
-  // `owner` and found an object.
   seedIdParts(e, out, idx)
 
   return out
@@ -706,10 +547,6 @@ module.exports = { SEED }
     })
 
 
-    // The message-level spec seneca-msg-test drives. TypeScript, compiled to
-    // dist-test by test/tsconfig.json — which is also why it must exist: the
-    // shipped tsconfig has `include: ["**/*.ts"]` and tsc fails outright on a
-    // config that matches no input.
     File({ name: 'basic.messages.ts' }, () => {
       Content(`/* Generated by @voxgig/sdkgen. Do not edit. */
 
@@ -803,12 +640,6 @@ describe('${provider.fileBase}', () => {
 
 `)
 
-      // Every flat entity (no parent keys), not just one "subject" — a
-      // provider with two or more flat siblings used to leave every one
-      // but the busiest untested beyond the accessor check above. A bare
-      // `list$()`/`load$(id)` call has no way to carry a parent key, so
-      // entities that need one are covered by the `nested` block below
-      // instead, with their keys filled in.
       const flat = provider.entities.filter((e: any) => 0 === e.parents.length)
 
       each(flat, (e: any) => {
@@ -840,7 +671,7 @@ describe('${provider.fileBase}', () => {
       .entity('provider/${provider.lower}/${e.name}')
       .load$('${entIdLiteral(e, '0')}')
 
-    assert.equal(found.${e.idf || 'id'}, '${entIdLiteral(e, '0')}')
+    assert.equal(found.id, '${entIdLiteral(e, '0')}')
     assert.equal(
       found.canon$({ string: true }),
       'provider/${provider.lower}/${e.name}',
@@ -873,13 +704,6 @@ describe('${provider.fileBase}', () => {
       // A nested entity cannot build its path without the parent id. That is
       // the mistake this target exists to make impossible, so pin it.
       each(nested, (e: any) => {
-        // A COMPOSITE-KEY ENTITY HAS NO SEPARATE PARENT GUARD to pin: its
-        // parents travel inside the id, so `need_<e>_<parent>` is not
-        // emitted and there is nothing that could throw "<parent> is
-        // required". What replaces it is a malformed id, which splitid_<e>
-        // refuses by name — so pin THAT instead, and keep the property the
-        // original test was defending: an incomplete address never reaches
-        // the API.
         if (0 < idPartsOf(e).length) {
           const sep = null != e.idsep && '' !== String(e.idsep) ? String(e.idsep) : '/'
           const shape = idPartsOf(e).join(sep)
@@ -888,16 +712,11 @@ describe('${provider.fileBase}', () => {
           // syntax error ("Invalid regular expression flags"). Escape every
           // regex metacharacter, not just the slash, so a future separator
           // cannot reintroduce this.
-          const shapeRe = shape.replace(/[.*+?^${}()|[\]\\\/]/g, '\\$&')
+          const shapeRe = regexLiteral(shape)
           const cmd = ['load', 'remove', 'update'].find((op: string) =>
             e.cmds.includes('remove' === op ? 'remove' : 'load' === op ? 'load' : 'save'))
 
           if (null != cmd) {
-            // THE OTHER REQUIRED KEYS STILL TRAVEL. A composite id carries
-            // the parts and nothing else, so an entity that also requires a
-            // plain query key — github's api_insights_summary_stat needs a
-            // `min_timestamp` besides its `actor_type/actor_id` — tripped
-            // that guard first and this test asserted the wrong refusal.
             const rest = queryPairs(e, false)
             const call = 'remove' === cmd ?
               `remove$({ ${rest}id: 'incomplete' })` :
@@ -920,23 +739,10 @@ describe('${provider.fileBase}', () => {
           }
         }
 
-        // EVERY parent key, not just the first. An entity nested two levels
-        // deep is guarded on both, so a test supplying only the alphabetically
-        // first tripped the second guard and failed on the code it was meant
-        // to be exercising.
         const key = e.parents[0]
         const pairs = e.parents
-          .map((k: string) => `${k}: '${parentSeed(e, k)}'`).join(', ')
-
-        // The guard is PER OP (Main's opParents), not a blanket property of
-        // the entity, so the op this test calls has to be one that actually
-        // requires `key` — hardcoding `list` assumed every nested entity's
-        // list is parent-scoped, which fails for e.g. an entity guarded on
-        // load/update/remove but whose list is unscoped (GitHub's `repo`:
-        // owner guards load, not list).
-        // AND NOT A CMD THAT REFUSES. A refusing cmd emits no guards at all
-        // — the refusal replaces them — so a test driving it asserted a
-        // "<key> is required" message that no longer exists.
+          .map((k: string) => `${jsKey(k)}: '${parentSeed(e, k)}'`).join(', ')
+
         const guardOp = ['list', 'load', 'update', 'remove']
           .find((op: string) => (e.opParents[op] || []).includes(key) &&
             !cmdRefuses(e, op))
@@ -945,12 +751,6 @@ describe('${provider.fileBase}', () => {
         // trip, because the parents live inside the id. needs-full-id above
         // is what pins the same property for those entities.
         if (null != guardOp && 0 === idPartsOf(e).length) {
-          // SENECA HAS NO `update$`. The entity cmds are load$/save$/list$/
-          // remove$, and an update is a `save$` on an entity that CARRIES an
-          // id — that is the whole convention this provider is built on.
-          // Emitting `update$({id})` produced eight tests that failed with
-          // "update$ is not a function", so they asserted nothing about the
-          // guard they were written for.
           const call =
             'list' === guardOp ? `${guardOp}$({})` :
               'update' === guardOp ?
@@ -963,19 +763,13 @@ describe('${provider.fileBase}', () => {
 
     await assert.rejects(
       () => seneca.entity('provider/${provider.lower}/${e.name}').${call},
-      /${key} is required/,
+      /${regexLiteral(key)} is required/,
     )
   })
 
 `)
         }
         if (e.cmds.includes('list')) {
-          // Assert on the SEEDED RECORDS, not merely that an array came back.
-          // `Array.isArray` is true of the empty array, so the nested-list
-          // test passed while proving nothing: the seed puts both of this
-          // entity's records under the same parent, so both must come back,
-          // under this plugin's canon, still carrying the parent key that
-          // addressed them.
           Content(`
   it('${e.name}-list', async () => {
     const seneca = await makeSeneca()
@@ -990,7 +784,7 @@ describe('${provider.fileBase}', () => {
     )
     ${0 < idPartsOf(e).length ?
       `assert.equal(list[0].id, '${entIdLiteral(e, '0')}')` :
-      `assert.equal(list[0].${key}, '${parentSeed(e, key)}')`}
+      `assert.equal(${jsProp('list[0]', key)}, '${parentSeed(e, key)}')`}
   })
 
 `)
@@ -1035,7 +829,16 @@ ${!loadHasKey(e) ? '' : `
       // transport implements create/update/remove, so this needs no server.
       each(provider.entities, (e: any) => {
         if (e.cmds.includes('save') && e.cmds.includes('remove')) {
-          if (compositeRoundTrip(e) && removeAddresses(e) &&
+          if (!e.canonicalOps.includes('create')) {
+            Content(`
+  // NO ${e.name} create/update/remove round-trip: THIS API HAS NO CREATE
+  // ROUTE FOR A ${e.name}, so there is no record of this test's own to
+  // update and remove. The update and remove cmds are still exercised
+  // through the guard and refusal tests above.
+
+`)
+          }
+          else if (compositeRoundTrip(e) && removeAddresses(e) &&
             !cmdRefuses(e, 'update')) {
             Content(`
 ` + crudTest(provider, e, 'offline'))
@@ -1094,12 +897,6 @@ ${!loadHasKey(e) ? '' : `
       })
 
 
-      // THE REFUSAL. A cmd whose only route addresses a different resource
-      // must not send the request — `migration`'s remove would delete a
-      // repository's migration archive, `user`'s a GPG key, `pull`'s a
-      // review comment, with the caller's id dropped and a successful reply.
-      // That is the worst possible answer, so it is refused, and refused
-      // BY NAME: the message says which key the route does not take.
       each(provider.entities, (e: any) => {
         for (const cmd of ['remove', 'update']) {
           if (true !== (e.idmisaddressed || {})[cmd]) {
@@ -1127,18 +924,6 @@ ${!loadHasKey(e) ? '' : `
       })
 
 
-      // ACTIONS — the `action$` directive.
-      //
-      // The test that matters most is the NEGATIVE one. A name this entity
-      // does not have must throw, because the alternative is that the plugin
-      // ignores the key and performs an ordinary save: a call that succeeds,
-      // reports success, and did something else. That is exactly how GitHub's
-      // `merge` reached its provider as an "update" — the endpoint existed,
-      // the plugin had no way to name it, and nothing said so.
-      //
-      // Generated for EVERY entity, whether it has actions or not: an entity
-      // with none is the case most likely to be typed at by mistake, and its
-      // error is the one that names the empty set.
       each(provider.entities, (e: any) => {
         const pairs = parentPairs(e, false)
         const acts = e.actionList.filter((a: any) => 'save' === a.cmd)
@@ -1150,7 +935,7 @@ ${!loadHasKey(e) ? '' : `
 
     await assert.rejects(
       () => seneca.entity('provider/${provider.lower}/${e.name}')
-        .make$({ ${pairs}id: '${e.name}0' })
+        .make$({ ${pairs}id: '${entIdLiteral(e, '0')}' })
         .directive$({ action$: 'no_such_action' })
         .save$(),
       /action\\$ "no_such_action" is not an action/,
@@ -1175,22 +960,6 @@ ${!loadHasKey(e) ? '' : `
 `)
         }
 
-        // THE SILENT-DROP PIN. A save with no `action$` must still take the
-        // canonical route: the whole mechanism is worthless if adding it
-        // changed what an ordinary call does, and this is the assertion that
-        // would fail if the action branch ever ran unconditionally.
-        //
-        // GATED ON THE ENTITY BEING ABLE TO PERFORM ONE, which is three
-        // separate facts and was none of them. The test loads a record, edits
-        // it and saves it back, so it needs a `load` cmd to fetch with, a
-        // canonical `update` route to save to — an entity whose only update
-        // point is the action has no plain save at all — and a mutable field
-        // to change. Emitted without those it ships a red suite to a package
-        // whose action works perfectly, which is the worst kind of generated
-        // test: it fails for a reason that is not about the code it names.
-        //
-        // The ACTION tests below are not gated on any of this. They are what
-        // this entity does have.
         const canPlainSave = e.cmds.includes('load') &&
           e.canonicalOps.includes('update') &&
           !cmdRefuses(e, 'update')
@@ -1219,23 +988,6 @@ ${!loadHasKey(e) ? '' : `
 `)
           }
 
-          // And the POSITIVE case: a name the entity DOES have is accepted
-          // and dispatched. `directive$` rather than `make$({ action$ })`
-          // because make$ drops an unknown trailing-`$` key before any store
-          // sees it — see the README's Actions section.
-          //
-          // WHAT THIS DOES NOT ASSERT, and why. The offline mock answers by
-          // matching a seeded record against the parameters of the point the
-          // SDK chose, and the seed is built for the CANONICAL route — an
-          // action route with parameters of its own has nothing seeded to
-          // match, so the mock's honest answer is a 404. Asserting a returned
-          // record here would mean generating a test that fails for every API
-          // whose actions are not shaped like its CRUD.
-          //
-          // The provider's own responsibility is to accept the name and route
-          // it. That is what is asserted: whatever comes back, it is not this
-          // plugin refusing the action. Paired with the unknown-action test
-          // above, the two together say the map holds exactly the right names.
           const act = acts[0]
           Content(`
   // \`${act.action}\` is an action of \`${act.op}\`: ${act.path}
@@ -1245,7 +997,7 @@ ${!loadHasKey(e) ? '' : `
 
     try {
       await seneca.entity('provider/${provider.lower}/${e.name}')
-        .make$({ ${pairs}id: '${e.name}0' })
+        .make$({ ${pairs}id: '${entIdLiteral(e, '0')}' })
         .directive$({ action$: '${act.action}' })
         .save$()
     }
@@ -1293,17 +1045,25 @@ ${!loadHasKey(e) ? '' : `
 
 `)
         }
-        if (subject.cmds.includes('load')) {
+        // A nested subject needs its parent ids from the server, and a
+        // composite one an id built from them; neither is available to a
+        // literal, so the missing-record read is emitted only where it can
+        // address something.
+        if (subject.cmds.includes('load') && 0 === idPartsOf(subject).length &&
+          liveParentsResolvable(provider, subject)) {
+          const missing = 0 === subject.parents.length ?
+            `'nosuch${subject.name}'` :
+            `{ ${queryPairs(subject, true)}id: 'nosuch${subject.name}' }`
           Content(`    // A read of something that is not there is \`null\`, live as well as
     // offline: the provider's 404 handling is the same code path either way.
     it('${subject.name}-load-missing', async (t) => {
       if (!live) return t.skip(noServer())
       const seneca = await makeSeneca(liveOpts())
 
-      assert.equal(
+${liveParentSetup(provider, subject, '    ')}      assert.equal(
         await seneca
           .entity('provider/${provider.lower}/${subject.name}')
-          .load$('nosuch${subject.name}'),
+          .load$(${missing}),
         null,
       )
     })
@@ -1311,17 +1071,9 @@ ${!loadHasKey(e) ? '' : `
 `)
         }
 
-        // The write path against a REAL server. The mock answers the shape the
-        // SDK expects by construction; only a live run proves the request the
-        // provider builds is one the API actually accepts — which for a nested
-        // entity means the parent id reached the URL rather than the body.
-        //
-        // Emitted only when a live parent id is OBTAINABLE (see
-        // liveParentsResolvable): against a real server the parent has to be
-        // looked up, and an entity whose parent cannot be listed offers no
-        // honest way to get one.
         each(provider.entities, (e: any) => {
           if (e.cmds.includes('save') && e.cmds.includes('remove') &&
+            e.canonicalOps.includes('create') &&
             liveParentsResolvable(provider, e) && compositeRoundTrip(e)) {
             Content(crudTest(provider, e, 'live'))
           }
@@ -1332,10 +1084,6 @@ ${!loadHasKey(e) ? '' : `
 `)
       }
 
-      // Repository hygiene, from the @seneca/maintain dependency this package
-      // declares. Two of its checks report a fault that is not there, because
-      // of WHERE they run rather than what they find, so each is excluded
-      // only in the environments that break it.
       Content(`
   it('maintain', async () => {
     const exclude = []
@@ -1430,13 +1178,6 @@ async function makeSeneca(pluginopts) {
 })
 
 
-// --- test/live.js, test/quick.js --------------------------------------------
-//
-// Manual scripts, not part of `npm test`: they need the companion server in
-// the SDK repo's `app/`, which is not published. Generated because the path
-// to that server is knowable — it is the inverse of this target's own
-// `output: path` — so the instruction can be exact rather than "start the
-// server somehow".
 
 const Scripts = cmp(function Scripts(props: any) {
   const { provider } = props
@@ -1513,7 +1254,7 @@ async function run() {
           Content(`  // ${e.name}: needs ${e.parents.join(', ')}; no listable parent to take
   // one from, so supply it yourself:
   //   await seneca.entity('provider/${provider.lower}/${e.name}')
-  //     .list$({ ${e.parents.map((k: string) => `${k}: '...'`).join(', ')} })
+  //     .list$({ ${e.parents.map((k: string) => `${jsKey(k)}: '...'`).join(', ')} })
 
 `)
           return
@@ -1527,7 +1268,7 @@ async function run() {
   if (0 < ${parent.name}s.length) {
     console.log('${e.name.toUpperCase()}', await seneca
       .entity('provider/${provider.lower}/${e.name}')
-      .list$({ ${key}: ${parent.name}s[0].${parent.idf || 'id'} }))
+      .list$({ ${jsKey(key)}: ${parent.name}s[0].id }))
   }
 
 `)
@@ -1540,10 +1281,8 @@ async function run() {
     // The write cycle, kept separate: it MUTATES the server, so it is not
     // something to run by reflex. It cleans up after itself.
     if (subject.cmds.includes('save') && subject.cmds.includes('remove')) {
-      const idf = subject.idf || 'id'
-      const writable = subject.fields
-        .filter((f: any) => f.name !== idf && f.name !== 'id')
-        .filter((f: any) => !subject.parents.includes(f.name))
+      const idf = 'id'
+      const writable = subject.fields.filter((f: any) => ownField(subject, f))
 
       const make = writable
         .map((f: any) => `${jsKey(f.name)}: ${fieldLiteral(f, 'quick')}`)
@@ -1567,7 +1306,9 @@ run()
 async function run() {
   const seneca = await makeSeneca()
 
-  // Create: the API assigns the id, so none is supplied here.
+  // Create: ${true === subject.rkoncreate ?
+            `this API keys ${subject.name} records by \`${subject.rk}\` and the create\n  // request requires it, so it is sent and comes back as the id.` :
+            'the API assigns the id, so none is supplied here.'}
   let ${subject.name} = await seneca
     .entity('provider/${provider.lower}/${subject.name}')
     .make$({ ${make} })
@@ -1580,8 +1321,8 @@ async function run() {
 `)
         // Change something an assertion could SEE. A container field would be
         // rewritten to the same empty literal, which demonstrates nothing.
-        const upd = writable.find((f: any) =>
-          'string' === f.kind || 'number' === f.kind) || null
+        const upd = writable.find((f: any) => changeField(subject, f) &&
+          ('string' === f.kind || 'number' === f.kind)) || null
 
         if (subject.ops.includes('update') && null != upd) {
           const f = upd
@@ -1601,16 +1342,6 @@ async function run() {
 `)
         }
 
-        // The NESTED write, which is the leg worth having a manual script
-        // for: it is the one where the parent id has to reach the URL rather
-        // than the body, and where a provider that forgets it reports an
-        // opaque 404 instead of saying what is missing.
-        //
-        // Only for a child of the record just created — then the parent id is
-        // `id`, already in hand, and removing the child leaves the server
-        // exactly as found. A child of anything else would need its own
-        // lookup, which belongs in the test suite rather than in a script
-        // whose whole point is to be readable.
         const child = provider.entities.find((e: any) =>
           1 === e.parents.length &&
           e.parentEntity === subject.name &&
@@ -1618,10 +1349,9 @@ async function run() {
 
         if (null != child) {
           const ckey = child.parents[0]
-          const cidf = child.idf || 'id'
+          const cidf = 'id'
           const cmake = (child.fields || [])
-            .filter((f: any) =>
-              f.name !== cidf && 'id' !== f.name && !child.parents.includes(f.name))
+            .filter((f: any) => ownField(child, f))
             .map((f: any) => `${jsKey(f.name)}: ${fieldLiteral(f, 'quick')}`)
             .join(', ')
 
@@ -1629,13 +1359,13 @@ async function run() {
     // goes under the ${subject.name} just created — and comes back off again.
     const ${child.name} = await seneca
       .entity('provider/${provider.lower}/${child.name}')
-      .make$({ ${ckey}: id${'' === cmake ? '' : ', ' + cmake} })
+      .make$({ ${jsKey(ckey)}: id${'' === cmake ? '' : ', ' + cmake} })
       .save$()
     console.log('${child.name.toUpperCase()} CREATED', ${child.name})
 
     await seneca
       .entity('provider/${provider.lower}/${child.name}')
-      .remove$({ ${ckey}: id, ${cidf}: ${child.name}.${cidf} })
+      .remove$({ ${jsKey(ckey)}: id, ${cidf}: ${child.name}.${cidf} })
     console.log('${child.name.toUpperCase()} REMOVED')
 
 `)
@@ -1663,7 +1393,6 @@ async function run() {
 })
 
 
-// --- .github/workflows/build.yml --------------------------------------------
 
 const Workflow = cmp(function Workflow(props: any) {
   const { provider } = props
@@ -1765,38 +1494,11 @@ ${!provider.liveApp ? '' : `
 `}
       - run: npm install${provider.sdkInstallFlag}
 
-      # The Seneca host framework is a PEER dependency, so the test suite needs
-      # it installed explicitly. --no-save keeps npm from rewriting the peer
-      # ranges in package.json to carets on what it happened to resolve, which
-      # would have the build testing a manifest the repo never authored.
-      - run: npm i --no-save seneca seneca-entity seneca-promisify @seneca/provider @seneca/env
-
       - run: npm run build --if-present
       - run: npm test
 `)
       })
 
-      // --- publish.yml ---------------------------------------------------
-      //
-      // Release on a `v*` tag push, via GitHub OIDC Trusted Publishing — no
-      // NPM_TOKEN secret anywhere. `id-token: write` lets npm exchange a
-      // GitHub OIDC token for a short-lived publish credential, and npm
-      // attaches provenance automatically.
-      //
-      // TWO THINGS ARE LOAD-BEARING AND EASY TO GET WRONG.
-      //
-      // The FILENAME. npm's trusted publisher is registered against this
-      // file's name, so renaming it breaks publishing until the npm-side
-      // configuration is changed to match. It is publish.yml deliberately.
-      //
-      // `npm install`, NOT `npm ci`. A Seneca plugin does not commit its
-      // lockfile (see .gitignore), so there is nothing for ci to install
-      // from — it fails outright. The SDK repo commits one and uses ci; this
-      // package cannot.
-      //
-      // The host framework is installed explicitly for the same reason
-      // build.yml does it: seneca and its plugins are PEER dependencies, and
-      // the test suite requires them directly.
       File({ name: 'publish.yml' }, () => {
         Content(`# Generated by @voxgig/sdkgen. Do not edit.
 #
@@ -1864,16 +1566,6 @@ jobs:
       # install, not ci: this package does not commit a lockfile.
       - run: npm install${provider.sdkInstallFlag}
 
-      # The Seneca host framework is a PEER dependency, so the test suite
-      # needs it installed explicitly.
-      #
-      # --no-save IS LOAD-BEARING. Without it npm rewrites the peer ranges in
-      # package.json to carets on whatever it resolved, and a later publish
-      # ships that rewritten manifest — so an authored \`>=26\` reaches
-      # consumers as \`^28.1.0\` and the package refuses to install for anyone
-      # on a newer major. The repo looks fine; only the artifact is narrowed.
-      - run: npm i --no-save seneca seneca-entity seneca-promisify @seneca/provider @seneca/env
-
       - run: npm run build
       - run: npm test
 
@@ -1957,13 +1649,6 @@ jobs:
 })
 
 
-// --- README.md ---------------------------------------------------------------
-//
-// The heading set is NOT free: @seneca/maintain checks a Seneca plugin README
-// for "Quick Example", "More Examples", "Motivation", "Support", "API",
-// "Contributing" and "Background", and the generated `maintain` test fails
-// without them. That check is the reason to generate this file rather than
-// leave it to a maintainer.
 
 const Readme = cmp(function Readme(props: any) {
   const { provider } = props
@@ -2044,23 +1729,13 @@ await seneca.ready()
 `)
     }
     if (subject.cmds.includes('load')) {
-      // THE FIRST RUNNABLE EXAMPLE HAS TO RUN. `load$('some-id')` passes a
-      // bare id and nothing else, but the generated handler calls
-      // `need_<entity>_<parent>()` on every parent key before it reaches the
-      // SDK — so for any entity that has one, the README's opening example
-      // threw `<entity> load: <parent> is required`. Show the object form
-      // with the parent keys the handler actually enforces; the bare-string
-      // form stays for a parentless entity, where it is correct and shorter.
-      // A COMPOSITE KEY IS ONE STRING, not a bag of keys. Its parents travel
-      // inside the id, so the object form with them alongside is the shape
-      // its own handler rejects — the example has to show the joined id.
       const cparts = idPartsOf(subject)
       const loadArg = 0 < cparts.length ?
         `'${cparts.map((p: string) => 'some-' + p).join(
           null != subject.idsep && '' !== String(subject.idsep) ?
             String(subject.idsep) : '/')}'` :
         0 === subject.parents.length ? `'some-id'` :
-          `{ ` + subject.parents.map((p: string) => `${p}: 'some-${p}'`).join(', ') +
+          `{ ` + subject.parents.map((p: string) => `${jsKey(p)}: 'some-${p}'`).join(', ') +
           `, id: 'some-id' }`
       Content(`const ${subject.name} = await seneca
   .entity('provider/${provider.lower}/${subject.name}').load$(${loadArg})
@@ -2099,9 +1774,6 @@ Each API entity is exposed as a Seneca entity under
 | Seneca entity | Commands | Fields |
 | --- | --- | --- |
 `)
-    // Fields as well as commands: a reader deciding whether this plugin
-    // covers what they need has to know what a record CONTAINS, and the
-    // table used to answer only half the question.
     each(provider.entities, (e: any) => {
       const fields = 0 === e.fields.length ? '—' :
         e.fields.map((f: any) => '`' + f.name + '`').join(', ')
@@ -2124,18 +1796,6 @@ missing key, rather than failing as an opaque 404 from a half-built URL.
       })
     }
 
-    // CUSTOM ACTIONS.
-    //
-    // apidef folds a non-CRUD verb into an ordinary op as an alternative
-    // point, and the SDK reaches it with `$action` in the call's argument.
-    // The `ts` target documents this in its own REFERENCE.md and the same
-    // treatment belongs here, because the Seneca spelling is DIFFERENT
-    // (`action$`, trailing dollar, Seneca's directive convention) and a
-    // reader who has only ever seen the SDK's would guess wrong.
-    //
-    // Undocumented, this is the state the plugin was in before: a GitHub
-    // provider with a `pull` entity and no way to merge a pull request at
-    // all, because nothing anywhere said the endpoint existed.
     const acting = provider.entities.filter((e: any) => 0 < e.actionList.length)
 
     if (0 < acting.length) {
@@ -2337,33 +1997,6 @@ ${provider.api} API definition, against the
 })
 
 
-// --- doc/tutorial.md ---------------------------------------------------------
-//
-// The Diataxis TUTORIAL: an empty folder to a working script in about fifteen
-// minutes. It teaches, so it is deliberately narrower than the other three
-// documents — one path, no alternatives, and no decisions asked of the
-// reader.
-//
-// Two decisions shape this component.
-//
-// FIRST, a tutorial must never ask the reader to invent a value. Every id in
-// the script is therefore either seeded here (offline) or read back from a
-// list call (live) — never a literal that only happens to exist on the
-// author's machine. That is also why a declared server is not by itself
-// enough to choose the live lesson: the primary entity must be listable, and
-// a nested primary entity must have a listable parent, or there is no honest
-// way to come by the first id. Failing that the offline lesson runs, which is
-// a complete tutorial in its own right rather than an apology for a missing
-// server.
-//
-// SECOND, the step numbers are computed rather than written, because which
-// steps exist depends on which cmds the model declares. `step()` counts as it
-// emits, and the prose refers to what a step did rather than to a number that
-// may not be there.
-//
-// The offline seed reuses seedRecord() — the same function behind
-// test/seed.js — so what the reader is told to paste has the shape the SDK
-// really answers with.
 
 const DocTutorial = cmp(function DocTutorial(props: any) {
   const { provider } = props
@@ -2386,7 +2019,7 @@ const DocTutorial = cmp(function DocTutorial(props: any) {
     .sort((a: any, b: any) =>
       (a.parents.length - b.parents.length) || (b.cmds.length - a.cmds.length))[0]
 
-  const idf = subject.idf || 'id'
+  const idf = 'id'
   const subjParent = 0 < subject.parents.length ?
     entOf(subject.parentEntity) : null
 
@@ -2420,19 +2053,14 @@ const DocTutorial = cmp(function DocTutorial(props: any) {
 
   // The value seedRecord() gives a parent key, so a query written here finds
   // the seeded record instead of quietly matching nothing.
-  const seedParentVal = (e: any, k: string) => {
-    const f = (e.fields || []).find((f: any) => f.name === k)
-    const pe = (null != f && '' !== f.parentEntity) ? f.parentEntity :
-      (k === e.parents[0] ? (e.parentEntity || '') : '')
-    return `${pe}0`
-  }
+  const seedParentVal = (e: any, k: string) => parentSeed(e, k)
 
   // A seed record guaranteed to carry its id and its parent keys.
   // seedRecord() emits only the fields the model marks required, and a record
   // missing its parent key is invisible to the very query this lesson makes.
   const demoRecord = (e: any, idx: number) => {
     const rec: any = seedRecord(e, idx)
-    const eidf = e.idf || 'id'
+    const eidf = e.rk || 'id'
     if (null == rec[eidf]) {
       rec[eidf] = `${e.name}${idx}`
     }
@@ -2482,13 +2110,13 @@ const DocTutorial = cmp(function DocTutorial(props: any) {
   const ${plural(subjParent.name)} = await seneca
     .entity('${canon(subjParent.name)}')
     .list$()
-  const ${ident(subject.parents[0])} = ${plural(subjParent.name)}[0].${subjParent.idf || 'id'}
+  const ${ident(subject.parents[0])} = ${plural(subjParent.name)}[0].id
 
 ` : ''
 
   // Fields worth printing, and worth writing: not the id, not a parent key.
-  const plainFields = subject.fields.filter((f: any) =>
-    f.name !== idf && 'id' !== f.name && !subject.parents.includes(f.name))
+  const plainFields = subject.fields.filter((f: any) => ownField(subject, f))
+  const changeFields = plainFields.filter((f: any) => changeField(subject, f))
   const shown = plainFields.slice(0, 2)
   const litval = (f: any, alt: boolean) =>
     'number' === f.kind ? (alt ? '4321' : '1234') :
@@ -2504,7 +2132,8 @@ const DocTutorial = cmp(function DocTutorial(props: any) {
   // Creating a record with nothing in it teaches nothing, so the write step
   // needs at least one field the caller actually supplies.
   const canWrite = subject.cmds.includes('save') && 0 < plainFields.length
-  const canUpdate = canWrite && subject.ops.includes('update')
+  const canUpdate = canWrite && subject.ops.includes('update') &&
+    0 < changeFields.length
   const canRemove = canWrite && subject.cmds.includes('remove')
 
   const cmdList = subject.cmds.map((c: string) => '`' + c + '$`').join(', ')
@@ -2714,8 +2343,9 @@ You should see:
 \`\`\`
 
 Two details of that configuration are worth a moment. The \`apikey\` is
-declared even though nothing here asks for credentials — an empty
-value simply means no \`authorization\` header is sent. Every Seneca
+declared even though nothing here asks for credentials — ${provider.authActive ?
+      'an empty\nvalue simply means no credential is sent' :
+      'this API declares\nno authentication, so the value is never read'}. Every Seneca
 provider is configured the same way, so an application that later moves
 to an authenticated service changes one value rather than its shape.
 And \`get:info\` is answered by the plugin itself, without calling the
@@ -2818,9 +2448,13 @@ so add:
   console.log('created with id', ${subjOne}.${idf})
 \`\`\`
 
-Run it, and note the id printed. It is **not** one you chose — the
+${true === subject.rkoncreate ?
+        `Run it, and note the id printed: it is the \`${subject.rk}\` you sent.
+The ${source} addresses ${subject.name} records by that key rather than by an
+id of its own, and the provider carries it as the entity's id.` :
+        `Run it, and note the id printed. It is **not** one you chose — the
 ${source} assigns ids itself and ignores any you send. That is worth
-knowing before you write code that assumes otherwise.
+knowing before you write code that assumes otherwise.`}
 
 `)
 
@@ -2830,10 +2464,10 @@ rather than a create, and \`save$\` decides between the two on exactly
 that:
 
 \`\`\`js
-  ${subjOne}.${plainFields[0].name} = ${litval(plainFields[0], true)}
+  ${subjOne}.${changeFields[0].name} = ${litval(changeFields[0], true)}
   ${subjOne} = await ${subjOne}.save$()
 
-  console.log('updated:', ${subjOne}.${plainFields[0].name})
+  console.log('updated:', ${subjOne}.${changeFields[0].name})
 \`\`\`
 
 `)
@@ -2882,7 +2516,7 @@ They behave the same way on every entity this plugin exposes.
 
     if (null != child) {
       const ckey = child.parents[0]
-      const cidf = child.idf || 'id'
+      const cidf = 'id'
       const cparent = null == childParent ? 'their parent' :
         `${childParent.name} records`
       const cop = child.cmds.includes('list') ? 'list' : 'load'
@@ -2899,7 +2533,7 @@ They behave the same way on every entity this plugin exposes.
         `  const ${plural(childParent.name)} = await seneca
     .entity('${canon(childParent.name)}')
     .list$()
-  const ${ident(ckey)} = ${plural(childParent.name)}[0].${childParent.idf || 'id'}
+  const ${ident(ckey)} = ${plural(childParent.name)}[0].id
 
 ` : ''
 
@@ -3004,7 +2638,9 @@ the way you saw:
     }
     if (canWrite) {
       Content(`- \`save$\` creates without an id and updates with one, and the
-  ${source} chooses the id.
+  ${true === subject.rkoncreate ?
+          `id is the \`${subject.rk}\` the create sends.` :
+          `${source} chooses the id.`}
 `)
     }
     if (offline) {
@@ -3030,21 +2666,6 @@ the way you saw:
 })
 
 
-// --- doc/how-to.md ----------------------------------------------------------
-//
-// The task-oriented quadrant of the Diataxis set: one problem per section, for
-// a reader who already has the plugin loaded. It instructs and does not
-// explain — anything that starts justifying a design choice belongs in
-// explanation.md and is linked to instead.
-//
-// Two decisions worth naming. First, the section list is built as data before
-// anything is emitted, so the table of contents and the sections themselves
-// are produced from the SAME guards and cannot drift: a recipe that is
-// suppressed because no entity declares the cmd also loses its TOC entry.
-// Second, every example id is the one `seedRecord` gives that entity, so the
-// examples here and the seed in test/seed.js agree — the offline recipe can
-// then be copied verbatim and the ids used in every other recipe will
-// actually resolve.
 
 const DocHowto = cmp(function DocHowto(props: any) {
   const { provider } = props
@@ -3072,19 +2693,20 @@ const DocHowto = cmp(function DocHowto(props: any) {
   }
 
   const canon = (e: any) => `provider/${provider.lower}/${e.name}`
-  const idf = (e: any) => e.idf || 'id'
+
+  // Seneca's key, on every entity: the provider translates it to whatever
+  // the API calls it. `apiKey` is that name, for the SDK-direct examples.
+  const idf = (_e: any) => 'id'
+  const apiKey = (e: any) => e.rk || 'id'
 
   // A parent key's example value. This MIRRORS seedRecord rather than
   // inventing something more readable: the offline recipe below seeds with
   // seedRecord, and an example id that does not match what was seeded turns
   // every other recipe into a lookup that answers null.
-  const parentVal = (e: any, k: string) => {
-    const f = e.fields.find((f: any) => f.name === k)
-    return null == f ? `${k.replace(/_id$/, '')}0` : `${f.parentEntity}0`
-  }
+  const parentVal = (e: any, k: string) => parentSeed(e, k)
 
   const parentArgs = (e: any) =>
-    e.parents.map((k: string) => `${k}: '${parentVal(e, k)}'`).join(', ')
+    e.parents.map((k: string) => `${jsKey(k)}: '${parentVal(e, k)}'`).join(', ')
 
   // A query naming ONE record. A top-level entity takes the bare id string;
   // a nested one cannot, because it is identified by the whole set of keys.
@@ -3096,18 +2718,11 @@ const DocHowto = cmp(function DocHowto(props: any) {
 
   // The SDK's own entity ops always take an object, even for a bare id.
   const sdkLoadArgs = (e: any) => 0 === e.parents.length ?
-    `{ ${idf(e)}: '${e.name}0' }` :
-    `{ ${parentArgs(e)}, ${idf(e)}: '${e.name}0' }`
+    `{ ${jsKey(apiKey(e))}: '${e.name}0' }` :
+    `{ ${parentArgs(e)}, ${jsKey(apiKey(e))}: '${e.name}0' }`
 
   const key = (k: string) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : `'${k}'`
 
-  // SERIALISE, DO NOT COERCE. `String(value)` renders an object as
-  // `[object Object]` and an empty array as the empty string, so a field of
-  // either kind turned the documented create recipe into a syntax error
-  // (`code_of_conduct: [object Object]`, `labels: ,`). Every value a seed
-  // record can hold — string, number, boolean, array, plain object — now
-  // emits as the JS literal it claims to be, recursively, so a reader can
-  // copy the block and run it.
   const jsval = (v: any): string => {
     if (null === v || undefined === v) {
       return 'null'
@@ -3131,16 +2746,18 @@ const DocHowto = cmp(function DocHowto(props: any) {
 
   // What a create sends: the seeded record without its id, because the id is
   // the API's to assign. Parent keys stay — a nested write carries them in
-  // the data rather than the query.
+  // the data rather than the query — and so does a key the create request
+  // requires, which is the caller's to supply.
   const createData = (e: any) => {
     const rec = seedRecord(e, 0)
-    delete rec[idf(e)]
+    if (true !== e.rkoncreate) {
+      delete rec[apiKey(e)]
+    }
     delete rec.id
     return rec
   }
 
-  const changeable = (e: any) => e.fields.find((f: any) =>
-    f.name !== idf(e) && 'id' !== f.name && !e.parents.includes(f.name))
+  const changeable = (e: any) => e.fields.find((f: any) => changeField(e, f))
 
   const newValue = (f: any) => 'number' === f.kind ? '999' :
     'boolean' === f.kind ? 'true' : `'${f.name}-changed'`
@@ -3199,9 +2816,10 @@ const ${eLoad.name} = await seneca
   .entity('${canon(eLoad)}')
   .load$(${oneArgs(eLoad)})
 \`\`\`
-${'id' === idf(eLoad) ? '' : `
-The id field for \`${eLoad.name}\` is \`${idf(eLoad)}\`, so that is the
-key to supply.
+${'id' === apiKey(eLoad) ? '' : `
+The API addresses \`${eLoad.name}\` records by \`${apiKey(eLoad)}\`; the
+provider carries that value as the entity's \`id\`, so the query is the
+same as for any other entity.
 `}
 A record that is not there comes back as \`null\`. It is not an error and
 it does not throw, so test the value rather than wrapping the call:
@@ -3418,28 +3036,59 @@ companion test server listens, so local development usually needs no
 \`base\` at all.`}`)
 
 
-  sec('Send an API key', `Credentials are not a plugin option: they come through the provider
+  if (!provider.authActive) {
+    sec('Send an API key', `The ${provider.api} definition declares no authentication, so this plugin
+reads no key and adds no credential to any request. The \`apikey\` entry in
+the provider configuration is the convention's shape, and stays empty:
+
+\`\`\`js
+  .use('provider', {
+    provider: {
+      ${provider.lower}: {
+        keys: {
+          apikey: { value: '' },
+        },
+      },
+    },
+  })
+\`\`\`
+
+To send a header the definition does not describe, supply it through
+\`sdk\`; it goes on every request as given:
+
+\`\`\`js
+.use('${provider.pkgName}', {
+  sdk: { headers: { 'x-api-key': process.env.${provider.ENV}_APIKEY } },
+})
+\`\`\``)
+  }
+  else {
+    sec('Send an API key', `Credentials are not a plugin option: they come through the provider
 convention, so that every provider in an application is configured the
 same way. Declare the variable with \`env\` and set the key under this
 provider's name:
 
 \`\`\`js
   .use('env', {
-    var: { $${provider.ENV}_APIKEY: String },
+    var: { $${provider.ENV}_APIKEY: String${provider.authBasic ?
+        `, $${provider.ENV}_SECRET: String` : ''} },
   })
   .use('provider', {
     provider: {
       ${provider.lower}: {
         keys: {
-          apikey: { value: '$${provider.ENV}_APIKEY' },
+          apikey: { value: '$${provider.ENV}_APIKEY' },${provider.authBasic ? `
+          secret: { value: '$${provider.ENV}_SECRET' },` : ''}
         },
       },
     },
   })
 \`\`\`
 
-Every request then carries \`authorization: Bearer <apikey>\`. An absent
-or empty key adds no header at all, so an API that needs no credentials
+Every request then carries ${credentialWire(provider)}.${provider.authBasic ? `
+HTTP Basic needs the pair: with either \`apikey\` or \`secret\` missing, no
+credential is sent.` : ''} An absent
+or empty key sends no credential at all, so an API that needs none
 is configured in exactly the same shape with an empty value — which is
 why it is worth writing even when there is nothing to send. An
 application that later moves to an authenticated service then changes one
@@ -3453,6 +3102,7 @@ For a different scheme, set the header yourself. Headers supplied through
   sdk: { headers: { 'x-api-key': process.env.${provider.ENV}_APIKEY } },
 })
 \`\`\``)
+  }
 
 
   sec('Check which plugin and SDK are running', `One message, and the thing to reach for when a deployment is behaving
@@ -3481,7 +3131,7 @@ released separately and most surprises live in the gap between them.`)
     const dpe = eList || subject
     const dpath = dpe.path || provider.probePath || '/'
     const dparams = pathParams(dpath)
-    const dval = (k: string) => (k === idf(dpe) || 'id' === k) ?
+    const dval = (k: string) => (k === apiKey(dpe) || 'id' === k) ?
       `${dpe.name}0` : `${k.replace(/_id$/, '')}0`
 
     sec('Reach the SDK directly', `The entity API covers the operations the API model declares. For
@@ -3711,25 +3361,6 @@ ${s.body}
 })
 
 
-// --- doc/reference.md ---------------------------------------------------------
-//
-// The Diátaxis reference: information-oriented, complete, and never teaching.
-// Everything a caller can reach — options, canons, fields, patterns, exports,
-// errors, environment variables, scripts — stated once, in tables, with the
-// exact strings the generated source actually emits.
-//
-// Three facts here are easy to get wrong by copying a hand-written original.
-// The guard message carries the PUBLISHED package name, because that is what
-// Main interpolates (`${provider.pkgName}: <entity> <cmd>: <key> is required`).
-// The `sdk` block of the get:info response carries the SDK's PACKAGE name, not
-// its slug. And an entity whose id field is not literally `id` cannot be read
-// with the `load$('x')` short form at all — Seneca turns that into `{id: 'x'}`,
-// which the generated action does not look at — so the object form is
-// documented for those entities instead of the string form.
-//
-// Nothing here assumes CRUD: every table row is conditional on the cmds and
-// ops the model actually declares, so an API offering only create, or only
-// reads, documents only what it has.
 
 const DocReference = cmp(function DocReference(props: any) {
   const { provider } = props
@@ -3740,8 +3371,6 @@ const DocReference = cmp(function DocReference(props: any) {
   // has nothing to select here.
   const acting = provider.entities.filter((e: any) => 0 < e.actionList.length)
 
-  // The entity used for worked examples: the same choice the tests and README
-  // make, so all three documents show the same entity.
   const subject = [...provider.entities]
     .sort((a: any, b: any) =>
       (a.parents.length - b.parents.length) || (b.cmds.length - a.cmds.length))[0]
@@ -3760,8 +3389,6 @@ const DocReference = cmp(function DocReference(props: any) {
 
   const live = '' !== provider.liveBase
 
-  // test/quick.js is emitted only when the subject entity can be created and
-  // removed again — see the Scripts cmp — so only document it when it exists.
   const quick = live && subject.cmds.includes('save') && subject.cmds.includes('remove')
 
   const canon = (e: any) => `provider/${provider.lower}/${e.name}`
@@ -3777,12 +3404,14 @@ const DocReference = cmp(function DocReference(props: any) {
   // A query literal for the docs: parent keys first, then whatever else the
   // command needs.
   const query = (e: any, extra: string[]) =>
-    `{ ${[...e.parents, ...extra].map((k: string) => `${k}: '...'`).join(', ')} }`
+    `{ ${[...e.parents, ...extra].map((k: string) => `${jsKey(k)}: '...'`).join(', ')} }`
 
   // How a single record is addressed. The `load$('x')` short form only works
   // when the id field is literally `id`.
-  const oneArg = (e: any) => 0 < e.parents.length ? query(e, [e.idf]) :
-    'id' === e.idf ? `'...'` : query(e, [e.idf])
+  const oneArg = (e: any) => 0 < e.parents.length ? query(e, ['id']) : `'...'`
+
+  const apiKeyOf = (e: any) => 0 < idPartsOf(e).length ?
+    idPartsOf(e).join(String(e.idsep || '/')) : (e.rk || 'id')
 
   // The required-key phrasing, which has to read correctly for one key as
   // well as several.
@@ -3949,11 +3578,11 @@ A canon carries only the commands its API operations support — an entity the
 API offers no delete for has no \`remove$\` — so the tables below are the
 whole of what each one answers.
 
-| Seneca canon | SDK accessor | Route | Id field | Parent keys | Commands |
-| ------------ | ------------ | ----- | -------- | ----------- | -------- |
+| Seneca canon | SDK accessor | Route | API key | Parent keys | Commands |
+| ------------ | ------------ | ----- | ------- | ----------- | -------- |
 `)
     each(provider.entities, (e: any) => {
-      Content(`| \`${canon(e)}\` | \`sdk.${e.acc}()\` | \`${e.path}\` | \`${e.idf}\` | ${0 < e.parents.length ?
+      Content(`| \`${canon(e)}\` | \`sdk.${e.acc}()\` | \`${e.path}\` | \`${apiKeyOf(e)}\` | ${0 < e.parents.length ?
         keys(e.parents) : '—'} | ${cmdList(e)} |
 `)
     })
@@ -3989,7 +3618,7 @@ before any request is made, rather than issuing one that would 404.
 `)
       }
       if (e.cmds.includes('load')) {
-        Content(`| \`load$(q)\` | ${reqd([...e.parents, e.idf])} | One \`${e.name}\`, or \`null\` if not found. |
+        Content(`| \`load$(q)\` | ${reqd([...e.parents, 'id'])} | One \`${e.name}\`, or \`null\` if not found. |
 `)
       }
       if (e.cmds.includes('save')) {
@@ -4001,24 +3630,19 @@ before any request is made, rather than issuing one that would 404.
 `)
       }
       if (e.cmds.includes('remove')) {
-        Content(`| \`remove$(q)\` | ${reqd([...e.parents, e.idf])} | \`null\`. |
+        Content(`| \`remove$(q)\` | ${reqd([...e.parents, 'id'])} | \`null\`. |
 `)
       }
 
-      // The `load$('x')` short form sets `id`, which an entity keyed by
-      // anything else never reads. Nested entities need the object form for
-      // their parent keys anyway, so this only needs saying for top-level ones.
-      const shortForm = 0 === e.parents.length && 'id' !== e.idf ?
-        e.cmds.filter((c: string) => 'load' === c || 'remove' === c) : []
-
-      if (0 < shortForm.length) {
+      if ('id' !== apiKeyOf(e)) {
         Content(`
-This entity is keyed by \`${e.idf}\` rather than \`id\`, so the short
-${1 === shortForm.length ? 'form' : 'forms'} ${shortForm
-            .map((c: string) => `\`${c}$('...')\``).join(' and ')} ${1 === shortForm.length ?
-              'does' : 'do'} not address it: Seneca reads a bare string as
-\`{id: '...'}\`, which is not a key this entity uses. Pass
-\`{ ${e.idf}: '...' }\` instead.
+The API addresses \`${e.name}\` records by \`${apiKeyOf(e)}\`; the provider
+carries that value as the entity's \`id\`, so every query and entity above
+uses \`id\`. A record the API returns with an unrelated \`id\` of its own
+${false === e.parkfree ?
+          `keeps it where it is: \`${provider.lower}_id\`, where this provider
+would otherwise park it, is a name \`${e.name}\` itself uses.` :
+          `keeps that under \`${provider.lower}_id\`.`}
 `)
       }
 
@@ -4037,7 +3661,8 @@ also defines are passed through unchanged in both directions.
 | ----- | ---- | ----- |
 `)
         each(e.fields, (f: any) => {
-          Content(`| \`${f.name}\` | ${f.kind} | ${f.name === e.idf ? 'Id field.' :
+          Content(`| \`${f.name}\` | ${f.kind} | ${f.name === (e.rk || 'id') ?
+            ('id' === f.name ? 'Id field.' : 'API key; carried as the entity\'s `id`.') :
             e.parents.includes(f.name) ? ('' === f.parentEntity ?
               'Parent key. Required by every command.' :
               `Parent key: the id of a \`${f.parentEntity}\`. Required by every command.`) : ''} |
@@ -4070,15 +3695,14 @@ also defines are passed through unchanged in both directions.
       // The dispatching entity to show it with: the subject when it qualifies,
       // otherwise the first that does.
       const s = dispatch.includes(subject) ? subject : dispatch[0]
-      const writable = s.fields
-        .filter((f: any) => f.name !== s.idf && f.name !== 'id')
-        .filter((f: any) => !s.parents.includes(f.name))
+      const writable = s.fields.filter((f: any) => ownField(s, f))
+      const alterable = writable.filter((f: any) => changeField(s, f))
       const value = (f: any, alt: boolean) => 'number' === f.kind ?
         (alt ? '4321' : '1234') : 'boolean' === f.kind ?
           (alt ? 'true' : 'false') : `'${f.name}${alt ? '-changed' : '-value'}'`
       const make = [
-        ...s.parents.map((k: string) => `${k}: '...'`),
-        ...writable.map((f: any) => `${f.name}: ${value(f, false)}`),
+        ...s.parents.map((k: string) => `${jsKey(k)}: '...'`),
+        ...writable.map((f: any) => `${jsKey(f.name)}: ${value(f, false)}`),
       ].join(', ')
 
       Content(`
@@ -4089,14 +3713,14 @@ created, an entity **with** one is updated. The provider dispatches on the
 id field, so the same call does both.
 
 \`\`\`js
-// Create — no ${s.idf}.
+// Create — no id.
 const ${s.name} = await seneca
   .entity('${canon(s)}')
   .make$({ ${make} })
   .save$()
 
-// Update — ${s.idf} present.
-${0 < writable.length ? `${s.name}.${writable[0].name} = ${value(writable[0], true)}
+// Update — id present.
+${0 < alterable.length ? `${s.name}.${alterable[0].name} = ${value(alterable[0], true)}
 ` : ''}await ${s.name}.save$()
 \`\`\`
 
@@ -4348,19 +3972,26 @@ it is absent, \`null\` or the empty string.
 
     Content(`
 ## Authentication keys
-
+${!provider.authActive ? `
+The ${provider.api} definition declares no authentication. The plugin reads
+no key and adds no credential to any request: \`sys:provider,get:keymap\` is
+never posted. An \`apikey\` configured under this provider's name is
+accepted, for uniformity with other providers, and ignored.
+` : `
 The plugin follows the provider convention: if an \`apikey\` key is
-configured and non-empty, it is sent as \`authorization: Bearer <apikey>\`
-on every request. If the provider is not registered, or the key is absent or
-empty, no header is added and startup proceeds normally — an API that needs
-no credential exercises the same path.
+configured and non-empty, it is sent as ${credentialWire(provider)} on every
+request.${provider.authBasic ? ` HTTP Basic needs a second key, \`secret\`; with
+either missing, no credential is sent.` : ''} If the provider is not
+registered, or the key is absent or empty, no credential is added and
+startup proceeds with a warning in the log.
 
 \`\`\`js
   .use('provider', {
     provider: {
       ${provider.lower}: {
         keys: {
-          apikey: { value: '$${provider.ENV}_APIKEY' },
+          apikey: { value: '$${provider.ENV}_APIKEY' },${provider.authBasic ? `
+          secret: { value: '$${provider.ENV}_SECRET' },` : ''}
         },
       },
     },
@@ -4368,9 +3999,10 @@ no credential exercises the same path.
 \`\`\`
 
 The key is read once, during \`seneca.prepare()\`, by posting
-\`sys:provider,get:keymap,provider:${provider.lower}\`. An \`authorization\`
-header supplied through the \`sdk.headers\` option takes precedence over it.
-
+\`sys:provider,get:keymap,provider:${provider.lower}\`. A header supplied
+through the \`sdk.headers\` option takes precedence over the one the key
+would set.
+`}
 ## Environment variables
 
 The plugin never reads the environment itself. These are the variables the
@@ -4450,28 +4082,10 @@ ${quick ? 'Both scripts target' : 'It targets'} \`$${provider.ENV}_TEST_BASE\`,
 })
 
 
-// --- doc/explanation.md ------------------------------------------------------
-//
-// The understanding-oriented corner of the Diátaxis set: the document someone
-// opens when the plugin surprised them. It DISCUSSES and never instructs, so
-// nothing here is a step and nothing here is a table — those belong in
-// tutorial.md, how-to.md and reference.md.
-//
-// The hard part of generating this one is that its subject is design reasoning,
-// most of which is true of EVERY provider this target emits (the entityBuilder
-// convention, the four-cmds-to-five-ops join, the .data() hop, the 404
-// translation) and only some of which depends on the model (whether any entity
-// is nested, whether writes exist at all, whether the API declares a server).
-// So the invariant prose is written once and the model-dependent sections are
-// guarded — an API with no nesting gets no nesting section rather than a
-// section explaining that it has none.
 
 const DocExplanation = cmp(function DocExplanation(props: any) {
   const { provider } = props
 
-  // The entity used as the worked example throughout: fewest parent keys
-  // (nothing to arrange around it) and the most cmds. Same choice the Tests
-  // and Readme cmps make, so the documents agree on what they talk about.
   const subject = [...provider.entities]
     .sort((a: any, b: any) =>
       (a.parents.length - b.parents.length) || (b.cmds.length - a.cmds.length))[0]
@@ -4777,12 +4391,19 @@ by hand. Nothing about the mapping is waiting to be written.
 `)
     }
 
-    Content(`## Credentials, whether or not the API needs them
+    Content(provider.authActive ? `## Credentials, whether or not the API needs them
 
 At startup the plugin asks \`@seneca/provider\` for the keymap of
-\`${provider.lower}\` and sends the \`apikey\` as a bearer token when one is
-configured.
+\`${provider.lower}\` and sends the \`apikey\` as ${credentialWire(provider)}
+when one is configured.
+` : `## Credentials, for an API that declares none
 
+The ${provider.api} definition declares no authentication, so the plugin
+plumbs no credential: it does not ask \`@seneca/provider\` for a keymap at
+startup, and adds nothing to a request. The SDK's own auth stage is empty
+for such a definition, so a key handed to it could not reach the wire.
+`)
+    Content(`
 The key is *optional*. Absent, unconfigured and empty all mean "send no
 header", and none of them is an error. For an API that needs no credential this
 looks like ceremony, and it is worth keeping anyway: the shape of a Seneca
@@ -4919,23 +4540,6 @@ order-dependent and then flaky.
 })
 
 
-// --- doc/ --------------------------------------------------------------------
-//
-// The Diátaxis documentation set: an index plus the four quadrants.
-//
-// WHY THIS IS GENERATED AT ALL. Every other sdkgen target emits a single
-// README, and for a language SDK that is the right amount: the SDK's real
-// reference is its types. A Seneca provider has no types a reader can browse —
-// its whole interface is message patterns and entity canons, which exist only
-// in prose. The provider this target was modelled on carried 1100 lines of
-// hand-written documentation for exactly that reason, and the first
-// regeneration left all of it orphaned: the README's link table was gone and
-// nothing emitted the files it had pointed at.
-//
-// Everything here is derived from the same `provider` shape the source and the
-// tests are built from, so the docs cannot describe an entity the plugin does
-// not expose, or a cmd it does not implement — the drift that makes
-// hand-written provider docs untrustworthy after the second API change.
 
 const DocIndex = cmp(function DocIndex(props: any) {
   const { provider } = props
@@ -4987,9 +4591,6 @@ components, where fixing it once fixes every provider.
 })
 
 
-// The whole `doc/` folder. One cmp so Main names the documentation once, and
-// so the folder is opened in a single place — the four quadrant components
-// emit a File each and know nothing about where they sit.
 const Docs = cmp(function Docs(props: any) {
   const { provider } = props