@voxgig/sdkgen 3.0.0 → 3.1.0

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

@@ -0,0 +1,3915 @@
+import {
+  cmp, each,
+  File, Content, Folder,
+  jsKey, jsProp,
+} 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.
+
+
+// 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) {
+    return String(byKey)
+  }
+
+  const f = (e.fields || []).find((f: any) => f.name === key)
+  return (f && f.parentEntity) || ''
+}
+
+
+// The seeded id of the record a parent path param points at.
+function parentSeed(e: any, key: string): string {
+  const pe = parentName(e, key)
+
+  // A key naming no entity in the model still has to seed SOMETHING the
+  // guard accepts; strip the `_id` suffix and use that.
+  return '' !== pe ? `${pe}0` : `${key.replace(/_id$/, '')}0`
+}
+
+
+// `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.
+function parentPairs(e: any, live: boolean): string {
+  return e.parents
+    .map((p: string) => live ? `${p}, ` : `${p}: '${parentSeed(e, p)}', `)
+    .join('')
+}
+
+
+// The entity a parent path param addresses, or null when the model has none of
+// that name.
+function parentEntityFor(provider: any, e: any, key: string): any {
+  const name = parentName(e, key)
+
+  return '' === name ? null :
+    provider.entities.find((pe: any) => pe.name === name) || null
+}
+
+
+// Can a LIVE round-trip get hold of this entity's parent ids at all? Every
+// parent key must name an entity in the model, and that entity must be
+// listable — otherwise there is no honest way to obtain an id the server will
+// accept, and the test is not emitted rather than emitted and skipped.
+function liveParentsResolvable(provider: any, e: any): boolean {
+  return e.parents.every((p: string) => {
+    const pe = parentEntityFor(provider, e, p)
+    return null != pe && pe.cmds.includes('list')
+  })
+}
+
+
+// The lines that fetch a live parent id per parent key, plus the guard that
+// skips when the server has no parent record to attach to. Empty for a
+// top-level entity.
+function liveParentSetup(provider: any, e: any, ind: string): string {
+  if (0 === e.parents.length) {
+    return ''
+  }
+
+  return e.parents.map((p: string) => {
+    const pe = parentEntityFor(provider, e, p)
+    const pv = `${pe.name}Records`
+
+    return `${ind}  // ${e.name} records hang off ${pe.name} records, so the ${p} has to
+${ind}  // come FROM THE SERVER. This database is not ours to seed.
+${ind}  const ${pv} = await seneca
+${ind}    .entity('provider/${provider.lower}/${pe.name}')
+${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'}
+
+`
+  }).join('')
+}
+
+
+// A field a round-trip test can CHANGE and then assert on: the first string
+// field that is neither the id nor a parent path param. Without one there is
+// nothing an update could alter that an assertion could see, so the update leg
+// 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)
+
+  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)
+  // Seneca's key, not the API's: this test drives seneca.entity(...), whose
+  // query and entity always spell the id `id`. The provider translates to
+  // whatever the API calls it.
+  const idf = 'id'
+  const mut = 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 ?
+    seedLiteral(e, 'crud') : ''
+
+  return `${ind}it('${e.name}-crud', async (${live ? 't' : ''}) => {
+${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.
+${ind}  const made = await ent.make$({ ${pairs}${made} }).save$()
+
+${ind}  assert.ok(null != made.${idf})
+${ind}  assert.equal(
+${ind}    made.canon\$({ string: true }),
+${ind}    'provider/${provider.lower}/${e.name}',
+${ind}  )
+
+${ind}  const id = made.${idf}
+
+${ind}  try {
+${ind}    const loaded = await ent.load\$({ ${pairs}${idf}: id })
+${ind}    assert.equal(loaded.${idf}, id)
+${
+  '' === mut ? '' :
+  `
+${ind}    // An entity CARRYING an id is an update, not a second create.
+${ind}    loaded.${mut} = 'crud-${mut}-2'
+${ind}    const updated = await loaded.save\$()
+
+${ind}    assert.equal(updated.${idf}, id)
+${ind}    assert.equal(updated.${mut}, 'crud-${mut}-2')
+
+${ind}    const reloaded = await ent.load\$({ ${pairs}${idf}: id })
+${ind}    assert.equal(reloaded.${mut}, 'crud-${mut}-2')
+`}${ind}  }
+${ind}  finally {
+${ind}    // Always clean up. The mock and the server both hold data for the
+${ind}    // process lifetime, so a leaked record changes what later tests see.
+${ind}    await ent.remove\$({ ${pairs}${idf}: id })
+${ind}  }
+
+${ind}  // remove is real: the record is gone, and reading it is an ordinary
+${ind}  // not-found rather than an error.
+${ind}  assert.equal(await ent.load\$({ ${pairs}${idf}: id }), null)
+${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'
+    case 'boolean': return 'true'
+    case 'array': return '[]'
+    case 'object': return '{}'
+    default: return `'${tag}-${f.name}'`
+  }
+}
+
+
+// `name: 'value'` pairs for an entity's own (non-id, non-parent) required
+// fields, tagged with `tag` so a test record is recognisable in a store it
+// 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))
+    .map((f: any) => `${jsKey(f.name)}: ${fieldLiteral(f, tag)}`)
+    .join(', ')
+}
+
+
+// A plausible seed record for an entity: its required fields, given values
+// that read as data rather than as `string`.
+function seedRecord(e: any, idx: number): Record<string, any> {
+  const out: Record<string, any> = {}
+
+  for (const f of e.fields) {
+    if ('id' === f.name || f.name === e.idf) {
+      out[f.name] = `${e.name}${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.
+      out[f.name] = `${f.parentEntity}0`
+    }
+    else if ('number' === f.kind) {
+      out[f.name] = 100 * (idx + 1)
+    }
+    else if ('boolean' === f.kind) {
+      out[f.name] = false
+    }
+    else if ('array' === f.kind) {
+      out[f.name] = []
+    }
+    else if ('object' === f.kind) {
+      out[f.name] = {}
+    }
+    else {
+      out[f.name] = `${f.name}${idx}`
+    }
+  }
+
+  return out
+}
+
+
+const Tests = cmp(function Tests(props: any) {
+  const { provider } = props
+
+  // The entity the suite exercises hardest: prefer one with no parent keys
+  // (nothing to arrange) and the most cmds.
+  const subject = [...provider.entities]
+    .sort((a: any, b: any) =>
+      (a.parents.length - b.parents.length) || (b.cmds.length - a.cmds.length))[0]
+
+  const nested = provider.entities.filter((e: any) => 0 < e.parents.length)
+
+  Folder({ name: 'test' }, () => {
+
+    // The seed the offline mock transport is loaded with. Generated from the
+    // model so it matches the shape the SDK will actually return.
+    File({ name: 'seed.js' }, () => {
+      Content(`/* Generated by @voxgig/sdkgen. Do not edit. */
+'use strict'
+
+// Seed data for the SDK's offline mock transport, so the entity tests
+// exercise real code paths without a server.
+const SEED = {
+  entity: {
+`)
+      each(provider.entities, (e: any) => {
+        Content(`    ${e.name}: {
+`)
+        each([0, 1], (i: any) => {
+          const idx = Number(i.val$ ?? i)
+          const rec = seedRecord(e, idx)
+          Content(`      ${e.name}${idx}: ${JSON.stringify(rec)},
+`)
+        })
+        Content(`    },
+`)
+      })
+      Content(`  },
+}
+
+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. */
+
+const Pkg = require('../package.json')
+
+const messages = {
+  print: false,
+  pattern: 'sys:provider,provider:${provider.lower}',
+  allow: { missing: true },
+
+  calls: [
+    {
+      pattern: 'get:info',
+      out: {
+        ok: true,
+        name: '${provider.lower}',
+        version: Pkg.version,
+      },
+    },
+  ],
+}
+
+export default messages
+
+if ('undefined' !== typeof module) {
+  module.exports = messages
+}
+`)
+    })
+
+
+    File({ name: `${provider.fileBase}.test.js` }, () => {
+      Content(`/* Generated by @voxgig/sdkgen. Do not edit. */
+'use strict'
+
+const { describe, it, before } = require('node:test')
+const assert = require('node:assert')
+
+const Seneca = require('seneca')
+
+const ${provider.pluginName} = require('../dist/${provider.fileBase}')
+const ${provider.pluginName}Doc = require('../dist/${provider.pluginName}-doc')
+
+const SenecaMsgTest = require('seneca-msg-test')
+const { Maintain } = require('@seneca/maintain')
+
+const { SEED } = require('./seed')
+
+const BasicMessages = require('../dist-test/basic.messages')
+${'' === provider.liveBase ? '' : `
+// The live tests run against the companion test server in the SDK repo
+// (\`app/\`), which serves this by default. Start it with:
+//   cd ${provider.sdkrel}/app && npm start
+const LIVE_BASE = process.env.${provider.ENV}_TEST_BASE || '${provider.liveBase}'
+`}
+
+describe('${provider.fileBase}', () => {
+
+  it('happy', async () => {
+    assert.notEqual(${provider.pluginName}, undefined)
+    assert.notEqual(${provider.pluginName}Doc, undefined)
+
+    const seneca = await makeSeneca()
+
+    assert.partialDeepStrictEqual(
+      await seneca.post('sys:provider,provider:${provider.lower},get:info'),
+      {
+        ok: true,
+        name: '${provider.lower}',
+      },
+    )
+  })
+
+
+  it('messages', async () => {
+    const seneca = await makeSeneca()
+    await SenecaMsgTest(seneca, BasicMessages)()
+  })
+
+
+  it('sdk-export', async () => {
+    const seneca = await makeSeneca()
+    const sdk = seneca.export('${provider.pluginName}/sdk')()
+
+`)
+      each(provider.entities, (e: any) => {
+        Content(`    assert.equal(typeof sdk.${e.acc}, 'function')
+`)
+      })
+      Content(`  })
+
+`)
+
+      if (subject.cmds.includes('list')) {
+        Content(`
+  it('${subject.name}-list', async () => {
+    const seneca = await makeSeneca()
+    const list = await seneca.entity('provider/${provider.lower}/${subject.name}').list$()
+
+    assert.equal(list.length, 2)
+
+    // Entities must come back as Seneca entities under this plugin's canon.
+    // The SDK tags its own results with its entity marker, which must not
+    // survive into the Seneca entity.
+    assert.equal(
+      list[0].canon$({ string: true }),
+      'provider/${provider.lower}/${subject.name}',
+    )
+  })
+
+`)
+      }
+
+      if (subject.cmds.includes('load')) {
+        Content(`
+  it('${subject.name}-load', async () => {
+    const seneca = await makeSeneca()
+    const found = await seneca
+      .entity('provider/${provider.lower}/${subject.name}')
+      .load$('${subject.name}0')
+
+    assert.equal(found.${subject.idf || 'id'}, '${subject.name}0')
+    assert.equal(
+      found.canon$({ string: true }),
+      'provider/${provider.lower}/${subject.name}',
+    )
+  })
+
+
+  // A 404 from a single-item read is an ordinary "not found" answer, not a
+  // failure: the provider turns it into null rather than letting the SDK
+  // throw.
+  it('${subject.name}-load-missing', async () => {
+    const seneca = await makeSeneca()
+    const missing = await seneca
+      .entity('provider/${provider.lower}/${subject.name}')
+      .load$('nosuch${subject.name}')
+
+    assert.equal(missing, null)
+  })
+
+`)
+      }
+
+      // 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) => {
+        // 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(', ')
+
+        Content(`
+  it('${e.name}-needs-${key}', async () => {
+    const seneca = await makeSeneca()
+
+    await assert.rejects(
+      () => seneca.entity('provider/${provider.lower}/${e.name}').list$({}),
+      /${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()
+    const list = await seneca
+      .entity('provider/${provider.lower}/${e.name}')
+      .list$({ ${pairs} })
+
+    assert.equal(list.length, 2)
+    assert.equal(
+      list[0].canon$({ string: true }),
+      'provider/${provider.lower}/${e.name}',
+    )
+    assert.equal(list[0].${key}, '${parentSeed(e, key)}')
+  })
+
+`)
+        }
+
+        // Reading ONE nested record is the path that has to thread both the
+        // parent id and the entity id through to the SDK, so cover it
+        // separately from list.
+        if (e.cmds.includes('load')) {
+          Content(`
+  it('${e.name}-load', async () => {
+    const seneca = await makeSeneca()
+    const found = await seneca
+      .entity('provider/${provider.lower}/${e.name}')
+      .load$({ ${pairs}, id: '${e.name}0' })
+
+    assert.equal(found.id, '${e.name}0')
+    assert.equal(
+      found.canon$({ string: true }),
+      'provider/${provider.lower}/${e.name}',
+    )
+  })
+
+
+  it('${e.name}-load-missing', async () => {
+    const seneca = await makeSeneca()
+    const missing = await seneca
+      .entity('provider/${provider.lower}/${e.name}')
+      .load$({ ${pairs}, id: 'nosuch${e.name}' })
+
+    assert.equal(missing, null)
+  })
+
+`)
+        }
+      })
+
+      // The WRITE path, offline. Reads were covered and writes were not, so
+      // every generated `cmd.save` and `cmd.remove` action shipped without its
+      // own suite ever running it — including the parent-key guard on a nested
+      // save, which is the one this target exists to get right. The mock
+      // transport implements create/update/remove, so this needs no server.
+      each(provider.entities, (e: any) => {
+        if (e.cmds.includes('save') && e.cmds.includes('remove')) {
+          Content(`
+` + crudTest(provider, e, 'offline'))
+        }
+      })
+
+      // Live tests, against the companion server in the SDK repo's `app/`.
+      // They PROBE first and skip when nothing is listening, so the suite is
+      // green on a machine that has never started it — a live suite that
+      // fails when the server is absent is one nobody runs.
+      if ('' !== provider.liveBase) {
+        Content(`
+  describe('live', () => {
+    let live = false
+
+    before(async () => {
+      live = await serverUp(LIVE_BASE)
+    })
+
+`)
+        if (subject.cmds.includes('list')) {
+          Content(`    it('${subject.name}-list', async (t) => {
+      if (!live) return t.skip(noServer())
+      const seneca = await makeSeneca(liveOpts())
+
+      const list = await seneca.entity('provider/${provider.lower}/${subject.name}').list$()
+
+      assert.ok(Array.isArray(list))
+      if (0 < list.length) {
+        assert.equal(
+          list[0].canon$({ string: true }),
+          'provider/${provider.lower}/${subject.name}',
+        )
+      }
+    })
+
+`)
+        }
+        if (subject.cmds.includes('load')) {
+          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(
+        await seneca
+          .entity('provider/${provider.lower}/${subject.name}')
+          .load$('nosuch${subject.name}'),
+        null,
+      )
+    })
+
+`)
+        }
+
+        // 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') &&
+            liveParentsResolvable(provider, e)) {
+            Content(crudTest(provider, e, 'live'))
+          }
+        })
+
+        Content(`  })
+
+`)
+      }
+
+      // 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 environment that breaks it.
+      Content(`
+  it('maintain', async () => {
+    const exclude = []
+
+    // check_default proves the default branch is main by looking for
+    // [branch "main"] in .git/config. A pull_request build checks out the
+    // merge ref, which records no such section.
+    if ('pull_request' === process.env.GITHUB_EVENT_NAME) {
+      exclude.push('check_default')
+    }
+
+    // url_pkgjson locates package.json by comparing process.cwd() + '/package.json'
+    // against a path found with Filehound. On Windows those are the same file
+    // spelt with different separators, so the url is never read.
+    if ('win32' === process.platform) {
+      exclude.push('url_pkgjson')
+    }
+
+    await Maintain({ exclude })
+  })
+
+`)
+
+      Content(`})
+
+`)
+
+      if ('' !== provider.liveBase) {
+        Content(`
+function noServer() {
+  return 'no ${provider.lower} server at ' + LIVE_BASE
+}
+
+
+function liveOpts() {
+  return { sdk: { base: LIVE_BASE } }
+}
+
+
+// Probe the companion test server so live tests skip cleanly when it is not
+// running, rather than failing the suite.
+async function serverUp(base) {
+  try {
+    const res = await fetch(base + '${provider.probePath}', {
+      signal: AbortSignal.timeout(2000),
+    })
+    return res.ok
+  }
+  catch (e) {
+    return false
+  }
+}
+
+`)
+      }
+
+      Content(`
+// Default to the SDK's offline mock transport, seeded from ./seed.
+async function makeSeneca(pluginopts) {
+  pluginopts = pluginopts || { test: true, testopts: SEED }
+
+  const seneca = Seneca({ legacy: false })
+    .test()
+    .use('promisify')
+    .use('entity')
+    .use('env', {
+      // Declared so the provider convention is exercised, and defaulted so
+      // the suite runs with nothing configured.
+      var: {
+        $${provider.ENV}_APIKEY: '',
+      },
+    })
+    .use('provider', {
+      provider: {
+        ${provider.lower}: {
+          keys: {
+            apikey: { value: '$${provider.ENV}_APIKEY' },
+          },
+        },
+      },
+    })
+    .use(${provider.pluginName}, pluginopts)
+
+  return seneca.ready()
+}
+`)
+    })
+  })
+})
+
+
+// --- 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
+
+  // Nothing to point at without a declared server.
+  if ('' === provider.liveBase) {
+    return
+  }
+
+  const subject = [...provider.entities]
+    .sort((a: any, b: any) =>
+      (a.parents.length - b.parents.length) || (b.cmds.length - a.cmds.length))[0]
+
+  const senecaSetup = `const Seneca = require('seneca')
+
+const BASE = process.env.${provider.ENV}_TEST_BASE || '${provider.liveBase}'
+
+async function makeSeneca() {
+  return Seneca({ legacy: false })
+    .test()
+    .use('promisify')
+    .use('entity')
+    .use('provider', {
+      provider: {
+        ${provider.lower}: {
+          keys: {
+            apikey: { value: '' },
+          },
+        },
+      },
+    })
+    .use('..', { sdk: { base: BASE } })
+    .ready()
+}
+`
+
+  Folder({ name: 'test' }, () => {
+
+    File({ name: 'live.js' }, () => {
+      Content(`/* Manual script: read from a running ${provider.api} server.
+ *
+ * Start the companion test server from the SDK repo first:
+ *   cd ${provider.sdkrel}/app && npm start
+ *
+ * Then:  node test/live.js
+ */
+
+${senecaSetup}
+
+run()
+
+async function run() {
+  const seneca = await makeSeneca()
+
+`)
+      // A nested entity's list needs its parent's id, so LOOK ONE UP rather
+      // than emitting a placeholder: a script that 404s on first run teaches
+      // nothing and reads as a broken provider.
+      each(provider.entities.filter((e: any) => e.cmds.includes('list')), (e: any) => {
+        if (0 === e.parents.length) {
+          Content(`  console.log('${e.name.toUpperCase()}', await seneca
+    .entity('provider/${provider.lower}/${e.name}')
+    .list$())
+
+`)
+          return
+        }
+
+        const parent = provider.entities
+          .find((p: any) => p.name === e.parentEntity && p.cmds.includes('list'))
+        if (null == parent) {
+          // Nothing to derive the parent id from. Say so in the script
+          // rather than emitting a call that cannot work.
+          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(', ')} })
+
+`)
+          return
+        }
+
+        const key = e.parents[0]
+        Content(`  const ${parent.name}s = await seneca
+    .entity('provider/${provider.lower}/${parent.name}')
+    .list$()
+
+  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'} }))
+  }
+
+`)
+      })
+      Content(`}
+`)
+    })
+
+
+    // 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 make = writable
+        .map((f: any) => `${jsKey(f.name)}: ${fieldLiteral(f, 'quick')}`)
+        .join(', ')
+
+      File({ name: 'quick.js' }, () => {
+        Content(`/* Manual script: exercise the full CRUD cycle against a running server.
+ *
+ * Start the companion test server from the SDK repo first:
+ *   cd ${provider.sdkrel}/app && npm start
+ *
+ * Then:  node test/quick.js
+ *
+ * Creates and then removes a ${subject.name}, so the server is left as found.
+ */
+
+${senecaSetup}
+
+run()
+
+async function run() {
+  const seneca = await makeSeneca()
+
+  // Create: the API assigns the id, so none is supplied here.
+  let ${subject.name} = await seneca
+    .entity('provider/${provider.lower}/${subject.name}')
+    .make$({ ${make} })
+    .save$()
+  console.log('CREATED', ${subject.name})
+
+  const id = ${subject.name}.${idf}
+
+  try {
+`)
+        // 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
+
+        if (subject.ops.includes('update') && null != upd) {
+          const f = upd
+          const v = 'number' === f.kind ? '4321' : `'quick-${f.name}-2'`
+          Content(`    // Update: an entity carrying an id is an update.
+    ${jsProp(subject.name, f.name)} = ${v}
+    console.log('UPDATED', await ${subject.name}.save$())
+
+`)
+        }
+        if (subject.cmds.includes('load')) {
+          Content(`    console.log(
+      'LOADED',
+      await seneca.entity('provider/${provider.lower}/${subject.name}').load$(id)
+    )
+
+`)
+        }
+
+        // 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 &&
+          e.cmds.includes('save') && e.cmds.includes('remove'))
+
+        if (null != child) {
+          const ckey = child.parents[0]
+          const cidf = child.idf || 'id'
+          const cmake = (child.fields || [])
+            .filter((f: any) =>
+              f.name !== cidf && 'id' !== f.name && !child.parents.includes(f.name))
+            .map((f: any) => `${jsKey(f.name)}: ${fieldLiteral(f, 'quick')}`)
+            .join(', ')
+
+          Content(`    // ${child.name} records hang off ${subject.name} records, so this one
+    // 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} })
+      .save$()
+    console.log('${child.name.toUpperCase()} CREATED', ${child.name})
+
+    await seneca
+      .entity('provider/${provider.lower}/${child.name}')
+      .remove$({ ${ckey}: id, ${cidf}: ${child.name}.${cidf} })
+    console.log('${child.name.toUpperCase()} REMOVED')
+
+`)
+        }
+
+        Content(`  }
+  finally {
+    await seneca.entity('provider/${provider.lower}/${subject.name}').remove$(id)
+    console.log('REMOVED', id)
+  }
+`)
+        if (subject.cmds.includes('load')) {
+          Content(`
+  console.log(
+    'AFTER REMOVE (expect null)',
+    await seneca.entity('provider/${provider.lower}/${subject.name}').load$(id)
+  )
+`)
+        }
+        Content(`}
+`)
+      })
+    }
+  })
+})
+
+
+// --- .github/workflows/build.yml --------------------------------------------
+
+const Workflow = cmp(function Workflow(props: any) {
+  const { provider } = props
+
+  Folder({ name: '.github' }, () => {
+    Folder({ name: 'workflows' }, () => {
+      File({ name: 'build.yml' }, () => {
+        Content(`# Generated by @voxgig/sdkgen. Do not edit.
+#
+# The ${provider.api} SDK is a normal published dependency, so \`npm install\`
+# is all that is needed to build and run the offline tests on every platform.
+${!provider.liveApp ? '' : `#
+# The live tests additionally need the companion server, which is only
+# distributed in the SDK's source repository (it is not published). That repo
+# is cloned and started on Linux only, because backgrounding the server
+# assumes a POSIX shell. The live tests probe for the server and skip cleanly
+# when it is absent, so on Windows and macOS they simply skip.`}
+
+name: build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    timeout-minutes: 10
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node-version: [24.x]
+
+    runs-on: \${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Use Node.js \${{ matrix.node-version }}
+        uses: actions/setup-node@v7
+        with:
+          node-version: \${{ matrix.node-version }}
+
+${!provider.liveApp ? '' : `
+      # Live-test target. Failure to start degrades coverage (the live tests
+      # probe first and skip) rather than failing the build — which is what
+      # continue-on-error is for, and what its absence undid: GitHub runs a
+      # run: block under bash -e, so a repo whose app/ has no build script,
+      # or no app/ at all, went red on its first push with the comment
+      # above still claiming otherwise.
+      - name: Start the ${provider.api} test server
+        if: runner.os == 'Linux'
+        continue-on-error: true
+        run: |
+          git clone --depth 1 \\
+            ${provider.sdkRepoUrl}.git \\
+            "$RUNNER_TEMP/sdk"
+          cd "$RUNNER_TEMP/sdk/app"
+          npm install
+          npm run build
+          npm start &
+          for i in $(seq 1 30); do
+            if curl -sf ${provider.liveBase}${provider.probePath} > /dev/null; then
+              echo "server up"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "server did not start; live tests will skip"
+`}
+      - run: npm install
+      - run: npm i seneca seneca-entity seneca-promisify @seneca/provider @seneca/env
+      - run: npm run build --if-present
+      - run: npm test
+`)
+      })
+    })
+  })
+})
+
+
+// --- 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
+
+  const subject = [...provider.entities]
+    .sort((a: any, b: any) =>
+      (a.parents.length - b.parents.length) || (b.cmds.length - a.cmds.length))[0]
+
+  const nested = provider.entities.filter((e: any) => 0 < e.parents.length)
+
+  File({ name: 'README.md' }, () => {
+    Content(`![Seneca ${provider.Name}-Provider](http://senecajs.org/files/assets/seneca-logo.png)
+
+> _Seneca ${provider.Name}-Provider_ is a plugin for [Seneca](http://senecajs.org)
+
+Provides access to the ${provider.api} API using the Seneca _provider_
+convention. ${provider.api} entities are represented as Seneca entities so that
+they can be accessed using the Seneca entity API and messages.
+
+Requests are handled by the [${provider.api} SDK](${provider.sdkRepoUrl}),
+which is generated from the API's OpenAPI specification. This plugin is
+generated from the same specification by
+[@voxgig/sdkgen](https://github.com/voxgig/sdkgen) — do not edit it by hand,
+change the model and regenerate.
+
+See [seneca-entity](https://github.com/senecajs/seneca-entity) and the [Seneca Data
+Entities
+Tutorial](https://senecajs.org/docs/tutorials/understanding-data-entities.html)
+for more details on the Seneca entity API.
+
+[![build](${provider.repoUrl}/actions/workflows/build.yml/badge.svg)](${provider.repoUrl}/actions/workflows/build.yml)
+
+| This open source module is sponsored and supported by [${provider.publisher}](${provider.publisherUrl}). |
+| --- |
+
+
+<!--START:SECTION:intro-->
+<!--END:SECTION:intro-->
+
+
+## Documentation
+
+Full documentation lives in [\`doc/\`](doc/README.md) and follows the
+[Diátaxis](https://diataxis.fr) framework:
+
+| Document | Purpose |
+| -------- | ------- |
+| [Tutorial](doc/tutorial.md) | Start here. Build a working script from an empty folder. |
+| [How-to guides](doc/how-to.md) | Recipes for specific tasks. |
+| [Reference](doc/reference.md) | Every pattern, entity, option and export. |
+| [Explanation](doc/explanation.md) | Why the plugin is designed this way. |
+
+
+## Quick Example
+
+\`\`\`js
+const Seneca = require('seneca')
+
+const seneca = Seneca()
+  .use('promisify')
+  .use('entity')
+  .use('env', { var: { $${provider.ENV}_APIKEY: '' } })
+  .use('provider', {
+    provider: {
+      ${provider.lower}: {
+        keys: { apikey: { value: '$${provider.ENV}_APIKEY' } },
+      },
+    },
+  })
+  .use('${provider.pkgName}')
+
+await seneca.ready()
+
+`)
+    if (subject.cmds.includes('list')) {
+      Content(`const ${subject.name}s = await seneca
+  .entity('provider/${provider.lower}/${subject.name}').list$()
+`)
+    }
+    if (subject.cmds.includes('load')) {
+      Content(`const ${subject.name} = await seneca
+  .entity('provider/${provider.lower}/${subject.name}').load$('some-id')
+`)
+    }
+    Content(`\`\`\`
+
+
+## Install
+
+\`\`\`sh
+npm install ${provider.pkgName}
+\`\`\`
+
+This plugin expects the Seneca host framework to be present:
+
+\`\`\`sh
+npm install seneca seneca-entity seneca-promisify @seneca/provider @seneca/env
+\`\`\`
+
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| \`sdk\` | object | Passed straight to the \`${provider.sdkClass}\` constructor. Most usefully \`base\`, to point at a server. |
+| \`test\` | boolean | Run the SDK in offline test mode (in-memory mock transport). |
+| \`testopts\` | object | Seed and options for the mock, used only when \`test\` is true. |
+
+
+## Entities
+
+Each API entity is exposed as a Seneca entity under
+\`provider/${provider.lower}/<entity>\`.
+
+| 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(', ')
+      Content(`| \`provider/${provider.lower}/${e.name}\` | ${e.cmds.map((c: string) => '`' + c + '$`').join(', ')} | ${fields} |
+`)
+    })
+
+    if (0 < nested.length) {
+      Content(`
+### Nested entities
+
+Some entities live under a parent in the API path, so every command needs the
+parent's id in the query. Leaving it out throws with a message naming the
+missing key, rather than failing as an opaque 404 from a half-built URL.
+
+`)
+      each(nested, (e: any) => {
+        Content(`- \`${e.name}\` requires \`${e.parents.join('`, `')}\`
+`)
+      })
+    }
+
+    Content(`
+
+## Action Patterns
+
+Every message pattern this plugin registers. The entity actions are the ones
+\`seneca-entity\` dispatches to when you call \`list$\` / \`load$\` / \`save$\` /
+\`remove$\` on a canon below — you rarely post them by hand, but they are what
+appears in a Seneca log, and a plugin that documents one of nine is a plugin
+whose logs cannot be read.
+
+| Pattern | Description |
+| --- | --- |
+| \`sys:provider,provider:${provider.lower},get:info\` | Plugin and SDK version information. |
+`)
+
+    const CMD_DESC: Record<string, string> = {
+      list: 'List records',
+      load: 'Load one record',
+      save: 'Create or update a record',
+      remove: 'Remove a record',
+    }
+
+    each(provider.entities, (e: any) => {
+      each(e.cmds, (cmd: any) => {
+        const c = String(cmd.val$ ?? cmd)
+        Content(`| \`sys:entity,cmd:${c},zone:provider,base:${provider.lower},name:${e.name}\` | ${CMD_DESC[c]}. |
+`)
+      })
+    })
+
+    Content(`
+
+
+## More Examples
+
+### Offline testing
+
+The SDK ships an in-memory mock transport, so this plugin can be exercised
+with no server:
+
+\`\`\`js
+.use('${provider.pkgName}', { test: true, testopts: { entity: { ... } } })
+\`\`\`
+
+\`testopts\` is passed straight to the SDK's test constructor; \`entity\`
+seeds the mock store. See \`test/seed.js\` for the shape.
+
+`)
+    if ('' !== provider.liveBase) {
+      Content(`### Running against a server
+
+\`\`\`js
+.use('${provider.pkgName}', { sdk: { base: '${provider.liveBase}' } })
+\`\`\`
+
+The companion test server is distributed in the SDK's source repository
+only. From a checkout beside this one:
+
+\`\`\`sh
+cd ${provider.sdkrel}/app && npm start
+\`\`\`
+
+Then \`node test/live.js\` reads from it, and \`node test/quick.js\` runs a
+full create/update/load/remove cycle.
+
+`)
+    }
+
+    Content(`
+## Motivation
+
+Applications rarely talk to one external service, and each service usually
+arrives with its own client library, authentication style and error
+conventions. That variety leaks into application code and makes it harder to
+test.
+
+The Seneca provider convention removes the variety: every external service
+becomes a Seneca entity reached with \`list$\`, \`load$\`, \`save$\` and
+\`remove$\`, so application code has one shape regardless of what it talks to.
+
+The SDK underneath arrives at a similar conclusion from the other side — it
+deliberately exposes entities rather than HTTP routes. This plugin is the
+short bridge between the two.
+
+
+## Support
+
+- Issues and bugs: [GitHub issues](${provider.repoUrl}/issues)
+- Seneca community: [senecajs.org](http://senecajs.org)
+
+
+## API
+
+### Plugin export: \`${provider.pluginName}/sdk\`
+
+Returns the configured \`${provider.sdkClass}\` instance, for the operations
+the entity API does not cover:
+
+\`\`\`js
+const sdk = seneca.export('${provider.pluginName}/sdk')()
+\`\`\`
+
+
+## Contributing
+
+This plugin is GENERATED. Changes belong in the SDK project's model and
+components, not here — anything edited in this repository is overwritten by
+the next generation run.
+
+The [Senecajs org](http://senecajs.org) encourages open participation. If you
+feel you can help in any way, be it with bug reporting, documentation,
+examples, extra testing, or new features, please get in touch.
+
+
+## Background
+
+Generated by [@voxgig/sdkgen](https://github.com/voxgig/sdkgen) from the
+${provider.api} API definition, against the
+[${provider.sdkPkg}](https://www.npmjs.com/package/${provider.sdkPkg}) SDK.
+`)
+  })
+})
+
+
+// --- 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
+
+  // Entity and field names come from an API definition, so they cannot be
+  // assumed to be legal JavaScript identifiers.
+  const ident = (s: string) => String(s).replace(/[^A-Za-z0-9_$]/g, '_')
+  const qkey = (k: string) =>
+    /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(k)) ? String(k) : `'${k}'`
+  const plural = (n: string) =>
+    n.endsWith('s') ? `${ident(n)}List` : `${ident(n)}s`
+  const canon = (n: string) => `provider/${provider.lower}/${n}`
+  const entOf = (name: string) =>
+    provider.entities.find((e: any) => e.name === name) || null
+
+  // The entity the lesson is built on: fewest parent keys to arrange, then
+  // most cmds to show. The same choice the tests and the README make, so all
+  // three talk about the same thing.
+  const subject = [...provider.entities]
+    .sort((a: any, b: any) =>
+      (a.parents.length - b.parents.length) || (b.cmds.length - a.cmds.length))[0]
+
+  const idf = subject.idf || 'id'
+  const subjParent = 0 < subject.parents.length ?
+    entOf(subject.parentEntity) : null
+
+  const hasServer = '' !== provider.liveBase
+
+  // Can the live lesson actually be written? It needs a server AND a first id
+  // the script can discover for itself.
+  const live = hasServer &&
+    subject.cmds.includes('list') &&
+    (0 === subject.parents.length ||
+      (1 === subject.parents.length &&
+        null != subjParent && subjParent.cmds.includes('list')))
+
+  const offline = !live
+
+  // The nested entity the lesson finishes on. Prefer one hanging off the
+  // subject, so the reader recognises the parent id when it turns up.
+  const readable = (e: any) => e.cmds.includes('list') || e.cmds.includes('load')
+  const nested = provider.entities
+    .filter((e: any) => 0 < e.parents.length && e.name !== subject.name)
+    .filter(readable)
+    // Live, the parent id has to come from somewhere: exactly one parent key,
+    // and a parent that can be listed.
+    .filter((e: any) => offline ||
+      (1 === e.parents.length && null != entOf(e.parentEntity) &&
+        entOf(e.parentEntity).cmds.includes('list')))
+  const child = nested.find((e: any) => e.parentEntity === subject.name) ||
+    nested.find((e: any) => null != entOf(e.parentEntity)) ||
+    nested[0] || null
+  const childParent = null == child ? null : entOf(child.parentEntity)
+
+  // 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`
+  }
+
+  // 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'
+    if (null == rec[eidf]) {
+      rec[eidf] = `${e.name}${idx}`
+    }
+    for (const k of e.parents) {
+      if (null == rec[k]) {
+        rec[k] = seedParentVal(e, k)
+      }
+    }
+    return rec
+  }
+
+  // Only the entities the lesson touches, in model order.
+  const seedNames = [subject.name]
+  if (null != subjParent) seedNames.push(subjParent.name)
+  if (null != child) seedNames.push(child.name)
+  if (null != childParent) seedNames.push(childParent.name)
+
+  const seedLiteral = provider.entities
+    .filter((e: any) => seedNames.includes(e.name))
+    .map((e: any) =>
+      `    ${qkey(e.name)}: {\n` +
+      [0, 1].map((idx: number) =>
+        `      ${qkey(e.name + idx)}: ${JSON.stringify(demoRecord(e, idx))},\n`)
+        .join('') +
+      `    },\n`)
+    .join('')
+
+  // Every call on the subject carries its parent keys, if it has any: live
+  // they come from a lookup, offline from the seed.
+  const subjKeys = subject.parents.map((k: string) =>
+    `${qkey(k)}: ${offline ? `'${seedParentVal(subject, k)}'` : ident(k)}`)
+  const listArg = 0 === subjKeys.length ? '' : `{ ${subjKeys.join(', ')} }`
+  const oneArg = (id: string) => 0 === subjKeys.length ? id :
+    `{ ${subjKeys.concat([`${qkey(idf)}: ${id}`]).join(', ')} }`
+
+  const subjVar = plural(subject.name)
+  const subjOne = ident(subject.name)
+
+  // Live, the first id is whatever the server answered with; offline it is
+  // seeded above.
+  const firstId = offline ? `'${subject.name}0'` : `${subjVar}[0].${idf}`
+
+  // A nested subject needs its parent's id before anything else can run.
+  const subjPre = (live && null != subjParent) ?
+    `  // ${subject.name} records live under ${subjParent.name} records in the API,
+  // so every ${subject.name} call needs a ${subject.parents[0]}.
+  const ${plural(subjParent.name)} = await seneca
+    .entity('${canon(subjParent.name)}')
+    .list$()
+  const ${ident(subject.parents[0])} = ${plural(subjParent.name)}[0].${subjParent.idf || '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 shown = plainFields.slice(0, 2)
+  const litval = (f: any, alt: boolean) =>
+    'number' === f.kind ? (alt ? '4321' : '1234') :
+      'boolean' === f.kind ? (alt ? 'true' : 'false') :
+        `'tutorial-${f.name}${alt ? '-2' : ''}'`
+
+  const makeFields = subject.parents
+    .map((k: string) =>
+      `${qkey(k)}: ${offline ? `'${seedParentVal(subject, k)}'` : ident(k)}`)
+    .concat(plainFields.map((f: any) => `${qkey(f.name)}: ${litval(f, false)}`))
+
+  const hasRead = subject.cmds.includes('list') || subject.cmds.includes('load')
+  // 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 canRemove = canWrite && subject.cmds.includes('remove')
+
+  const cmdList = subject.cmds.map((c: string) => '`' + c + '$`').join(', ')
+
+  // Entity names are lowercase, and some of them have to start a sentence.
+  const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1)
+
+  // A nested SUBJECT would otherwise carry an unexplained parent key through
+  // every example in the lesson. Said once, before the first call.
+  const nestedNote = 0 === subject.parents.length ? '' :
+    `${cap(subject.name)} records live inside ${'' === subject.parentEntity ?
+      'a parent record' : `${subject.parentEntity} records`} in the API,
+and the route says so:
+
+\`${subject.path}\`
+
+The parent id there is not optional, so every ${subject.name} call
+carries ${subject.parents.map((k: string) => '`' + k + '`').join(' and ')} in its query. Leave it out and the provider
+names the key you missed, rather than letting a half-built URL come
+back as a puzzling 404.
+
+`
+
+  // The clone lands in a directory named for the repository, so the cd that
+  // follows can be exact rather than "wherever you put it". With no repo url
+  // to clone from, the only path anyone can be told is the relative one back
+  // to the SDK project.
+  const sdkRepo = String(provider.sdkRepoUrl || '')
+  const sdkDir = sdkRepo.replace(/\/+$/, '').split('/').pop() || 'sdk'
+  const appDir = '' === sdkRepo ? `${provider.sdkrel}/app` : `${sdkDir}/app`
+
+  const getServer = '' === sdkRepo ?
+    `You also need a server to talk to. The SDK itself installs from npm,
+but its test server does not — it ships only in the SDK's source
+project, in its \`app\` folder, which is at \`${provider.sdkrel}\`
+relative to this one.
+` :
+    `You also need a server to talk to. The SDK itself installs from npm,
+but its test server does not — it ships only in the SDK's source
+repository, so clone that:
+
+\`\`\`sh
+$ git clone ${sdkRepo}.git
+\`\`\`
+
+If you already have that checkout beside this plugin, it is at
+\`${provider.sdkrel}\`, and you can skip the clone.
+`
+
+  // What a bare GET on the probe route answers with, when the model has one.
+  const probeEnt = '' === provider.probePath ? null :
+    provider.entities.find((e: any) => e.path === provider.probePath)
+
+  // Who assigns ids and holds the data, in prose.
+  const source = live ? 'server' : 'store'
+
+  // Where the nested-subject note lands: the first step that shows a call.
+  const noteAt = subject.cmds.includes('list') ? 'list' :
+    subject.cmds.includes('load') ? 'load' : 'write'
+
+  let stepno = 0
+  const step = (title: string) => `## Step ${++stepno}: ${title}`
+
+  File({ name: 'tutorial.md' }, () => {
+
+    Content(`# Tutorial: your first ${provider.Name} query
+
+This tutorial takes you from an empty folder to a script that
+${canWrite ? 'reads and writes' : 'reads'} ${provider.api} data through
+Seneca entities. It should take about fifteen minutes.
+
+You will build one script and add to it as you go.`)
+
+    if (live) {
+      Content(` Everything runs
+locally against a test server you start yourself, so nothing here can
+affect anything outside your machine.
+
+You need [Node.js](https://nodejs.org) 24 or later.
+
+${getServer}
+${step('Start the test server')}
+
+That server implements the ${provider.api} API. Build and start it:
+
+\`\`\`sh
+$ cd ${appDir}
+$ npm install
+$ npm run build
+$ npm start
+\`\`\`
+
+It listens on \`${provider.liveBase}\`. Check it from another terminal:
+
+\`\`\`sh
+$ curl ${provider.liveBase}${provider.probePath}
+\`\`\`
+
+`)
+      Content(null == probeEnt ?
+        `You should get a JSON answer rather than a refused connection.
+Leave the server running.
+
+` :
+        `You should see a JSON array of ${probeEnt.name} records.
+Leave the server running.
+
+`)
+    }
+    else {
+      Content(` Everything runs in
+memory: the SDK ships an offline mode backed by a small in-memory
+store, and you supply that store's contents yourself. No request leaves
+your machine, so nothing here can affect anything outside it.
+
+You need [Node.js](https://nodejs.org) 24 or later. You do not need a
+server, a network connection, or credentials.
+
+`)
+    }
+
+    Content(`${step('Create the project')}
+
+`)
+    if (live) {
+      Content(`In a new terminal:
+
+`)
+    }
+    Content(`\`\`\`sh
+$ mkdir ${provider.lower}-demo
+$ cd ${provider.lower}-demo
+$ npm init -y
+$ npm install seneca seneca-entity seneca-promisify @seneca/provider ${provider.pkgName}
+\`\`\`
+
+The first four are the Seneca host: the framework itself, the entity
+API, the promise wrapper that makes calls awaitable, and the shared
+machinery every Seneca provider is built on. The last is this plugin,
+which brings the ${provider.api} SDK with it.
+
+${step('Connect')}
+
+Create \`demo.js\`:
+
+\`\`\`js
+const Seneca = require('seneca')
+
+`)
+
+    if (offline) {
+      Content(`// The offline store. Each key under an entity name is that record's
+// id, and each record is what the API would have answered with.
+const SEED = {
+  entity: {
+${seedLiteral}  },
+}
+
+`)
+    }
+
+    Content(`async function main() {
+  const seneca = await Seneca({ legacy: false })
+    .use('promisify')
+    .use('entity')
+    .use('provider', {
+      provider: {
+        ${qkey(provider.lower)}: {
+          keys: {
+            apikey: { value: '' },
+          },
+        },
+      },
+    })
+`)
+    Content(live ?
+      `    .use('${provider.pkgName}', {
+      sdk: { base: '${provider.liveBase}' },
+    })
+` :
+      `    .use('${provider.pkgName}', {
+      test: true,
+      testopts: SEED,
+    })
+`)
+    Content(`    .ready()
+
+  const info = await seneca.post('sys:provider,provider:${provider.lower},get:info')
+  console.log(info)
+}
+
+main()
+\`\`\`
+
+Run it:
+
+\`\`\`sh
+$ node demo.js
+\`\`\`
+
+You should see:
+
+\`\`\`js
+{
+  ok: true,
+  name: '${provider.lower}',
+  version: '${provider.version}',
+  sdk: { name: '${provider.sdkPkg}', version: '${provider.sdkVersion}' },
+}
+\`\`\`
+
+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
+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
+API, so a reply tells you the plugin loaded and initialised before any
+request goes anywhere.
+
+`)
+
+    if (subject.cmds.includes('list')) {
+      Content(`${step(`List the ${subject.name} records`)}
+
+${'list' === noteAt ? nestedNote : ''}Replace the \`console.log(info)\` line with:
+
+\`\`\`js
+${subjPre}  const ${subjVar} = await seneca
+    .entity('${canon(subject.name)}')
+    .list$(${listArg})
+
+  console.log('Found ' + ${subjVar}.length + ' ${subject.name} record(s):')
+  ${subjVar}.forEach((r) => {
+    console.log('  ' + r.${idf}${shown.map((f: any) => ` + '  ' + r.${f.name}`).join('')})
+  })
+\`\`\`
+
+`)
+      Content(offline ?
+        `Run it again and you will see the two ${subject.name}
+records you seeded, under the ids they are filed by.
+
+` :
+        `Run it again and you will see every ${subject.name}
+record the server holds.
+
+`)
+      Content(`No URL, no HTTP verb, no JSON parsing. You asked a Seneca entity for
+a list, the provider turned that into an SDK call, and the SDK turned
+it into a request. These are ordinary Seneca entities, so everything
+you already know about the entity API applies to them.
+
+`)
+    }
+
+    if (subject.cmds.includes('load')) {
+      Content(`${step(`Load one ${subject.name}`)}
+
+${'load' === noteAt ? nestedNote : ''}Add:
+
+\`\`\`js
+  const one = await seneca
+    .entity('${canon(subject.name)}')
+    .load$(${oneArg(firstId)})
+
+  console.log('loaded', one.${idf}${0 < shown.length ? `, one.${shown[0].name}` : ''})
+\`\`\`
+
+`)
+      Content(subject.cmds.includes('list') ?
+        `\`list$\` gives you many, \`load$\` gives you one. Now ask for
+something that is not there:
+
+` :
+        `\`load$\` gives you one record by its id. Now ask for something
+that is not there:
+
+`)
+      Content(`\`\`\`js
+  const missing = await seneca
+    .entity('${canon(subject.name)}')
+    .load$(${oneArg(`'nosuch${subject.name}'`)})
+
+  console.log('missing =', missing)   // null
+\`\`\`
+
+You get \`null\`, not an exception. "There is no such
+${subject.name}" is an ordinary answer to a lookup, so it does not
+interrupt your code.
+
+`)
+    }
+
+    if (canWrite) {
+      Content(`${step('Create, change and remove')}
+
+${'write' === noteAt ? nestedNote : ''}`)
+      Content(hasRead ?
+        `Everything so far has been reading. This entity accepts writes too,
+so add:
+
+` :
+        `Now write one. Add:
+
+`)
+      Content(`\`\`\`js
+  // Create: make$ builds an entity, save$ persists it.
+  let ${subjOne} = await seneca
+    .entity('${canon(subject.name)}')
+    .make$({ ${makeFields.join(', ')} })
+    .save$()
+
+  console.log('created with id', ${subjOne}.${idf})
+\`\`\`
+
+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.
+
+`)
+
+      if (canUpdate) {
+        Content(`Now change it. An entity that already carries an id is an update
+rather than a create, and \`save$\` decides between the two on exactly
+that:
+
+\`\`\`js
+  ${subjOne}.${plainFields[0].name} = ${litval(plainFields[0], true)}
+  ${subjOne} = await ${subjOne}.save$()
+
+  console.log('updated:', ${subjOne}.${plainFields[0].name})
+\`\`\`
+
+`)
+      }
+
+      if (canRemove) {
+        Content(`And remove it, leaving the ${source} as you found it:
+
+\`\`\`js
+  await seneca
+    .entity('${canon(subject.name)}')
+    .remove$(${oneArg(`${subjOne}.${idf}`)})
+\`\`\`
+
+`)
+        if (subject.cmds.includes('load')) {
+          Content(`Load it once more and, as before, you get \`null\`:
+
+\`\`\`js
+  console.log(
+    'after remove:',
+    await seneca
+      .entity('${canon(subject.name)}')
+      .load$(${oneArg(`${subjOne}.${idf}`)})
+  )   // null
+\`\`\`
+
+`)
+        }
+      }
+      else {
+        Content(`This entity declares no remove operation, so the record you have just
+created stays where it is.
+
+`)
+      }
+
+      Content(`Those are the only methods there are:
+
+${cmdList}
+
+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 cparent = null == childParent ? 'their parent' :
+        `${childParent.name} records`
+      const cop = child.cmds.includes('list') ? 'list' : 'load'
+
+      // Live, the parent id comes from a list; offline it is seeded, so a
+      // literal is both shorter and exactly reproducible.
+      const reuse = `${subjVar}[0].${idf}`
+      const cval = offline ? `'${seedParentVal(child, ckey)}'` :
+        (null != childParent && childParent.name === subject.name &&
+          subject.cmds.includes('list') && 0 === subject.parents.length) ?
+          reuse : ident(ckey)
+
+      const cpre = (live && reuse !== cval) ?
+        `  const ${plural(childParent.name)} = await seneca
+    .entity('${canon(childParent.name)}')
+    .list$()
+  const ${ident(ckey)} = ${plural(childParent.name)}[0].${childParent.idf || 'id'}
+
+` : ''
+
+      const cargs = child.parents.map((k: string) => k === ckey ?
+        `${qkey(k)}: ${cval}` : `${qkey(k)}: '${seedParentVal(child, k)}'`)
+
+      Content(`${step(`Reach the ${child.name} records`)}
+
+${cap(child.name)} records live inside ${cparent}, and the API route
+says so:
+
+\`${child.path}\`
+
+The parent id in that path is not optional, so every ${child.name}
+call needs a \`${ckey}\` in its query:
+
+\`\`\`js
+`)
+
+      if (child.cmds.includes('list')) {
+        Content(`${cpre}  const ${plural(child.name)} = await seneca
+    .entity('${canon(child.name)}')
+    .list$({ ${cargs.join(', ')} })
+
+  console.log('found ' + ${plural(child.name)}.length + ' ${child.name} record(s)')
+`)
+      }
+      else {
+        Content(`${cpre}  const found = await seneca
+    .entity('${canon(child.name)}')
+    .load$({ ${cargs.concat([`${qkey(cidf)}: '${child.name}0'`]).join(', ')} })
+
+  console.log('found', found.${cidf})
+`)
+      }
+
+      Content(`\`\`\`
+
+Leave the \`${ckey}\` out and the call throws at once, naming the key it
+needed, rather than letting a half-built URL come back as a puzzling
+404:
+
+\`\`\`js
+  // throws: ${provider.pkgName}: ${child.name} ${cop}: ${ckey} is required
+  await seneca
+    .entity('${canon(child.name)}')
+    .${'list' === cop ? 'list$()' : `load$('${child.name}0')`}
+\`\`\`
+
+`)
+    }
+
+    if (offline) {
+      Content(`## Talking to a real server
+
+The script you have just written never touched the network. To point it
+at a running ${provider.api} server instead, replace the \`test\` and
+\`testopts\` options with that server's base URL:
+
+\`\`\`js
+    .use('${provider.pkgName}', {
+      sdk: { base: '${hasServer ? provider.liveBase : 'https://api.example.com'}' },
+    })
+\`\`\`
+
+Nothing else in the script changes — the entity calls are the same
+calls. Your seeded ids will not exist there, so read the ids you need
+from a \`list$\` first.
+
+`)
+      if (hasServer && '' !== sdkRepo) {
+        Content(`A test server that answers on that address is distributed in the SDK's
+source repository, which is the only place it ships. Clone
+\`${sdkRepo}\`, then run \`npm install\`, \`npm run build\` and
+\`npm start\` in its \`app\` folder.
+
+`)
+      }
+    }
+
+    Content(`## What you have learned
+
+You built a script that ${canWrite ? 'reads and writes' : 'reads'}
+${provider.api} data through Seneca entities,
+${live ? 'against a real server' : 'with no server involved'}. Along
+the way you saw:
+
+- Provider configuration has the same shape even when no credentials
+  are needed.
+- API resources are Seneca entities under \`provider/${provider.lower}/\`,
+  reached with the entity API you already know.
+`)
+    if (null != child || 0 < subject.parents.length) {
+      Content(`- A resource nested under another in the API needs its parent's id in
+  every query, and says which key is missing when you forget.
+`)
+    }
+    if (subject.cmds.includes('load')) {
+      Content(`- \`load$\` answers \`null\` for something that is not there, rather
+  than throwing.
+`)
+    }
+    if (canWrite) {
+      Content(`- \`save$\` creates without an id and updates with one, and the
+  ${source} chooses the id.
+`)
+    }
+    if (offline) {
+      Content(`- The offline store makes all of this runnable with nothing installed
+  but npm packages, which is also how you test your own code.
+`)
+    }
+
+    Content(`
+## Where to go next
+
+- To do a specific job — ${live ? 'run without a server' : 'point at a real server'}, reach the raw SDK,
+  test your own code — see the [how-to guides](how-to.md).
+- To look up an exact pattern, field or option, see the
+  [reference](reference.md).
+- To understand why the plugin is built this way — why entities rather
+  than one message per route, and what it does with the SDK's answers
+  — see the [explanation](explanation.md).
+- For what each of these documents is for, see the
+  [documentation index](README.md).
+`)
+  })
+})
+
+
+// --- 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
+
+  const ents = provider.entities
+  const nested = ents.filter((e: any) => 0 < e.parents.length)
+
+  // The model gives '' when the API definition declares no server. Normalise
+  // an absent value to the same thing, so a missing base is treated as absent
+  // rather than printed as a default nobody can use.
+  const liveBase = provider.liveBase || ''
+
+  // The same choice the tests and the manual scripts make: fewest parent keys
+  // (nothing to arrange), then most cmds. Recipes prefer it, so one entity
+  // carries the reader through the document wherever it can.
+  const subject = [...ents]
+    .sort((a: any, b: any) =>
+      (a.parents.length - b.parents.length) || (b.cmds.length - a.cmds.length))[0]
+
+  const forCmd = (cmd: string) => {
+    const able = ents.filter((e: any) => e.cmds.includes(cmd))
+    return able.find((e: any) => e === subject) ||
+      able.find((e: any) => 0 === e.parents.length) ||
+      able[0] || null
+  }
+
+  const canon = (e: any) => `provider/${provider.lower}/${e.name}`
+  const idf = (e: any) => e.idf || '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 parentArgs = (e: any) =>
+    e.parents.map((k: string) => `${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.
+  const oneArgs = (e: any) => 0 === e.parents.length ?
+    `'${e.name}0'` : `{ ${parentArgs(e)}, ${idf(e)}: '${e.name}0' }`
+
+  const listArgs = (e: any) =>
+    0 === e.parents.length ? '' : `{ ${parentArgs(e)} }`
+
+  // 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' }`
+
+  const key = (k: string) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : `'${k}'`
+
+  const literal = (rec: Record<string, any>) => {
+    const names = Object.keys(rec)
+    if (0 === names.length) {
+      return '{}'
+    }
+    return '{ ' + names
+      .map((k) => `${key(k)}: ` +
+        ('string' === typeof rec[k] ? `'${rec[k]}'` : String(rec[k])))
+      .join(', ') + ' }'
+  }
+
+  // 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.
+  const createData = (e: any) => {
+    const rec = seedRecord(e, 0)
+    delete rec[idf(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 newValue = (f: any) => 'number' === f.kind ? '999' :
+    'boolean' === f.kind ? 'true' : `'${f.name}-changed'`
+
+  const pathParams = (p: string) =>
+    (String(p).match(/\{([^}]+)\}/g) || []).map((s: string) => s.slice(1, -1))
+
+  const eList = forCmd('list')
+  const eLoad = forCmd('load')
+  const eSave = forCmd('save')
+  const eRemove = forCmd('remove')
+
+  // Sections as data, so the contents list and the sections cannot disagree.
+  const sections: any[] = []
+  const sec = (title: string, body: string) => sections.push({ title, body })
+
+  // GitHub's heading anchors: lowercased, punctuation dropped, spaces
+  // hyphenated. Section titles avoid backticks and full stops so this stays
+  // a faithful reproduction rather than an approximation.
+  const anchor = (title: string) => '#' + title.toLowerCase()
+    .replace(/[^a-z0-9 _-]/g, '').trim().replace(/ +/g, '-')
+
+  const NESTED_TITLE = 'Work with nested entities'
+  const OFFLINE_TITLE = 'Run offline, without a server'
+
+
+  if (null != eList) {
+    sec('List the records of an entity', `Every resource this plugin covers is a Seneca entity under
+\`provider/${provider.lower}/\`, so listing one is \`list$\`:
+
+\`\`\`js
+const ${eList.name}s = await seneca
+  .entity('${canon(eList)}')
+  .list$(${listArgs(eList)})
+\`\`\`
+
+You get an ordinary array of Seneca entities back, so \`length\`, \`map\`
+and \`data$()\` behave exactly as they do for any other store.
+
+Fields in the query travel to the API as match criteria. Seneca's own
+directives — \`sort$\`, \`limit$\` and the rest — are stripped before the
+call, because they are features of a database store and not of an HTTP
+API. If you need ordering or paging, ask the API for it using fields it
+recognises, or sort the returned array yourself.${0 < nested.length ? `
+
+An entity nested under a parent in the API path cannot be listed without
+the parent's id; see [${NESTED_TITLE}](${anchor(NESTED_TITLE)}).` : ''}`)
+  }
+
+
+  if (null != eLoad) {
+    sec('Read one record by id', `\`load$\` answers a single record:
+
+\`\`\`js
+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.
+`}
+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:
+
+\`\`\`js
+const missing = await seneca
+  .entity('${canon(eLoad)}')
+  .load$(${0 === eLoad.parents.length ? `'nosuch'` :
+    `{ ${parentArgs(eLoad)}, ${idf(eLoad)}: 'nosuch' }`})
+
+if (null == missing) {
+  // no such ${eLoad.name}
+}
+\`\`\`
+
+Everything else that can go wrong — a network failure, a 5xx, a rejected
+key — does throw, so an unhandled rejection still means something is
+genuinely wrong.`)
+  }
+
+
+  if (null != eSave) {
+    const created = literal(createData(eSave))
+
+    sec('Create a record', `\`make$\` builds an entity and \`save$\` writes it. An entity with no id
+is a create:
+
+\`\`\`js
+const ${eSave.name} = await seneca
+  .entity('${canon(eSave)}')
+  .make$(${created})
+  .save$()
+
+console.log(${eSave.name}.${idf(eSave)})
+\`\`\`
+${0 === eSave.parents.length ? '' : `
+Note that \`${eSave.parents.join('`, `')}\` travels in the DATA for a write,
+not in a query: a \`${eSave.name}\` is created inside its parent.
+`}
+\`save$\` resolves to the record as the API returned it, which is the only
+reliable source of the id. Read it from there rather than predicting it:
+what an API does with an id you supply on create is its own business, and
+several ignore it entirely.`)
+
+    const f = changeable(eSave)
+
+    sec('Update a record', `The same call updates. \`save$\` dispatches on the id: an entity carrying
+one is an update, an entity without one is a create. So the safe shape is
+load, change, save:
+
+\`\`\`js${eSave.cmds.includes('load') ? `
+const ${eSave.name} = await seneca
+  .entity('${canon(eSave)}')
+  .load$(${oneArgs(eSave)})
+` : `
+const ${eSave.name} = seneca
+  .entity('${canon(eSave)}')
+  .make$(${literal(0 === eSave.parents.length ?
+      { [idf(eSave)]: `${eSave.name}0` } :
+      { ...Object.fromEntries(eSave.parents.map(
+        (k: string) => [k, parentVal(eSave, k)])),
+      [idf(eSave)]: `${eSave.name}0` })})
+`}${null == f ? `
+// change the fields you need
+` : `
+${eSave.name}.${f.name} = ${newValue(f)}
+`}
+await ${eSave.name}.save$()
+\`\`\`
+
+Mutating the record you loaded sends it as it stood plus your change, so
+you do not depend on how the API treats a request that omits fields —
+some merge, some replace.`)
+  }
+
+
+  if (null != eRemove) {
+    sec('Remove a record', `\`\`\`js
+await seneca
+  .entity('${canon(eRemove)}')
+  .remove$(${oneArgs(eRemove)})
+\`\`\`
+${0 === eRemove.parents.length ? '' : `
+As with a read, the parent keys are part of naming the record, so they go
+in the query object alongside the id.
+`}${eRemove.cmds.includes('load') ? `
+A \`load$\` of the same id afterwards answers \`null\`.` :
+      `
+\`remove$\` resolves once the API has accepted the removal.`}`)
+  }
+
+
+  if (0 < nested.length) {
+    // A nested entity that declares no cmds has nothing to demonstrate, so
+    // prefer one that does; the error example needs a command that exists.
+    const n = nested.find((e: any) => 0 < e.cmds.length) || nested[0]
+    const firstCmd = n.cmds[0] || 'list'
+
+    sec(NESTED_TITLE, `Some resources live inside a parent, and the API path says so — the
+route for \`${n.name}\` is:
+
+\`\`\`
+${n.path}
+\`\`\`
+
+So a \`${n.name}\` cannot be addressed at all without its parent's id, and
+the provider requires those keys on every command.
+
+${nested.map((e: any) =>
+      `- \`${e.name}\` requires \`${e.parents.join('`, `')}\``).join('\n')}
+
+For reads the keys go in the query; for writes they go in the data:
+
+\`\`\`js${n.cmds.includes('list') ? `
+await seneca.entity('${canon(n)}').list$({ ${parentArgs(n)} })
+` : ''}${n.cmds.includes('load') ? `
+await seneca.entity('${canon(n)}')
+  .load$({ ${parentArgs(n)}, ${idf(n)}: '${n.name}0' })
+` : ''}${n.cmds.includes('save') ? `
+await seneca.entity('${canon(n)}')
+  .make$(${literal(createData(n))})
+  .save$()
+` : ''}${n.cmds.includes('remove') ? `
+await seneca.entity('${canon(n)}')
+  .remove$({ ${parentArgs(n)}, ${idf(n)}: '${n.name}0' })
+` : ''}\`\`\`
+
+Leave a key out and the call throws at once, naming what is missing:
+
+\`\`\`
+${provider.pkgName}: ${n.name} ${firstCmd}: ${n.parents[0]} is required
+\`\`\`
+
+That is deliberate: without it the SDK would build half a URL and the
+server would answer 404, which is a much harder message to act on. The
+[explanation](explanation.md) covers why this is a guard rather than a
+silent default.`)
+  }
+
+
+  {
+    // Seed the entity the recipes use, plus the first nested entity AND its
+    // parent — a child seeded under a parent that is not there lists as
+    // empty, which reads as a passing test that proves nothing.
+    const seeded: any[] = []
+    const add = (e: any) => {
+      if (null != e && !seeded.includes(e)) {
+        seeded.push(e)
+      }
+    }
+    const child = 0 < nested.length ? nested[0] : null
+    const parent = null == child ? null :
+      ents.find((p: any) => p.name === child.parentEntity)
+
+    add(subject)
+    if (null != child) {
+      add(parent)
+      add(child)
+    }
+    seeded.sort((a: any, b: any) => ents.indexOf(a) - ents.indexOf(b))
+
+    const seed = seeded.map((e: any) => `      ${e.name}: {
+` + [0, 1].map((i: number) =>
+      `        ${e.name}${i}: ${literal(seedRecord(e, i))},`).join('\n') + `
+      },`).join('\n')
+
+    sec(OFFLINE_TITLE, `The SDK ships an in-memory mock transport. Turn it on with \`test\` and
+seed it with \`testopts\`:
+
+\`\`\`js
+.use('${provider.pkgName}', {
+  test: true,
+  testopts: {
+    entity: {
+${seed}
+    },
+  },
+})
+\`\`\`
+
+Records are keyed by id under their entity name, and the id inside the
+record has to match the key it is filed under. Every command then works
+offline, not-found included: an id you did not seed answers \`null\`,
+exactly as it would against a real server.${null == parent || null == child ? '' : `
+
+A nested record has to point at a parent that is actually seeded: each
+\`${child.name}\` above carries \`${child.parents[0]}: '${parentVal(child, child.parents[0])}'\`, and
+that is a \`${parent.name}\` the seed contains. Seed a child under a parent
+that is not there and its list comes back empty rather than failing —
+which, in a test, reads as a pass that proves nothing.`}
+
+This is how this plugin's own suite runs, and it is the recommended way
+to test application code that uses the provider: no server, no network,
+and the same code path as production. See \`test/seed.js\`, which seeds
+every entity this way.`)
+  }
+
+
+  sec('Point at a different server', `The \`sdk\` option is passed straight to the \`${provider.sdkClass}\`
+constructor, so \`base\` chooses the host:
+
+\`\`\`js
+.use('${provider.pkgName}', {
+  sdk: { base: 'https://${provider.lower}.example.com' },
+})
+\`\`\`
+
+${'' === liveBase ?
+    `The API definition declares no server, so there is no default worth
+relying on: set \`base\` explicitly, or run against the mock instead (see
+[${OFFLINE_TITLE}](${anchor(OFFLINE_TITLE)})).` :
+    `The SDK's own default is \`${liveBase}\`, which is where the
+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
+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 },
+  })
+  .use('provider', {
+    provider: {
+      ${provider.lower}: {
+        keys: {
+          apikey: { value: '$${provider.ENV}_APIKEY' },
+        },
+      },
+    },
+  })
+\`\`\`
+
+Every request then carries \`authorization: Bearer <apikey>\`. An absent
+or empty key adds no header at all, so an API that needs no credentials
+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
+value rather than its structure.
+
+For a different scheme, set the header yourself. Headers supplied through
+\`sdk\` win over the one the key would have set:
+
+\`\`\`js
+.use('${provider.pkgName}', {
+  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
+unexpectedly:
+
+\`\`\`js
+const info = await seneca.post(
+  'sys:provider,provider:${provider.lower},get:info')
+\`\`\`
+
+\`\`\`js
+{
+  ok: true,
+  name: '${provider.lower}',
+  version: '${provider.version}',
+  sdk: { name: '${provider.sdkPkg}', version: '${provider.sdkVersion}' },
+}
+\`\`\`
+
+\`version\` is this plugin's; \`sdk.version\` is the SDK it is running
+against. That pair is what to quote in a bug report, because the two are
+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) ?
+      `${dpe.name}0` : `${k.replace(/_id$/, '')}0`
+
+    sec('Reach the SDK directly', `The entity API covers the operations the API model declares. For
+anything else — an endpoint with no entity behind it, a response header
+you need to read — take the configured SDK client out of the plugin's
+exports:
+
+\`\`\`js
+const sdk = seneca.export('${provider.pluginName}/sdk')()
+\`\`\`
+
+The export is a function, so call it, and it only answers after
+\`seneca.ready()\` — that is when the plugin builds the client with the
+resolved key.
+
+SDK operations resolve to SDK ENTITY instances rather than plain data, so
+read the record out with \`.data()\`. The provider does this for you; here
+you do it yourself:
+
+\`\`\`js${dpe.cmds.includes('list') ? `
+const ${dpe.name}s = (await sdk.${dpe.acc}().list(${listArgs(dpe)}))
+  .map((r) => r.data())
+` : ''}${dpe.cmds.includes('load') ? `
+const one = (await sdk.${dpe.acc}().load(${sdkLoadArgs(dpe)})).data()
+` : ''}\`\`\`
+
+For a route the entity model does not cover at all, \`direct\` sends a
+request and hands back the raw response:
+
+\`\`\`js
+const res = await sdk.direct({
+  path: '${dpath}',
+  method: 'GET',${0 === dparams.length ? '' : `
+  params: { ${dparams.map((k: string) => `${key(k)}: '${dval(k)}'`).join(', ')} },`}
+})
+
+if (res instanceof Error) throw res
+if (!res.ok) throw (res.err || new Error('status ' + res.status))
+
+console.log(res.data)
+\`\`\`
+
+\`prepare()\` builds the same request without sending it, which is the
+quickest way to see what the SDK would actually do — url, method, headers
+and body, before anything leaves the process.
+
+Raw data becomes a Seneca entity again through \`data$\`:
+
+\`\`\`js
+const ent = seneca.entity('${canon(dpe)}').data$(res.data)
+\`\`\``)
+  }
+
+
+  sec('Develop against a local SDK checkout', `The SDK is an ordinary published dependency, so normal use needs nothing
+special:
+
+\`\`\`sh
+$ npm install
+\`\`\`
+
+If you are changing the SDK and this plugin together, point npm at a
+local checkout instead. Clone the SDK beside this repository, at the path
+this project expects, and build it — it does not commit its build output:
+
+\`\`\`sh
+$ git clone ${provider.sdkRepoUrl}.git \\
+    ${provider.sdkrel}
+$ cd ${provider.sdkrel}/ts
+$ npm install && npm run build
+\`\`\`
+
+Then link it in, without committing the change to \`package.json\`:
+
+\`\`\`sh
+$ npm install --no-save ${provider.sdkrel}/ts
+\`\`\`
+
+npm creates a symlink, so a rebuild of the SDK is picked up here with no
+reinstall:
+
+\`\`\`sh
+$ ls -l node_modules/${provider.sdkPkg}
+\`\`\`
+
+To go back to the published SDK:
+
+\`\`\`sh
+$ rm -rf node_modules/${provider.sdkPkg} package-lock.json && npm install
+\`\`\`
+
+Removing the lockfile matters. npm will happily keep resolving to the
+link if the lockfile still records it and the local version satisfies the
+range.`)
+
+
+  {
+    const pattern = subject.cmds.includes('load') ? `${subject.name}-load` :
+      subject.cmds.includes('list') ? `${subject.name}-list` : 'happy'
+    const skipped = subject.cmds.includes('list') ?
+      `${subject.name}-list` : `${subject.name}-load-missing`
+
+    sec('Run the test suite', `\`\`\`sh
+$ npm run build
+$ npm test
+\`\`\`
+
+The build comes first: the suite runs against \`dist\`, so an unbuilt
+change is not the change you are testing.
+
+The offline tests use the SDK mock and always run.${'' === liveBase ? '' : ` The live tests
+probe for a server first and skip cleanly when there is none, so a clean
+checkout is green on a machine that has never started one:
+
+\`\`\`
+﹣ ${skipped} # no ${provider.lower} server at ${liveBase}
+\`\`\``}
+
+Coverage, and a single test by name:
+
+\`\`\`sh
+$ npm run test-coverage
+$ TEST_PATTERN=${pattern} npm run test-some
+\`\`\``)
+  }
+
+
+  if ('' !== liveBase) {
+    sec('Run the live tests against a server', `The companion test server ships only in the SDK's source repository, not
+in the published package. From the checkout beside this one:
+
+\`\`\`sh
+$ cd ${provider.sdkrel}/app
+$ npm install && npm run build && npm start
+\`\`\`
+
+Then run the suite as usual: the live tests find the server and activate
+themselves.
+
+\`\`\`sh
+$ npm test
+\`\`\`
+
+To target a server somewhere else:
+
+\`\`\`sh
+$ ${provider.ENV}_TEST_BASE=http://localhost:9000 npm test
+\`\`\`
+
+The generated live tests only read, so a run leaves the server exactly as
+it found it.${subject.cmds.includes('save') && subject.cmds.includes('remove') ? `
+
+Two manual scripts are there for poking at a running server by hand:
+
+\`\`\`sh
+$ node test/live.js     # read from each entity
+$ node test/quick.js    # a full write cycle, cleaning up after itself
+\`\`\`` : `
+
+\`node test/live.js\` reads from each entity, for poking at a running
+server by hand.`}`)
+  }
+
+
+  sec('Build and release', `\`\`\`sh
+$ npm run build      # tsc --build src test
+$ npm run watch      # the same, in watch mode
+$ npm run reset      # clean, install, build, test
+\`\`\`
+
+Releasing follows the Seneca convention, in one command — clean, install,
+build, test, tag from \`package.json\`, publish:
+
+\`\`\`sh
+$ npm run repo-publish
+\`\`\`
+
+Only \`dist\`, the TypeScript sources and the licence file are published;
+the test suite and its build output stay in the repository.
+
+Before publishing, check that \`package.json\` still depends on the
+published SDK by version range and not on a local path: a \`file:\`
+dependency left behind from local development installs perfectly on your
+own machine and cannot be resolved by anybody else.
+
+One last thing: this repository is GENERATED from the ${provider.api} API
+model by [@voxgig/sdkgen](https://github.com/voxgig/sdkgen). An edit made
+here survives exactly as long as the next generation run. Change the
+model, or the components that build this target, and regenerate.`)
+
+
+  File({ name: 'how-to.md' }, () => {
+    Content(`# How-to guides
+
+Each guide here solves one problem, and assumes you already have a
+working Seneca instance with this plugin loaded. If you do not, work
+through the [tutorial](tutorial.md) first.
+
+These guides show what to do and leave out the reasoning — that is in the
+[explanation](explanation.md), and the exact patterns, fields and options
+are listed in the [reference](reference.md).
+
+`)
+
+    each(sections, (s: any) => {
+      Content(`- [${s.title}](${anchor(s.title)})
+`)
+    })
+
+    each(sections, (s: any) => {
+      Content(`
+## ${s.title}
+
+${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
+
+  // 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]
+
+  const nested = provider.entities.filter((e: any) => 0 < e.parents.length)
+  const saving = provider.entities.filter((e: any) => e.cmds.includes('save'))
+
+  // Entities whose API offers BOTH create and update: only for those does
+  // `save$` dispatch on the id. Where it offers one, saying otherwise is wrong.
+  const dispatch = saving.filter((e: any) =>
+    e.ops.includes('create') && e.ops.includes('update'))
+  const oneway = saving.filter((e: any) => !dispatch.includes(e))
+
+  const anyCmd = (c: string) => provider.entities.some((e: any) => e.cmds.includes(c))
+  const anyOp = (o: string) => saving.some((e: any) => e.ops.includes(o))
+
+  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}`
+
+  const cmdList = (e: any) => e.cmds.map((c: string) => '`' + c + '$`').join(', ')
+
+  const keys = (list: string[]) => '`' + list.join('`, `') + '`'
+
+  // The same list as prose: `a`, `b` and `c`.
+  const keysAnd = (list: string[]) => 1 === list.length ? keys(list) :
+    `${keys(list.slice(0, -1))} and \`${list[list.length - 1]}\``
+
+  // 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(', ')} }`
+
+  // 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])
+
+  // The required-key phrasing, which has to read correctly for one key as
+  // well as several.
+  const reqd = (list: string[]) =>
+    1 === list.length ? `${keys(list)} **required**` :
+      2 === list.length ? `\`${list[0]}\` and \`${list[1]}\`, both **required**` :
+        `${keys(list)}, all **required**`
+
+  // The example used in the error block: whichever command the subject has.
+  const errCall = subject.cmds.includes('list') ?
+    `list$(${0 < subject.parents.length ? query(subject, []) : ''})` :
+    subject.cmds.includes('load') ? `load$(${oneArg(subject)})` :
+      subject.cmds.includes('remove') ? `remove$(${oneArg(subject)})` :
+        'make$({ ... }).save$()'
+
+  File({ name: 'reference.md' }, () => {
+    Content(`# Reference
+
+Complete description of the interface exposed by
+\`${provider.pkgName}\` version ${provider.version}.
+
+This document describes the machinery and assumes you know what you are
+looking for. To learn the plugin, start with the [tutorial](tutorial.md);
+for recipes, see the [how-to guides](how-to.md); for the reasoning behind
+the design, see the [explanation](explanation.md). The package overview is
+the [README](../README.md), and the document index is [here](README.md).
+
+- [Requirements](#requirements)
+- [Registration](#registration)
+- [Options](#options)
+- [Entities](#entities)
+- [Action patterns](#action-patterns)
+- [Plugin exports](#plugin-exports)
+- [Errors](#errors)
+- [Authentication keys](#authentication-keys)
+- [Environment variables](#environment-variables)
+- [Package scripts](#package-scripts)
+
+## Requirements
+
+| Item | Value |
+| ---- | ----- |
+| Node.js | \`>=24\` |
+| Module format | CommonJS |
+| SDK | [\`${provider.sdkPkg}\`](https://www.npmjs.com/package/${provider.sdkPkg}) \`^${provider.sdkVersion}\` |
+
+The SDK is an ordinary published dependency, installed by \`npm install\`
+like any other.
+`)
+
+    if (live) {
+      Content(`
+The companion **test server** used by the live tests is a separate matter:
+it ships only in the SDK's [source repository](${provider.sdkRepoUrl}) under
+\`app/\`, and is not published. It is needed only to run the live tests —
+see the [how-to guides](how-to.md).
+`)
+    }
+
+    Content(`
+### Peer dependencies
+
+All must be present in the host application. The accepted version ranges are
+declared in this package's \`package.json\`.
+
+| Package | Purpose |
+| ------- | ------- |
+| \`seneca\` | The host framework. The plugin runs inside the host's instance, never its own. |
+| \`seneca-entity\` | The entity API the canons below are served through. |
+| \`seneca-promisify\` | The promise-returning message API. |
+| \`@seneca/provider\` | The provider convention, including \`provider/entityBuilder\`. |
+| \`@seneca/env\` | Resolves \`$\`-prefixed key values from the environment. |
+
+## Registration
+
+The plugin name is \`${provider.pluginName}\`. It must be registered after
+\`entity\`, \`promisify\` and \`provider\`:
+
+\`\`\`js
+Seneca({ legacy: false })
+  .use('promisify')
+  .use('entity')
+  .use('provider', { ... })
+`)
+
+    if (live) {
+      Content(`  .use('${provider.pkgName}', { sdk: { base: '${provider.liveBase}' } })
+\`\`\`
+`)
+    }
+    else {
+      Content(`  .use('${provider.pkgName}', { sdk: { base: BASE } })
+\`\`\`
+
+The ${provider.api} definition declares no server, so there is no default
+base URL: \`BASE\` is the URL of the API you are talking to, and it must be
+supplied through the \`sdk\` option.
+`)
+    }
+
+    Content(`
+The SDK client is constructed during plugin startup and is not available
+until \`seneca.ready()\` resolves.
+
+## Options
+
+| Option | Type | Default | Effect |
+| ------ | ---- | ------- | ------ |
+| \`sdk\` | object | \`{}\` | Passed straight to the \`${provider.sdkClass}\` constructor. Most usefully \`base\`. |
+| \`test\` | boolean | \`false\` | Run the SDK against its in-memory mock transport instead of HTTP. |
+| \`testopts\` | object | \`{}\` | Test-feature options, used only when \`test\` is true. \`{entity: {...}}\` seeds the mock. |
+
+### \`sdk\`
+
+Any option the \`${provider.sdkClass}\` constructor accepts:
+
+| Key | Effect |
+| --- | ------ |
+| \`base\` | Base URL for API requests. ${live ?
+      `The SDK's own default is \`${provider.liveBase}\`.` :
+      'There is no default: this API declares no server, so it must be set.'} |
+| \`prefix\` / \`suffix\` | URL fragments placed around the path. |
+| \`headers\` | Headers sent on every request. These win over the \`authorization\` header the provider adds from a configured key. |
+| \`system\` | System overrides, e.g. a custom \`fetch\`. |
+
+### \`test\` and \`testopts\`
+
+\`\`\`js
+.use('${provider.pkgName}', {
+  test: true,
+  testopts: {
+    entity: {
+`)
+    each(provider.entities, (e: any) => {
+      Content(`      ${e.name}: { ${e.name}0: ${JSON.stringify(seedRecord(e, 0))} },
+`)
+    })
+    Content(`    },
+  },
+})
+\`\`\`
+
+Mock records are keyed by id under their entity name. In this mode no
+network calls are made, and an unseeded id produces the same not-found
+behaviour as a live server. This package's own \`test/seed.js\` is generated
+in exactly this shape.
+`)
+
+    if (0 < nested.length) {
+      Content(`
+A nested record's parent key must name a record the parent entity also
+seeds: the mock resolves the path literally, so an unmatched parent id
+yields nothing rather than an error.
+`)
+    }
+
+    Content(`
+## Entities
+
+The plugin registers ${1 === provider.entities.length ?
+      'one entity canon' : `${provider.entities.length} entity canons`}.
+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 |
+| ------------ | ------------ | ----- | -------- | ----------- | -------- |
+`)
+    each(provider.entities, (e: any) => {
+      Content(`| \`${canon(e)}\` | \`sdk.${e.acc}()\` | \`${e.path}\` | \`${e.idf}\` | ${0 < e.parents.length ?
+        keys(e.parents) : '—'} | ${cmdList(e)} |
+`)
+    })
+
+    each(provider.entities, (e: any) => {
+      const hasCreate = e.ops.includes('create')
+      const hasUpdate = e.ops.includes('update')
+
+      Content(`
+### \`${canon(e)}\`
+
+Backed by \`sdk.${e.acc}()\`, whose results are \`${e.cls}\` instances; the
+provider hands Seneca the plain record from \`.data()\`.
+`)
+
+      if (0 < e.parents.length) {
+        Content(`
+\`${e.name}\` is nested under \`${e.path}\` in the API, so **every**
+\`${e.name}\` command requires ${keysAnd(e.parents)}. Omitting one throws —
+\`${provider.pkgName}: ${e.name} <cmd>: ${e.parents[0]} is required\` —
+before any request is made, rather than issuing one that would 404.
+`)
+      }
+
+      Content(`
+| Command | Query / data | Returns |
+| ------- | ------------ | ------- |
+`)
+      if (e.cmds.includes('list')) {
+        Content(`| \`list$(q)\` | ${0 < e.parents.length ?
+          `${reqd(e.parents)}, plus optional match fields` :
+          'optional match fields'} | Array of \`${e.name}\` entities. |
+`)
+      }
+      if (e.cmds.includes('load')) {
+        Content(`| \`load$(q)\` | ${reqd([...e.parents, e.idf])} | One \`${e.name}\`, or \`null\` if not found. |
+`)
+      }
+      if (e.cmds.includes('save')) {
+        Content(`| \`save$()\` | entity data${0 < e.parents.length ?
+          `, including ${keysAnd(e.parents)}` : ''} | ${hasCreate && hasUpdate ?
+            `Created or updated \`${e.name}\`.` : hasCreate ?
+              `Created \`${e.name}\`; the API declares no update operation.` :
+              `Updated \`${e.name}\`; the API declares no create operation.`} |
+`)
+      }
+      if (e.cmds.includes('remove')) {
+        Content(`| \`remove$(q)\` | ${reqd([...e.parents, e.idf])} | \`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) {
+        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.
+`)
+      }
+
+      if (0 === e.fields.length) {
+        Content(`
+The API definition declares no required fields for this entity; whatever it
+returns is passed through unchanged.
+`)
+      }
+      else {
+        Content(`
+Required fields, as declared by the API definition. Optional fields the API
+also defines are passed through unchanged in both directions.
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+`)
+        each(e.fields, (f: any) => {
+          Content(`| \`${f.name}\` | ${f.kind} | ${f.name === e.idf ? 'Id field.' :
+            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.`) : ''} |
+`)
+        })
+      }
+
+      if (e.cmds.includes('list') || e.cmds.includes('load')) {
+        Content(`
+\`\`\`js
+`)
+        if (e.cmds.includes('list')) {
+          Content(`const ${e.name}s = await seneca
+  .entity('${canon(e)}')
+  .list$(${0 < e.parents.length ? query(e, []) : ''})
+`)
+        }
+        if (e.cmds.includes('load')) {
+          Content(`const ${e.name} = await seneca
+  .entity('${canon(e)}')
+  .load$(${oneArg(e)})
+`)
+        }
+        Content(`\`\`\`
+`)
+      }
+    })
+
+    if (0 < dispatch.length) {
+      // 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 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)}`),
+      ].join(', ')
+
+      Content(`
+### Create versus update
+
+\`save$\` follows the Seneca convention: an entity **without** an id is
+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}.
+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)}
+` : ''}await ${s.name}.save$()
+\`\`\`
+
+Whether a client-supplied id survives a create is a property of the API, not
+of this plugin: many assign the id themselves and ignore the one sent. Read
+the id back off the returned entity rather than assuming the one you set.
+`)
+    }
+
+    if (0 < oneway.length) {
+      if (0 === dispatch.length) {
+        Content(`
+### Create versus update
+
+\`save$\` normally dispatches on the id: an entity without one is created,
+an entity with one is updated.
+`)
+      }
+
+      Content(`
+${1 === oneway.length ?
+        'This entity supports only one half of that pair, so `save$` does not' :
+        'These entities support only one half of that pair, so `save$` does not'}
+dispatch for ${1 === oneway.length ? 'it' : 'them'}:
+
+| Canon | Behaviour of \`save$\` |
+| ----- | -------------------- |
+`)
+      each(oneway, (e: any) => {
+        Content(`| \`${canon(e)}\` | Always ${e.ops.includes('create') ? 'creates' : 'updates'}; the API declares no ${e.ops.includes('create') ? 'update' : 'create'} operation. |
+`)
+      })
+    }
+
+    Content(`
+### Command to SDK operation
+
+| Seneca command | SDK call | Notes |
+| -------------- | -------- | ----- |
+`)
+    if (anyCmd('list')) {
+      Content(`| \`list$(q)\` | \`.list(q)\` | Query keys are passed through as match fields. |
+`)
+    }
+    if (anyCmd('load')) {
+      Content(`| \`load$(q)\` | \`.load({ ...keys })\` | Only the keys the route needs are sent. |
+`)
+    }
+    if (anyOp('create')) {
+      Content(`| \`save$()\` on an entity with no id | \`.create(data)\` | Data is the entity's own fields, without Seneca metadata. |
+`)
+    }
+    if (anyOp('update')) {
+      Content(`| \`save$()\` on an entity with an id | \`.update(data)\` | |
+`)
+    }
+    if (anyCmd('remove')) {
+      Content(`| \`remove$(q)\` | \`.remove({ ...keys })\` | Resolves to \`null\` whatever the API returns. |
+`)
+    }
+
+    Content(`
+Every SDK operation resolves to an SDK entity instance, or a list of them,
+rather than raw data. The provider calls \`.data()\` on each and hands the
+plain record to \`entize\`, so what comes back is an ordinary Seneca entity
+under this plugin's canon, carrying none of the SDK's own markers.
+
+### Query fields
+
+Seneca query directives — any key ending in \`$\`, such as \`sort$\` or
+\`limit$\` — are stripped before the query reaches the SDK. They are
+instructions to a store, not match fields for the API, and are not
+otherwise supported.
+
+## Action patterns
+
+### \`sys:provider,provider:${provider.lower},get:info\`
+
+Returns metadata about the plugin and SDK. Answered locally; makes no API
+call.
+
+\`\`\`js
+await seneca.post('sys:provider,provider:${provider.lower},get:info')
+\`\`\`
+
+\`\`\`js
+{
+  ok: true,
+  name: '${provider.lower}',
+  version: '${provider.version}',
+  sdk: {
+    name: '${provider.sdkPkg}',
+    version: '${provider.sdkVersion}',
+  },
+}
+\`\`\`
+
+Both versions are read at runtime from the respective \`package.json\`, so
+they describe what is installed rather than what was generated.
+
+### Entity patterns
+
+Registered by \`@seneca/provider\`. Normally reached through the entity API
+rather than posted directly.
+
+| Pattern |
+| ------- |
+`)
+    each(provider.entities, (e: any) => {
+      Content(e.cmds
+        .map((c: string) =>
+          `| \`sys:entity,zone:provider,base:${provider.lower},name:${e.name},cmd:${c}\` |\n`)
+        .join(''))
+    })
+
+    Content(`
+### Inherited from \`@seneca/provider\`
+
+| Pattern | Purpose |
+| ------- | ------- |
+| \`sys:provider,get:key\` | Fetch one named key for a provider. |
+| \`sys:provider,get:keymap\` | Fetch all keys for a provider. |
+| \`sys:provider,list:provider\` | List registered providers and their key names. |
+
+## Plugin exports
+
+### \`${provider.pluginName}/sdk\`
+
+A function returning the configured \`${provider.sdkClass}\` instance.
+
+\`\`\`js
+const sdk = seneca.export('${provider.pluginName}/sdk')()
+`)
+    if (subject.ops.includes('list')) {
+      Content(`
+// Every SDK operation resolves to an SDK entity (or a list of them),
+// not raw data; \`.data()\` gives the plain record.
+const ${subject.name}s = (await sdk.${subject.acc}().list()).map((e) => e.data())
+`)
+    }
+    if ('' !== provider.probePath) {
+      Content(`
+// \`direct\` reaches endpoints outside the entity model.
+const res = await sdk.direct({ path: '${provider.probePath}', method: 'GET' })
+`)
+    }
+    Content(`\`\`\`
+
+Available only after \`seneca.ready()\`. Use it for SDK features the entity
+API does not surface — notably \`direct()\` and \`prepare()\` for endpoints
+the entity model does not cover.
+
+## Errors
+
+| Situation | Behaviour |
+| --------- | --------- |
+`)
+    if (anyCmd('load')) {
+      Content(`| \`load$\` for a non-existent id | Resolves to \`null\`. |
+`)
+    }
+    if (anyCmd('remove')) {
+      Content(`| \`remove$\` for a non-existent id | Resolves to \`null\`; not an error. |
+`)
+    }
+    if (0 < nested.length) {
+      Content(`| A nested entity command missing a parent key | Throws before any request is made. |
+`)
+    }
+    if (anyCmd('list') || anyCmd('save')) {
+      Content(`| A 404 from \`${[anyCmd('list') ? 'list$' : '', anyCmd('save') ? 'save$' : ''].filter((s: string) => '' !== s).join('` or `')}\` | Thrown. Only single-record reads and removes map a 404 to \`null\`. |
+`)
+    }
+    Content(`| Any other non-2xx response | Thrown as raised by the SDK. |
+| A request that never got a response | Thrown, with \`status\` \`-1\`. |
+
+SDK errors are \`${provider.Name}Error\` instances carrying
+\`is${provider.Name}Error: true\`, a \`code\` (e.g. \`request_status\`), the
+HTTP \`status\` at the top level (\`-1\` when the request never got a
+response), a \`notFound\` flag, and a \`ctx\` holding the request context and
+its \`result\` — \`status\`, \`statusText\`, \`headers\` and \`body\`. The
+\`null\`-on-missing behaviour is triggered by \`err.notFound\`, not by
+inspecting the status at the call site.
+
+\`\`\`js
+try {
+  await seneca.entity('${canon(subject)}').${errCall}
+}
+catch (err) {
+  console.error(err.code, err.status, err.notFound)
+}
+\`\`\`
+`)
+
+    if (0 < nested.length) {
+      Content(`
+The missing-parent-key guard is this plugin's own, thrown before the SDK is
+called at all. Its message names the entity, the command and the key:
+
+| Entity | Message |
+| ------ | ------- |
+`)
+      each(nested, (e: any) => {
+        Content(e.parents
+          .map((k: string) =>
+            `| \`${e.name}\` | \`${provider.pkgName}: ${e.name} <cmd>: ${k} is required\` |\n`)
+          .join(''))
+      })
+      Content(`
+where \`<cmd>\` is the command that was called. A key counts as missing if
+it is absent, \`null\` or the empty string.
+`)
+    }
+
+    Content(`
+## Authentication keys
+
+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.
+
+\`\`\`js
+  .use('provider', {
+    provider: {
+      ${provider.lower}: {
+        keys: {
+          apikey: { value: '$${provider.ENV}_APIKEY' },
+        },
+      },
+    },
+  })
+\`\`\`
+
+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.
+
+## Environment variables
+
+The plugin never reads the environment itself. These are the variables the
+surrounding convention and tooling resolve:
+
+| Variable | Read by | Purpose |
+| -------- | ------- | ------- |
+| \`$${provider.ENV}_APIKEY\` | \`@seneca/env\` | Supplies the \`apikey\` value when the key is declared as \`'$${provider.ENV}_APIKEY'\`, as above. |
+`)
+    if (live) {
+      Content(`| \`$${provider.ENV}_TEST_BASE\` | The test suite and the manual scripts | Base URL for the live tests. Defaults to \`${provider.liveBase}\`. |
+`)
+    }
+
+    Content(`
+## Package scripts
+
+| Script | Action |
+| ------ | ------ |
+| \`npm run build\` | \`tsc --build src test\` — compiles to \`dist\` and \`dist-test\`. |
+| \`npm run watch\` | The same, in watch mode. |
+| \`npm test\` | Runs the \`node:test\` suite. |
+| \`npm run test-some\` | Runs tests matching \`$TEST_PATTERN\`. |
+| \`npm run test-watch\` | Test suite in watch mode. |
+| \`npm run test-coverage\` | Test suite with Node's built-in coverage. |
+| \`npm run clean\` | Removes \`node_modules\`, \`dist\`, \`dist-test\`, \`.tsbuildinfo\`, lockfiles. |
+| \`npm run reset\` | \`clean\`, then install, build and test. |
+| \`npm run repo-tag\` | Commits, tags and pushes \`v<version>\` taken from \`package.json\`. |
+| \`npm run repo-publish\` | Clean install, then \`repo-publish-quick\`. |
+| \`npm run repo-publish-quick\` | Build, test, tag, and publish to npm. |
+
+### Repository layout
+
+| Path | Contents |
+| ---- | -------- |
+| \`src/\` | TypeScript source, with its own \`tsconfig.json\`. |
+| \`test/\` | Test suite (\`.js\`, run by \`node:test\`) and TypeScript fixtures. |
+| \`dist/\` | Compiled source. Committed; published. |
+| \`dist-test/\` | Compiled test fixtures. Committed; **not** published. |
+| \`.tsbuildinfo/\` | Incremental build cache. Not committed. |
+| \`doc/\` | This documentation. |
+
+This repository is generated by
+[@voxgig/sdkgen](https://github.com/voxgig/sdkgen) from the ${provider.api}
+API definition. Anything edited here is overwritten by the next generation
+run; changes belong in the model.
+`)
+
+    if (live) {
+      const listable = provider.entities
+        .filter((e: any) => e.cmds.includes('list'))
+        .map((e: any) => e.name)
+
+      Content(`
+### Manual scripts
+
+Not part of \`npm test\`: they need the companion test server, which is
+distributed only in the SDK's source repository.
+
+| Script | Purpose |
+| ------ | ------ |
+`)
+      Content(`| \`node test/live.js\` | ${0 < listable.length ?
+        `Read ${listable.join(', ')} from a running server.` :
+        'Reads from a running server; no entity here supports `list$`, so it does nothing.'} |
+`)
+      if (quick) {
+        Content(`| \`node test/quick.js\` | Exercise the full write cycle on \`${subject.name}\`, cleaning up after itself. |
+`)
+      }
+      Content(`
+${quick ? 'Both scripts target' : 'It targets'} \`$${provider.ENV}_TEST_BASE\`, defaulting to
+\`${provider.liveBase}\`.
+`)
+    }
+  })
+})
+
+
+// --- 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]
+
+  const nested = provider.entities.filter((e: any) => 0 < e.parents.length)
+  const writable = provider.entities.filter((e: any) => e.cmds.includes('save'))
+  const loadable = provider.entities.filter((e: any) => e.cmds.includes('load'))
+  const removable = provider.entities.filter((e: any) => e.cmds.includes('remove'))
+
+  // Entities where `save` has nothing to dispatch on, because the API offers
+  // only one of create/update. Worth naming: their `save$` ignores the id
+  // rule the rest of this document explains.
+  const onesided = writable.filter((e: any) =>
+    !(e.ops.includes('create') && e.ops.includes('update')))
+
+  const code = (s: string) => '`' + s + '`'
+  const list = (names: string[]) => names.map(code).join(', ')
+
+  // What the offline suite actually covers, so the prose does not claim a
+  // `load` test for an entity that has no load.
+  const covered: string[] = []
+  if (subject.cmds.includes('list')) covered.push('list')
+  if (subject.cmds.includes('load')) covered.push('load', 'the not-found answer')
+  if (0 < nested.length) covered.push('the nested-entity rules')
+  const coveredPhrase = 0 < covered.length ? ` — ${covered.join(', ')} —` : ''
+
+  const othersSentence = 1 < provider.entities.length ?
+    'The other entities carry whatever their own operations support; the\n' +
+    '[reference](reference.md) lists them all.' :
+    'It is the only entity this API declares, and the\n' +
+    '[reference](reference.md) spells its commands out.'
+
+  // The nesting section names the parent entity when the model knows it, and
+  // falls back to the path params when a parent key points at nothing declared.
+  const n = nested[0]
+  const nestLead = null == n ? '' :
+    '' !== n.parentEntity ?
+      `The API nests ${code(n.name)} under ${code(n.parentEntity)}: a ` +
+      `${code(n.name)}'s URL contains its ${code(n.parentEntity)}.` :
+      `The API nests ${code(n.name)} under a parent resource: a ` +
+      `${code(n.name)}'s URL contains ${list(n.parents)}.`
+
+  File({ name: 'explanation.md' }, () => {
+    Content(`# Explanation
+
+This document discusses why \`${provider.pkgName}\` is built the way it is.
+It does not tell you how to do anything — for that see the
+[tutorial](tutorial.md) and the [how-to guides](how-to.md), and for the exact
+patterns, entities and options, the [reference](reference.md). The whole set is
+indexed in [doc/README.md](README.md).
+
+
+## The provider convention
+
+Seneca applications talk to the outside world through *providers*. A provider
+is a plugin that makes a third-party API look like a Seneca data source, so
+application code uses the entity API it already knows instead of learning a
+client library per service.
+
+The payoff is uniformity. An application reading from ${provider.api}, a
+payment processor and a CRM uses one access pattern for all three:
+
+\`\`\`js
+await seneca.entity('provider/${provider.lower}/${subject.name}').list$()
+await seneca.entity('provider/stripe/charge').list$()
+\`\`\`
+
+Because these are ordinary Seneca entities, everything built on the entity API
+— logging, tracing, message interception, test doubles — applies to remote
+calls without any special support for HTTP.
+
+
+## What entityBuilder buys
+
+The convention is more than a naming scheme. \`@seneca/provider\` exports
+\`provider/entityBuilder\`, and this plugin hands it exactly one thing: a map
+from entity name to a small set of cmd actions. Recognising the
+\`provider/${provider.lower}/\` canon, registering the \`role:entity\` messages
+that sit behind \`list$\`, \`load$\`, \`save$\` and \`remove$\`, and turning
+whatever an action returns into an entity of the right canon — none of that is
+written here. It arrives with the convention.
+
+What remains is a handful of async functions, each a few lines long, whose
+whole job is to call the SDK and hand the result back through the \`entize\`
+function entityBuilder supplies. That thinness is the point rather than an
+accident of effort: a provider that is nearly all glue can be read at a glance,
+generated in full, and regenerated when the API moves. Cleverness added here is
+cleverness that has to be maintained against a moving target.
+
+
+## Two layers of the same idea
+
+This provider is unusual among Seneca providers in that the thing it wraps is
+*already* entity-shaped. The ${provider.api} SDK exposes accessors like
+\`client.${subject.acc}()\` — carrying
+${list(subject.ops)} —
+rather than raw HTTP routes, for much the same reason Seneca does. A small,
+uniform surface is easier for people and for agents to reason about than a set
+of URL templates.
+
+So the provider is mostly a translation between two entity models that already
+agree on the important things. Where they *disagree* is where this plugin has
+to do real work, and each disagreement is discussed below.
+
+
+## Where the SDK and Seneca disagree
+
+### Four commands, five operations
+
+Seneca's store commands are \`list\`, \`load\`, \`save\` and \`remove\`. The
+SDK's operations are \`list\`, \`load\`, \`create\`, \`update\` and \`remove\`.
+Four of the five line up. \`save\` is the join, and it dispatches on the id: an
+entity carrying one is an update, an entity without one is a create.
+
+`)
+
+    if (0 < writable.length) {
+      Content(`That is Seneca's convention rather than this plugin's invention, and it is a
+good one. Exposing create and update separately would push the HTTP verb back
+into application code — the caller who loaded a record, changed a field and
+called \`save$\` would have to know whether that becomes a POST or a PUT. The
+presence of the id already answers the question. Asking the caller to answer it
+again only adds a way to be wrong.
+
+`)
+    }
+
+    Content(`Which commands exist at all is decided per entity, from the operations the API
+declares, rather than from an assumption that everything is CRUD.
+\`${subject.name}\` carries
+${list(subject.cmds.map((c: string) => c + '$'))}.
+${othersSentence}
+An entity whose API has no create and no update simply has no \`save$\`, which
+is a better answer than a \`save$\` that exists and then fails at the HTTP
+layer.
+
+`)
+
+    if (0 < onesided.length) {
+      Content(`Where an entity declares only one of create and update there is nothing to
+dispatch on, and \`save$\` means that operation whether an id is present or not:
+
+`)
+      each(onesided, (e: any) => {
+        Content(`- \`${e.name}\`: \`save$\` always ${e.ops.includes('create') ? 'creates' : 'updates'}
+`)
+      })
+      Content(`
+`)
+    }
+
+    Content(`### Entity instances versus plain data
+
+Every SDK operation resolves to an SDK entity instance, never to raw data:
+\`list\` to a list of them, and each single-record operation to one. The record
+is absorbed into the instance and read back through \`.data()\`.${0 < removable.length ?
+      ` A removed\nentity is the same instance, marked deleted, still holding what it held.` : ''}
+
+Seneca's \`entize\` wants plain data, so the provider takes the \`.data()\` hop
+on everything the SDK hands back, before it goes anywhere near an entity. That
+is the whole of the \`plain\` helper in the source, and it is the only place in
+the plugin that knows the SDK deals in instances at all.
+
+The hop earns its keep for a second reason. An SDK instance carries its own
+serialisation marker, and that marker must not survive into a Seneca entity:
+Seneca reads \`entity$\` on a data object as the *canon*. A marker landing on
+that key would be taken as a canon, and the record would come back under the
+wrong one — or under none. The SDK namespaces its marker so the collision
+cannot happen by accident, but normalising at this boundary is still the right
+call. It is what makes the data plain, and it keeps the provider independent of
+whatever the SDK decides to carry alongside a record.
+
+`)
+
+    if (0 < loadable.length) {
+      Content(`### Missing things
+
+\`load$\` for an id that does not exist resolves to \`null\`. Only a 404 is
+translated this way; every other failure propagates.
+
+"This thing does not exist" is an ordinary answer to a lookup, not a failure of
+the lookup. It is usually a branch in the caller's logic, and forcing every call
+site into a \`try\`/\`catch\` to express that branch makes the common path noisy.
+A malformed request, a rejected credential or an unreachable server means
+something else entirely: the question could not be asked, and that should
+interrupt rather than quietly look like an empty result.
+
+The SDK does not draw this line — it throws for any non-2xx — so the provider
+asks the thrown error, which reports \`notFound\` and the HTTP \`status\` at the
+top level. That coupling to the SDK's error shape is a deliberate and narrow
+one, and it is why the shape is written down in the
+[reference](reference.md).
+
+`)
+
+      if (0 < removable.length) {
+        Content(`\`remove$\` is treated the same way and for the same reason: removing something
+that is already gone leaves the caller with what the caller wanted.
+
+`)
+      }
+    }
+    else if (0 < removable.length) {
+      Content(`### Missing things
+
+Nothing here reads a single record by id, but \`remove$\` still has to decide
+what "it was not there" means, and it treats a 404 as an ordinary outcome rather
+than a failure: the record is gone, which is what the caller asked for. Every
+other failure — a malformed request, a rejected credential, an unreachable
+server — means the question could not be asked at all, and propagates.
+
+The SDK does not draw that line; it throws for any non-2xx. So the provider asks
+the thrown error, which reports \`notFound\` and the HTTP \`status\` at the top
+level. That coupling to the SDK's error shape is a deliberate and narrow one,
+and it is why the shape is written down in the [reference](reference.md).
+
+`)
+    }
+
+    if (0 < nested.length) {
+      Content(`### Nesting
+
+${nestLead}
+Seneca's entity model is flat — a canon has no notion of a parent.
+
+The gap is bridged by putting the parent id in the query, which is why
+\`${n.parents[0]}\` is required on every \`${n.name}\` command${n.cmds.includes('load') ?
+        `, and why\n\`${n.name}\` \`load$\` takes an object rather than a bare id string` : ''}.
+This is inherited from the API's URL structure — \`${n.path}\` — rather than
+chosen here.
+
+The provider checks for \`${n.parents[0]}\` itself and throws a named error
+rather than letting the request go out. Without the check, the SDK builds a URL
+with a missing segment and the server answers 404${n.cmds.includes('load') ?
+        `, and that 404 is\nindistinguishable from "that ${n.name} does not exist" — which the provider\nwould then dutifully translate to \`null\`. A forgotten argument would look\nexactly like an empty result` :
+        ` — an opaque failure that says\nnothing about the argument that was left out`}. Failing early turns a confusing
+wrong answer into an obvious mistake.
+
+`)
+      if (1 < nested.length) {
+        Content(`The same applies to every nested entity here —
+${list(nested.map((e: any) => e.name))} — each guarded on its own keys.
+
+`)
+      }
+    }
+
+    Content(`### Query directives
+
+Seneca store queries can carry directives such as \`sort$\` and \`limit$\`.
+These are instructions to a *store*, and the API has no equivalent, so the
+provider strips any key ending in \`$\` before the query becomes an API match.
+
+Passing them through would be worse than dropping them: the SDK would forward
+them as ordinary match fields, and the API would either ignore them or reject
+the request outright. Dropping them is imperfect too — a caller who writes
+\`list$({ sort$: 'name' })\` gets unsorted results and no complaint — but it is
+the behaviour least likely to produce a wrong answer, and the limitation is
+documented rather than hidden. Sorting and limiting belong on the caller's
+side, or in the API's own query fields where it has them.
+
+
+`)
+
+    if (0 < writable.length) {
+      Content(`## Why writes are supported here
+
+The read-only question is worth asking of every provider, and the answer here
+follows from the API rather than from taste.
+
+Writes map cleanly onto entities only when the API's notion of "save" is
+unambiguous. For a CMS with draft states, localised fields and a separate
+publish step, \`save$\` would have to pick one interpretation and would mislead
+whoever guessed differently. Here the write operations are plain whole-record
+ones, so \`save$\` can mean exactly one thing for each of
+${list(writable.map((e: any) => e.name))}, and the store surface those
+operations support is implemented in full.
+
+One wrinkle does not map cleanly. Seneca's model lets a caller choose an id;
+many APIs assign ids themselves and ignore any id sent on create. The provider
+does not try to paper over that, because it cannot make a server honour an id
+it did not issue. Code that predicts the id of a record it is about to create
+will be wrong on such an API, and the remedy is to read the id back from what
+\`save$\` returns rather than to guess it beforehand.
+
+
+`)
+    }
+    else {
+      Content(`## Why this provider only reads
+
+Every entity here exposes reads alone. That is not a policy decision taken in
+the plugin: the cmd map is built from the operations the API declares, and none
+of these entities declares a create or an update. A \`save$\` that existed only
+to fail at the HTTP layer would be worse than no \`save$\` at all — the absence
+is the honest signal, and it appears in the entity table in the
+[reference](reference.md).
+
+If the API grows write operations, they arrive here by regeneration rather than
+by hand. Nothing about the mapping is waiting to be written.
+
+
+`)
+    }
+
+    Content(`## 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.
+
+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
+application should not depend on whether a particular service happens to need a
+key. An application that moves from an open endpoint to an authenticated
+deployment then changes one configuration value rather than restructuring how
+the plugin loads — and a provider that demanded a key from an API that has none
+would force every user to invent a fake one.
+
+
+## Depending on a published SDK
+
+The SDK is an ordinary published dependency: \`${provider.sdkPkg}\` at
+\`^${provider.sdkVersion}\`, resolved by npm like anything else.
+
+The alternative is vendoring — copying the generated client into this
+repository. That is tempting, since both artefacts come from the same model and
+change together. It is also wrong. It makes a second copy of something that is
+regenerated whenever the API moves, and it puts this plugin's release cycle in
+charge of the API's. As a dependency, the SDK carries its own semantic version:
+when the API changes, the SDK is versioned, and this plugin either follows the
+range or pins until it is ready. Keeping them separable also matters to the
+people who use the SDK with no Seneca anywhere in sight.
+
+One consequence of depending on generated code is worth stating plainly. The
+SDK is regenerated as the API model changes, so its surface can shift in ways a
+hand-written library's would not. That argues for keeping this plugin thin, and
+for pinning behaviour in tests. Everything this plugin knows about the SDK's
+shapes is concentrated in three small functions — the \`.data()\` hop, the query
+cleaner and the not-found translation — plus the construction of the client, so
+an SDK change is absorbed in one place and surfaces as a failing offline test
+rather than as a surprise in production.
+
+`)
+
+    if ('' === provider.liveBase) {
+      Content(`The API definition declares no server, so this plugin has no default host: the
+base URL arrives through the \`sdk.base\` option, supplied by whoever configures
+the plugin for a particular deployment. The tests therefore run entirely
+against the SDK's mock transport, which is the one host that is always
+available.
+
+
+`)
+    }
+    else {
+      Content(`The distinction that does survive is between the SDK and its **test server**.
+The SDK is published; the server is not, and ships only in
+[the SDK's source repository](${provider.sdkRepoUrl}). So the offline tests need
+nothing but \`npm install\`, while the live tests need a clone. That asymmetry
+is why the live tests probe for the server and skip rather than fail: the common
+case is a contributor who has the dependency but not the repository.
+
+
+`)
+    }
+
+    Content(`## A generated plugin
+
+Nothing in this repository is hand-written. The plugin source, its tests, its CI
+workflow, its manifest and these documents are all emitted by
+[@voxgig/sdkgen](https://github.com/voxgig/sdkgen) from the ${provider.api} API
+model — the same model the SDK is generated from, which is why the two cannot
+disagree about entity names, id fields, or which operations exist.
+
+There is one blunt consequence for anyone reading the code and reaching for an
+edit: the edit will not survive. The next generation run overwrites this
+repository, without a merge and without a warning. A fix applied here is a fix
+that has to be applied again, silently, forever.
+
+The source of truth is the SDK project's model — \`${provider.sdkrel}\` from
+here, if both are checked out — together with the sdkgen component that emits
+this target. A change to *what* the API offers belongs in the model; a change to
+*how* the provider expresses it belongs in the component. Both are versioned,
+both regenerate every provider built this way rather than just this one, and
+both are where a fix is worth making. See
+[Contributing](../README.md#contributing).
+
+
+## How the tests are arranged
+
+The suite runs offline by default. It needs no credentials and no network.
+
+The **offline** tests use the SDK's own mock transport, reached through this
+plugin's own options:
+
+\`\`\`js
+.use('${provider.pkgName}', {
+  test: true,
+  testopts: { entity: { ${subject.name}: { '${subject.name}0': { ... } } } },
+})
+\`\`\`
+
+This is better than the usual provider-testing compromise. Rather than checking
+only that the plugin loads and answers
+\`sys:provider,provider:${provider.lower},get:info\`, the tests exercise the
+entity commands themselves${coveredPhrase}
+through the real code path, from a Seneca entity call down to the transport and
+back. The only thing replaced is the socket. And because the mock belongs to the
+SDK, it stays honest as the SDK changes: a regeneration that alters a return
+shape breaks a test here rather than someone's production run.
+
+Seeding the mock is not decoration either. The seed is generated from the same
+model as the entities, so the records the tests read carry the fields the API
+would really return${0 < nested.length ? `, and a nested record's parent id
+names a parent record that exists — otherwise the nested tests would read an
+empty store and pass without proving anything` : ''}.
+
+`)
+
+    if ('' !== provider.liveBase) {
+      Content(`The **live** tests point at the companion server in the SDK repository and probe
+it before running, skipping with a stated reason when nothing answers. So a
+contributor who has just cloned this repository gets a meaningful result
+immediately, and a more thorough one after starting the server.
+
+Skipping is deliberate, and preferred over quietly returning early. An early
+\`return\` reports a test as *passed*, which makes an unconfigured checkout look
+as though it verified the integration when it verified nothing at all. A skip is
+honest about coverage, and the summary count shows how much did not run.
+
+`)
+
+      if (subject.cmds.includes('save') && subject.cmds.includes('remove')) {
+        Content(`The manual scripts in \`test/\` that write to a live server remove what they
+create, in a \`finally\` block, so the server is left as it was found. A run that
+leaks a record changes the result of the next one, which is how a suite becomes
+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
+
+  File({ name: 'README.md' }, () => {
+    Content(`# Documentation
+
+The documentation for \`${provider.pkgName}\` follows the
+[Diátaxis](https://diataxis.fr) framework. Each document serves one purpose,
+and that purpose decides what belongs in it. If you are unsure where to look,
+use the table below.
+
+| Document | Purpose | Read it when |
+| -------- | ------- | ------------ |
+| [Tutorial](tutorial.md) | Learning-oriented. A lesson that takes you from nothing to a working script. | You have never used this plugin and want to see it work. |
+| [How-to guides](how-to.md) | Task-oriented. Recipes that solve one problem each. | You know what you want to do and need the steps. |
+| [Reference](reference.md) | Information-oriented. A complete, factual description of the interface. | You need to look up a message pattern, entity field, or option. |
+| [Explanation](explanation.md) | Understanding-oriented. The reasoning behind the design. | You want to know *why* it works this way, or you are debugging something surprising. |
+
+## The distinction that matters most
+
+The tutorial and the how-to guides look alike — both are sequences of steps —
+but they are not interchangeable.
+
+The **tutorial** is a lesson. It is safe to follow, it produces a result you
+can see, and it asks you to make no decisions. Its job is to build confidence,
+so it deliberately avoids alternatives and edge cases.
+
+A **how-to guide** assumes competence. It answers "how do I list every record
+of a collection?", and it assumes you already have a working Seneca instance.
+Its job is to get a task done, so it omits the explanation.
+
+Likewise **reference** describes the machinery and nothing else — it never
+teaches. **Explanation** discusses and gives context — it never instructs.
+
+## These documents are generated
+
+This plugin, and this documentation with it, is generated by
+[@voxgig/sdkgen](https://github.com/voxgig/sdkgen) from the ${provider.api} API
+definition held in the [SDK project](${provider.sdkRepoUrl}). An edit made here
+is lost on the next regeneration.
+
+Something genuinely specific to this API — a quirk of its authentication, a
+rate limit worth warning about — belongs in the model the generator reads, not
+in the output it writes. Everything else belongs in the generator's own
+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
+
+  Folder({ name: 'doc' }, () => {
+    DocIndex({ provider })
+    DocTutorial({ provider })
+    DocHowto({ provider })
+    DocReference({ provider })
+    DocExplanation({ provider })
+  })
+})
+
+
+export {
+  Tests,
+  Scripts,
+  Workflow,
+  Readme,
+  Docs,
+}