@xemahq/create-biome 0.2.3 → 0.3.1

package/dist/lib/template-files.js

@@ -9,6 +9,13 @@ function pascalize(kebab) {
 function constCase(kebab) {
     return kebab.replaceAll('-', '_').toUpperCase();
 }
+function snakeCase(kebab) {
+    return kebab.replaceAll('-', '_');
+}
+const SAMPLE_RESOURCE = 'item';
+const SAMPLE_RESOURCE_PLURAL = 'items';
+const FEATURE_DIR = SAMPLE_RESOURCE_PLURAL;
+const FEATURE_MODULE_CLASS = 'ItemsModule';
 function serverBiomeRootFiles(ctx) {
     return {
         'README.md': `# ${ctx.displayName}
@@ -17,6 +24,24 @@ ${ctx.description}
 
 A first-party Xema **server biome** scaffolded by \`@xemahq/create-biome\`.
 
+## What you already have, without authoring anything
+
+| You wrote | You already have |
+|---|---|
+| \`@XemaResource('${SAMPLE_RESOURCE}')\` + four \`@XemaRoute\`s | four authorized, auditable, **agent-callable capabilities** — \`${ctx.biomeId}:${SAMPLE_RESOURCE}.{list,read,create,delete}@1\` — in the capability graph, with input/output schemas |
+| \`xema.capabilityDomain\` | the \`<domain>\` those refs are filed under |
+| a \`search-type\` contribution | a renderable search result-type with working deep links |
+| \`renderHints.routeTemplate\` | a real URL from chat and search into the detail page |
+
+**No capability descriptor is written anywhere in this biome, and none should
+be.** Rename the \`${SAMPLE_RESOURCE}\` resource and the refs follow; add a route
+and it projects; delete one and the projector prunes it. Reach for
+\`@XemaCapabilityHint\` to correct a derived value, and for a hand-authored
+\`@XemaCapability\` only when an operation genuinely needs a curated ref.
+
+Run \`pnpm test\` in \`api/${apiNameForBiome(ctx.biomeId)}/\` to see the exact
+capability set this biome projects.
+
 ## First steps
 
 \`\`\`sh
@@ -38,7 +63,9 @@ xema biome publish
   bootstrapped by \`XemaServiceModule.forBiome(...)\`.
 - \`skills/\` — Skill folder bundles (\`<slug>/SKILL.md\`) seeded into the agent runtime.
 - \`agents/\` — Agent definitions (\`<slug>.md\`); declare each in \`xema.agents[]\`.
-- \`contributions/\` — \`*.contribution.json\` envelopes (capabilities, etc.).
+- \`contributions/\` — \`*.contribution.json\` envelopes (capabilities, search
+  result-types, …). Ships a working \`${ctx.biomeId}.search-type.contribution.json\`
+  so this biome's content is renderable AND deep-linkable from search on day one.
 - \`workspace-manifests/\` — \`<slug>.workspace.yaml\` agent workspace manifests.
 
 ## In-tree monorepo development
@@ -73,7 +100,98 @@ be declared in \`xema-biome.json\` under \`xema.agents[]\` (\`slug\` + \`mode\`)
 boot-time cross-validator enforces parity between the manifest roster and the
 on-disk files. The \`agents/\` directory itself is discovered by on-disk presence.
 `,
-        'contributions/.gitkeep': '',
+        'contributions/README.md': `# Contributions
+
+Drop contribution envelopes here, one \`<slug>.<kind>.contribution.json\` per
+declaration. Every file has the SAME two-key envelope shape:
+
+\`\`\`json
+{ "kind": "<contribution-kind>", "manifest": { /* kind-specific manifest */ } }
+\`\`\`
+
+The file-name suffix and the \`kind\` field MUST agree — a mismatch fails the
+biome's contribution sync at boot with the offending path. Provenance
+(\`biome.id\` / \`biome.version\`) is NEVER declared inline: it is stamped from
+\`xema-biome.json\` by the discovering host.
+
+Every manifest is validated fail-fast against its kernel Zod schema at
+biome-discovery time, so a malformed contribution never reaches a registry.
+
+## What ships here already
+
+- \`${ctx.biomeId}.search-type.contribution.json\` — the search RESULT-TYPE for
+  this biome's primary entity. It declares the \`(objectKind, docType)\` facet,
+  the render/route hints the generic search UI reads, the searchable-field set,
+  and the result-level authz mapping. Edit it to match your real entity; delete
+  it only if this biome indexes nothing.
+
+## \`renderHints.routeTemplate\`
+
+The route template turns a search hit into a real URL. Its placeholder
+vocabulary is the CLOSED \`SearchRouteTemplateVariable\` set, split by WHO
+supplies each value:
+
+\`\`\`
+platform-derived (always available, never declared):
+  orgId · projectId · docType · objectKind · sourceId · title
+projected (YOU supply: declare in renderHints.routeParams AND stamp on
+IndexableDocument.routeParams):
+  slug · containerSlug
+\`\`\`
+
+\`slug\` is your entity's own URL slug; \`containerSlug\` is the slug of the
+collection a nested route puts it under (e.g. a knowledge space). Use them when
+your frontend route is slug-addressed rather than id-addressed:
+
+\`\`\`json
+"renderHints": {
+  "routeTemplate": "/spaces/projects/{projectId}/docs/{containerSlug}/{slug}",
+  "routeParams": ["containerSlug", "slug"]
+}
+\`\`\`
+
+A template must be a site-relative path (leading \`/\`, no whitespace, no \`//\`)
+and may reference nothing else. Validation is fail-fast at parse time: an
+unknown placeholder is rejected, a PROJECTED placeholder you did not declare in
+\`routeParams\` is rejected (it could never expand), and a \`routeParams\` entry
+the template never references is rejected as a dead declaration. At expansion
+time a placeholder with no value yields NO url rather than a half-substituted,
+broken link.
+
+Point \`routeTemplate\` at the per-INSTANCE detail route whenever your biome has
+one. When it genuinely has none, the biome's own registered surface (its list
+page) is a better link than none — but NEVER invent a query parameter your UI
+does not actually read: that produces a live-looking URL that silently ignores
+the result the user clicked.
+`,
+        [`contributions/${ctx.biomeId}.search-type.contribution.json`]: `${JSON.stringify({
+            $comment: `Search RESULT-TYPE for this biome's primary entity — replace the placeholder ` +
+                `values with your real ones. \`objectKind\` must be a XemaObjectKind member; use ` +
+                `the kind your entity IS, or the closest one when it has no kernel kind (docType ` +
+                `is the real discriminator, and the natural key is the (objectKind, docType) pair). ` +
+                `\`searchableFields\` must match the fields your producer actually projects onto the ` +
+                `IndexableDocument. \`routeTemplate\` resolves to the deeplink-only detail page the ` +
+                `paired web biome ships (\`navHidden: true\`, slug '${ctx.biomeId}/:id'), so the link ` +
+                `works on day one — if you scaffolded WITHOUT a web surface, add that route before ` +
+                `keeping this field, and drop it entirely rather than pointing it at a list page. ` +
+                `\`embeddingEligibleDefault\` is false: semantic embedding is opt-in, never inferred.`,
+            kind: 'search-type',
+            manifest: {
+                objectKind: 'artifact',
+                docType: `${snakeCase(ctx.biomeId)}_item`,
+                renderHints: {
+                    label: ctx.displayName,
+                    icon: 'layout-grid',
+                    routeTemplate: `/spaces/projects/{projectId}/${ctx.biomeId}/{sourceId}`,
+                },
+                searchableFields: ['title', 'content', 'tags'],
+                embeddingEligibleDefault: false,
+                authz: {
+                    resourceType: `${snakeCase(ctx.biomeId)}_item`,
+                    defaultVisibility: 'org-shared',
+                },
+            },
+        }, null, 2)}\n`,
         'workspace-manifests/README.md': `# Workspace manifests
 
 Drop agent workspace manifests here, one \`<slug>.workspace.yaml\` per agent
@@ -85,10 +203,6 @@ function serverApiFiles(ctx) {
     const apiName = apiNameForBiome(ctx.biomeId);
     const apiDir = `api/${apiName}`;
     const constName = `${constCase(apiName)}_BOOTSTRAP`;
-    const pascal = pascalize(ctx.biomeId);
-    const featureModule = `${pascal}Module`;
-    const featureController = `${pascal}Controller`;
-    const featureService = `${pascal}Service`;
     return {
         [`${apiDir}/package.json`]: `${JSON.stringify({
             name: apiName,
@@ -103,6 +217,7 @@ function serverApiFiles(ctx) {
                 lint: 'eslint "src/**/*.ts"',
                 'lint:fix': 'eslint "src/**/*.ts" --fix',
                 typecheck: 'tsc --noEmit',
+                test: 'nest build && node --test "test/*.test.mjs"',
                 openapi: 'NODE_PATH=node_modules xema-openapi',
                 'client:generate': 'xema-client-generate',
             },
@@ -176,20 +291,24 @@ function serverApiFiles(ctx) {
                 ],
             },
         }, null, 2)}\n`,
+        [`${apiDir}/eslint.config.mjs`]: ESLINT_CONFIG,
         [`${apiDir}/.gitignore`]: `node_modules
 dist
 .turbo
 openapi.*.json
 `,
+        [`${apiDir}/test/manifest.test.mjs`]: renderManifestTest(ctx),
+        [`${apiDir}/test/capabilities.test.mjs`]: renderCapabilitiesTest(ctx, apiName),
         [`${apiDir}/src/generated/${apiName}.bootstrap.generated.ts`]: renderBootstrapPlaceholder(apiName, constName, `${ctx.displayName} API`, ctx.biomeId),
         [`${apiDir}/src/main.ts`]: renderMainTs(apiName, ctx),
-        [`${apiDir}/src/app.module.ts`]: renderAppModule(apiName, constName, featureModule),
+        [`${apiDir}/src/app.module.ts`]: renderAppModule(apiName, constName),
         [`${apiDir}/src/config/index.ts`]: renderConfigIndex(),
         [`${apiDir}/src/health/health.module.ts`]: HEALTH_MODULE,
         [`${apiDir}/src/health/health.controller.ts`]: HEALTH_CONTROLLER,
-        [`${apiDir}/src/${ctx.biomeId}/${ctx.biomeId}.module.ts`]: renderFeatureModule(ctx.biomeId, featureModule, featureController, featureService),
-        [`${apiDir}/src/${ctx.biomeId}/${ctx.biomeId}.controller.ts`]: renderFeatureController(ctx.biomeId, featureController, featureService),
-        [`${apiDir}/src/${ctx.biomeId}/${ctx.biomeId}.service.ts`]: renderFeatureService(ctx.biomeId, featureService),
+        [`${apiDir}/src/${FEATURE_DIR}/${FEATURE_DIR}.module.ts`]: renderFeatureModule(),
+        [`${apiDir}/src/${FEATURE_DIR}/${FEATURE_DIR}.controller.ts`]: renderFeatureController(ctx),
+        [`${apiDir}/src/${FEATURE_DIR}/${FEATURE_DIR}.service.ts`]: renderFeatureService(),
+        [`${apiDir}/src/${FEATURE_DIR}/dto/${SAMPLE_RESOURCE}.dto.ts`]: renderItemDto(),
     };
 }
 function renderBootstrapPlaceholder(apiName, constName, displayName, biomeId) {
@@ -213,6 +332,9 @@ export const ${constName}: BiomeServiceDescriptor = {
   displayName: '${displayName}',
   requiresServices: ['identity-api'],
   exposesCapabilities: [],
+  biomeId: '${biomeId}',
+  biomeVersion: '0.1.0',
+  capabilityDomain: '${biomeId}',
 };
 `;
 }
@@ -235,11 +357,9 @@ void bootstrapXemaService({
 });
 `;
 }
-function renderAppModule(apiName, constName, featureModule) {
-    const featureFile = featureModule
-        .replace(/Module$/, '')
-        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-        .toLowerCase();
+function renderAppModule(apiName, constName) {
+    const featureFile = FEATURE_DIR;
+    const featureModule = FEATURE_MODULE_CLASS;
     return `import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import { APP_INTERCEPTOR } from '@nestjs/core';
@@ -269,6 +389,44 @@ import { ${featureModule} } from './${featureFile}/${featureFile}.module';
 export class AppModule {}
 `;
 }
+const ESLINT_CONFIG = `import eslint from '@eslint/js';
+import prettierConfig from 'eslint-config-prettier';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  { ignores: ['dist/', 'node_modules/', 'src/generated/', 'test/', 'eslint.config.mjs'] },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  prettierConfig,
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-misused-promises': 'error',
+      '@typescript-eslint/await-thenable': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/consistent-type-imports': [
+        'error',
+        { prefer: 'type-imports', fixStyle: 'separate-type-imports' },
+      ],
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrors: 'all' },
+      ],
+      eqeqeq: ['error', 'always'],
+      curly: ['error', 'all'],
+      'no-console': ['error', { allow: ['warn', 'error'] }],
+      'no-duplicate-imports': 'error',
+    },
+  },
+);
+`;
 function renderConfigIndex() {
     return `import { registerAs } from '@nestjs/config';
 
@@ -292,88 +450,358 @@ import { HealthController } from './health.controller';
 export class HealthModule {}
 `;
 const HEALTH_CONTROLLER = `import { Controller, Get } from '@nestjs/common';
-import { XemaPublicRoute } from '@xemahq/xema-decorators';
+import { PublicRouteReason, XemaPublicRoute } from '@xemahq/xema-decorators';
 
+/**
+ * Probe endpoints. \`@XemaPublicRoute\` requires a closed-domain \`reason\` —
+ * public-by-default is not expressible, so every unauthenticated route says
+ * why it is one. These are also the only routes in the service that project no
+ * capability: a public probe is not an agent-callable operation.
+ */
 @Controller('health')
 export class HealthController {
   @Get('live')
-  @XemaPublicRoute()
+  @XemaPublicRoute({ reason: PublicRouteReason.K8sProbe })
   live(): { status: 'ok' } {
     return { status: 'ok' };
   }
 
   @Get('ready')
-  @XemaPublicRoute()
+  @XemaPublicRoute({ reason: PublicRouteReason.K8sProbe })
   ready(): { status: 'ok' } {
     return { status: 'ok' };
   }
 }
 `;
-function renderFeatureModule(biomeId, featureModule, featureController, featureService) {
-    const file = biomeId;
+function renderFeatureModule() {
     return `import { Module } from '@nestjs/common';
 
-import { ${featureController} } from './${file}.controller';
-import { ${featureService} } from './${file}.service';
+import { ItemsController } from './items.controller';
+import { ItemsService } from './items.service';
 
 @Module({
-  controllers: [${featureController}],
-  providers: [${featureService}],
+  controllers: [ItemsController],
+  providers: [ItemsService],
 })
-export class ${featureModule} {}
+export class ${FEATURE_MODULE_CLASS} {}
 `;
 }
-function renderFeatureController(biomeId, featureController, featureService) {
-    const file = biomeId;
-    const serviceVar = camelize(biomeId);
-    return `import { Controller, Get } from '@nestjs/common';
-import { ApiOkResponse, ApiTags } from '@nestjs/swagger';
-import { XemaRoute } from '@xemahq/xema-decorators';
-
-import { ${featureService} } from './${file}.service';
-import { ${pascalizeForDto(biomeId)}StatusDto } from './${file}.service';
-
-@ApiTags('${biomeId}')
-@Controller('${biomeId}')
-export class ${featureController} {
-  constructor(private readonly ${serviceVar}Service: ${featureService}) {}
-
-  @Get('status')
-  @XemaRoute()
-  @ApiOkResponse({ type: ${pascalizeForDto(biomeId)}StatusDto })
-  status(): ${pascalizeForDto(biomeId)}StatusDto {
-    return this.${serviceVar}Service.status();
+function renderFeatureController(ctx) {
+    return `import { Body, Controller, Delete, Get, Param, Post } from '@nestjs/common';
+import {
+  ApiCreatedResponse,
+  ApiNoContentResponse,
+  ApiOkResponse,
+  ApiTags,
+} from '@nestjs/swagger';
+import {
+  ApiSurface,
+  XemaApiSurface,
+  XemaCapabilityHint,
+  XemaResource,
+  XemaRoute,
+} from '@xemahq/xema-decorators';
+
+import { CreateItemDto, ItemDto } from './dto/item.dto';
+import { ItemsService } from './items.service';
+
+/**
+ * Resource controller for the \`${SAMPLE_RESOURCE}\` noun this biome owns.
+ *
+ * \`@XemaResource\` + \`@XemaRoute\` are the ONLY declarations needed to get
+ * capabilities: at boot, \`XemaServiceModule.forBiome\` stamps every public
+ * operation with \`x-xema-resource\` / \`x-xema-action\`, and the HTTP capability
+ * projector derives one capability per operation —
+ * \`<capabilityDomain>:<resource>.<verb>@1\` — registers it, and prunes any it
+ * no longer produces. The refs this file yields (domain \`${ctx.biomeId}\`, from
+ * \`xema.capabilityDomain\`):
+ *
+ *   ${ctx.biomeId}:${SAMPLE_RESOURCE}.list@1     risk low
+ *   ${ctx.biomeId}:${SAMPLE_RESOURCE}.read@1     risk low
+ *   ${ctx.biomeId}:${SAMPLE_RESOURCE}.create@1   risk medium
+ *   ${ctx.biomeId}:${SAMPLE_RESOURCE}.delete@1   risk high, requires approval
+ *
+ * Risk tiers come from the DECLARED verb→risk table, not a heuristic; an
+ * unrecognised verb resolves to \`high\` (never low), which over-gates visibly
+ * instead of silently un-gating. \`test/capabilities.test.mjs\` asserts this
+ * exact set, so adding or renaming a route without updating the expectation
+ * fails the build rather than quietly changing the biome's public surface.
+ */
+@ApiTags('${SAMPLE_RESOURCE_PLURAL}')
+// The surface is the "which generated client, and is this agent-reachable?"
+// axis, and it is REQUIRED: a route with no surface is unclassified, and the
+// projector only ever derives from \`ApiSurface.Public\`. There is no default —
+// a silently-private route that an author believed was public would be the
+// worst kind of quiet failure.
+@XemaApiSurface(ApiSurface.Public)
+@XemaResource('${SAMPLE_RESOURCE}')
+@Controller('${SAMPLE_RESOURCE_PLURAL}')
+export class ItemsController {
+  constructor(private readonly itemsService: ItemsService) {}
+
+  @Get()
+  @XemaRoute({ action: 'list' })
+  @ApiOkResponse({ type: ItemDto, isArray: true })
+  list(): ItemDto[] {
+    return this.itemsService.list();
+  }
+
+  @Get(':itemId')
+  @XemaRoute({ action: 'read' })
+  @ApiOkResponse({ type: ItemDto })
+  read(@Param('itemId') itemId: string): ItemDto {
+    return this.itemsService.read(itemId);
+  }
+
+  @Post()
+  @XemaRoute({ action: 'create' })
+  // The ONE knob for correcting a derived value. \`riskTier\` and
+  // \`requiresApproval\` are the other two; each defaults from the verb table,
+  // and the summary defaults to the OpenAPI description. Override only what is
+  // actually wrong — a hand-authored \`@XemaCapability\` always beats both, and
+  // is reserved for the rare operation that needs a curated v2 ref.
+  @XemaCapabilityHint({
+    summary:
+      'Create one ${SAMPLE_RESOURCE} in this biome. Prefer this over editing storage directly: it is the audited, authorized write path.',
+  })
+  @ApiCreatedResponse({ type: ItemDto })
+  create(@Body() dto: CreateItemDto): ItemDto {
+    return this.itemsService.create(dto);
+  }
+
+  @Delete(':itemId')
+  @XemaRoute({ action: 'delete' })
+  @ApiNoContentResponse()
+  remove(@Param('itemId') itemId: string): void {
+    this.itemsService.remove(itemId);
   }
 }
 `;
 }
-function pascalizeForDto(biomeId) {
-    return pascalize(biomeId);
-}
-function renderFeatureService(biomeId, featureService) {
-    const pascal = pascalize(biomeId);
-    return `import { Injectable } from '@nestjs/common';
-import { ApiProperty } from '@nestjs/swagger';
+function renderItemDto() {
+    return `import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
 
-/** Sample response DTO — replace with the biome's real domain types. */
-export class ${pascal}StatusDto {
-  @ApiProperty({ example: '${biomeId}' })
-  biome!: string;
+/**
+ * Sample domain type — replace with the biome's real one. The DTO is not
+ * decoration: the capability projector derives each capability's input and
+ * output JSON Schema from the OpenAPI operation, so an untyped body produces a
+ * capability an agent cannot call correctly.
+ */
+export class ItemDto {
+  @ApiProperty({ description: 'Stable identifier of the ${SAMPLE_RESOURCE}.' })
+  id!: string;
+
+  @ApiProperty({ description: 'Human-readable title.' })
+  title!: string;
+}
 
-  @ApiProperty({ example: 'ok' })
-  status!: string;
+export class CreateItemDto {
+  @ApiProperty({ description: 'Human-readable title.', maxLength: 200 })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(200)
+  title!: string;
 }
+`;
+}
+function renderFeatureService() {
+    return `import { Injectable, NotFoundException } from '@nestjs/common';
 
+import { CreateItemDto, ItemDto } from './dto/item.dto';
+
+/**
+ * Sample in-memory store — replace with the biome's real persistence. Kept
+ * deliberately trivial so a freshly-scaffolded biome builds and tests with no
+ * database: the scaffold's job is to prove the capability/render/deep-link
+ * wiring, not to pick a storage engine for you.
+ */
 @Injectable()
-export class ${featureService} {
-  status(): ${pascal}StatusDto {
-    return { biome: '${biomeId}', status: 'ok' };
+export class ItemsService {
+  private readonly items = new Map<string, ItemDto>();
+  private nextId = 1;
+
+  list(): ItemDto[] {
+    return [...this.items.values()];
+  }
+
+  read(itemId: string): ItemDto {
+    const found = this.items.get(itemId);
+    if (found === undefined) {
+      throw new NotFoundException(\`${SAMPLE_RESOURCE} "\${itemId}" not found\`);
+    }
+    return found;
+  }
+
+  create(dto: CreateItemDto): ItemDto {
+    const id = String(this.nextId);
+    this.nextId += 1;
+    const created: ItemDto = { id, title: dto.title };
+    this.items.set(id, created);
+    return created;
+  }
+
+  remove(itemId: string): void {
+    if (!this.items.delete(itemId)) {
+      throw new NotFoundException(\`${SAMPLE_RESOURCE} "\${itemId}" not found\`);
+    }
   }
 }
 `;
 }
+function renderManifestTest(ctx) {
+    return `import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { BiomeManifestSchema } from '@xemahq/kernel-contracts/biome';
+import {
+  SearchTypeContributionManifestSchema,
+  assertValidSearchRouteTemplate,
+} from '@xemahq/kernel-contracts/search';
+
+// test/ -> api/<api>/ -> api/ -> biome root
+const BIOME_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+const readJson = (rel) => JSON.parse(readFileSync(join(BIOME_ROOT, rel), 'utf8'));
+
+test('xema-biome.json validates against the kernel BiomeManifestSchema', () => {
+  const result = BiomeManifestSchema.safeParse(readJson('xema-biome.json'));
+  assert.equal(
+    result.success,
+    true,
+    result.success ? '' : JSON.stringify(result.error.issues, null, 2),
+  );
+});
+
+test('the manifest declares the capability domain its routes project into', () => {
+  const manifest = readJson('xema-biome.json');
+  // Without a declared domain the projector falls back to xema.id, which is
+  // correct but invisible. Declaring it keeps the capability vocabulary a
+  // one-line edit instead of a documentation hunt.
+  assert.equal(manifest.xema.capabilityDomain, '${ctx.biomeId}');
+});
+
+test('the search-type contribution validates and its routeTemplate is well-formed', () => {
+  const envelope = readJson('contributions/${ctx.biomeId}.search-type.contribution.json');
+  assert.equal(envelope.kind, 'search-type');
+
+  const result = SearchTypeContributionManifestSchema.safeParse(envelope.manifest);
+  assert.equal(
+    result.success,
+    true,
+    result.success ? '' : JSON.stringify(result.error.issues, null, 2),
+  );
+
+  // A deep link that only LOOKS clickable is worse than none: every
+  // placeholder must come from the closed SearchRouteTemplateVariable set.
+  assertValidSearchRouteTemplate(envelope.manifest.renderHints.routeTemplate);
+});
+`;
+}
+function renderCapabilitiesTest(ctx, apiName) {
+    return `import 'reflect-metadata';
+
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { after, before, test } from 'node:test';
+
+// Loaded through \`createRequire\`, not \`import\`: \`nest build\` emits CommonJS,
+// and a decorated class's exports are not statically analysable, so an ESM
+// named import of the compiled module fails. Requiring the framework packages
+// the same way also guarantees the test and the compiled controller share ONE
+// instance of Nest — two would mean two metadata registries and an empty scan.
+const require = createRequire(import.meta.url);
+
+const { DiscoveryService, MetadataScanner, ModulesContainer, NestFactory } = require('@nestjs/core');
+const { DocumentBuilder, SwaggerModule } = require('@nestjs/swagger');
+const { scanApiSurfaces, stampRouteExtensions } = require('@xemahq/xema-decorators');
+const { deriveHttpCapabilities } = require('@xemahq/xema-service-nest');
+
+const { ItemsModule } = require('../dist/${FEATURE_DIR}/${FEATURE_DIR}.module.js');
+
+/**
+ * The capabilities this biome MUST project, and the risk tier each derives.
+ * Hand-maintained on purpose: this is the assertion, not the derivation. Change
+ * a route and this list must change with it — deliberately, and in review.
+ */
+const EXPECTED = {
+  '${ctx.biomeId}:${SAMPLE_RESOURCE}.list@1': { riskTier: 'low', requiresApproval: false },
+  '${ctx.biomeId}:${SAMPLE_RESOURCE}.read@1': { riskTier: 'low', requiresApproval: false },
+  '${ctx.biomeId}:${SAMPLE_RESOURCE}.create@1': { riskTier: 'medium', requiresApproval: false },
+  '${ctx.biomeId}:${SAMPLE_RESOURCE}.delete@1': { riskTier: 'high', requiresApproval: true },
+};
+
+let derivation;
+let app;
+
+before(async () => {
+  // The feature module ALONE — no XemaServiceModule, so no registry, no
+  // identity bootstrap, no network. Capability derivation reads decorator
+  // metadata and the OpenAPI document; neither needs a booted platform.
+  app = await NestFactory.create(ItemsModule, { logger: false });
+  const doc = SwaggerModule.createDocument(
+    app,
+    new DocumentBuilder().setTitle('${apiName}').setVersion('0.1.0').build(),
+    { operationIdFactory: (controllerKey, methodKey) => \`\${controllerKey}_\${methodKey}\` },
+  );
+  const scan = scanApiSurfaces(
+    new DiscoveryService(app.get(ModulesContainer, { strict: false })),
+    new MetadataScanner(),
+  );
+  stampRouteExtensions(doc, scan.projections);
+
+  derivation = deriveHttpCapabilities({
+    doc,
+    serviceName: '${apiName}',
+    domain: '${ctx.biomeId}',
+    biomeId: '${ctx.biomeId}',
+    biomeVersion: '0.1.0',
+    sourceKey: 'http-operations',
+    authoredRefs: new Set(),
+  });
+});
+
+after(async () => {
+  await app?.close();
+});
+
+test('every route projects a capability — none authored by hand', () => {
+  const derived = [...derivation.capabilities.keys()].sort();
+  assert.deepEqual(derived, Object.keys(EXPECTED).sort());
+});
+
+test('risk tier and approval gating are derived from the declared verb table', () => {
+  for (const [ref, expected] of Object.entries(EXPECTED)) {
+    const capability = derivation.capabilities.get(ref);
+    assert.ok(capability, \`missing capability \${ref}\`);
+    assert.equal(capability.riskTier, expected.riskTier, ref);
+    assert.equal(capability.requiresApproval, expected.requiresApproval, ref);
+  }
+});
+
+test('each capability carries an invocation binding and IO schemas', () => {
+  for (const ref of Object.keys(EXPECTED)) {
+    const capability = derivation.capabilities.get(ref);
+    // Without a binding the ref is registered but unroutable — an agent could
+    // discover it and never call it.
+    assert.ok(capability.invocation, \`\${ref} has no invocation binding\`);
+    assert.equal(capability.provenance.biomeId, '${ctx.biomeId}');
+    assert.ok(capability.inputSchema, \`\${ref} has no input schema\`);
+  }
+});
+
+test('the @XemaCapabilityHint summary wins over the derived one', () => {
+  const created = derivation.capabilities.get('${ctx.biomeId}:${SAMPLE_RESOURCE}.create@1');
+  assert.match(created.summary, /audited, authorized write path/);
+});
+`;
+}
 export function webBiomeFiles(ctx) {
     const pageComponent = `${pascalize(ctx.biomeId)}Page`;
+    const detailComponent = `${pascalize(ctx.biomeId)}DetailPage`;
     const navId = ctx.biomeId;
     return {
         'package.json': `${JSON.stringify({
@@ -408,8 +836,9 @@ export function webBiomeFiles(ctx) {
             },
         }, null, 2)}\n`,
         'tsconfig.json': WEB_TSCONFIG,
-        'src/index.tsx': renderWebIndex(ctx, pageComponent, navId),
+        'src/index.tsx': renderWebIndex(ctx, pageComponent, detailComponent, navId),
         [`src/pages/${pageComponent}.tsx`]: renderWebPage(ctx, pageComponent),
+        [`src/pages/${detailComponent}.tsx`]: renderWebDetailPage(ctx, detailComponent),
     };
 }
 const WEB_TSCONFIG = `{
@@ -440,7 +869,7 @@ const WEB_TSCONFIG = `{
   "include": ["src/**/*.ts", "src/**/*.tsx"]
 }
 `;
-function renderWebIndex(ctx, pageComponent, navId) {
+function renderWebIndex(ctx, pageComponent, detailComponent, navId) {
     return `import { defineWebBiome } from '@xemahq/ui-kernel';
 import { LayoutGrid } from 'lucide-react';
 
@@ -472,12 +901,66 @@ const ${camelize(ctx.webBiomeId)}Biome = defineWebBiome({
       scope: 'project',
       load: () => import('./pages/${pageComponent}'),
     },
+    {
+      // Deeplink-only detail route. This is the LANDING TARGET of the server
+      // biome's search-type \`renderHints.routeTemplate\`
+      // (\`/spaces/projects/{projectId}/${navId}/{sourceId}\`) — without it the
+      // template would expand to a real-looking URL that 404s, which is worse
+      // than shipping no deep link at all. \`navHidden\` keeps it out of the
+      // menu: it is reachable from search and from chat, never browsed to.
+      slug: '${navId}/:id',
+      label: '${ctx.navLabel} detail',
+      icon: LayoutGrid,
+      category: 'build',
+      scope: 'project',
+      navHidden: true,
+      load: () => import('./pages/${detailComponent}'),
+    },
   ],
 });
 
 export default ${camelize(ctx.webBiomeId)}Biome;
 `;
 }
+function renderWebDetailPage(ctx, detailComponent) {
+    return `import { useBiomeRouteParams } from '@/lib/biomes/biome-host-next';
+
+/**
+ * Deeplink-only detail page for one \`${ctx.biomeId}\` record.
+ *
+ * Reached by expanding the search-type contribution's \`routeTemplate\`, whose
+ * \`{sourceId}\` placeholder binds to the \`:id\` segment declared on this page's
+ * slug. Both sides name the same closed vocabulary, so a search hit, a chat
+ * citation and a manual URL all land here.
+ */
+export default function ${detailComponent}(): JSX.Element {
+  const { projectId, id } = useBiomeRouteParams<{
+    projectId?: string;
+    id?: string;
+  }>();
+
+  return (
+    <div className="p-6">
+      <h1 className="text-xl font-semibold">${ctx.navLabel} detail</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        Replace this with the real record view — fetch by id from the biome's
+        API and render it.
+      </p>
+      <dl className="mt-4 text-sm">
+        <dt className="font-medium">Record id</dt>
+        <dd>
+          <code>{id ?? '(missing — this route requires an id)'}</code>
+        </dd>
+        <dt className="mt-2 font-medium">Project scope</dt>
+        <dd>
+          <code>{projectId ?? '(none — open from a project)'}</code>
+        </dd>
+      </dl>
+    </div>
+  );
+}
+`;
+}
 function renderWebPage(ctx, pageComponent) {
     return `import { useBiomeRouteParams } from '@/lib/biomes/biome-host-next';
 
@@ -505,6 +988,425 @@ export default function ${pageComponent}(): JSX.Element {
 }
 `;
 }
+export function connectorBiomeFiles(ctx) {
+    const providerKey = ctx.biomeId.replace(/^connector-/, '');
+    const connectorKey = providerKey.replaceAll('-', '_').toUpperCase();
+    const camel = camelize(providerKey);
+    return {
+        'README.md': renderConnectorReadme(ctx, providerKey, connectorKey),
+        'package.json': `${JSON.stringify({
+            name: `@xemahq/biomes-${ctx.biomeId}`,
+            version: '0.1.0',
+            description: ctx.description,
+            license: 'LicenseRef-Xema-BSL-1.1',
+            private: true,
+            type: 'module',
+            main: 'dist/connector-adapters/index.js',
+            files: ['dist', 'xema-biome.json'],
+            exports: {
+                './connector-adapters': {
+                    types: './dist/connector-adapters/index.d.ts',
+                    default: './dist/connector-adapters/index.js',
+                },
+                './package.json': './package.json',
+            },
+            scripts: {
+                clean: 'rm -rf dist',
+                build: 'tsc -p tsconfig.json',
+                typecheck: 'tsc --noEmit',
+                format: 'prettier --write "src/**/*.ts"',
+                test: 'tsc -p tsconfig.json && node --test "tests/*.test.mjs"',
+            },
+            dependencies: {
+                '@xemahq/biome-sdk': 'catalog:',
+                '@xemahq/kernel-contracts': 'catalog:',
+            },
+            devDependencies: {
+                '@types/node': 'catalog:',
+                prettier: 'catalog:',
+                typescript: 'catalog:',
+            },
+        }, null, 2)}\n`,
+        'tsconfig.json': `${JSON.stringify({
+            extends: '../../tsconfig.base.json',
+            compilerOptions: {
+                outDir: 'dist',
+                rootDir: 'src',
+                module: 'ESNext',
+                moduleResolution: 'Bundler',
+            },
+            include: ['src/**/*.ts'],
+            exclude: ['node_modules', 'dist'],
+        }, null, 2)}\n`,
+        '.gitignore': `node_modules
+dist
+.turbo
+`,
+        'src/connector-adapters/index.ts': renderConnectorAdapter(ctx, providerKey, connectorKey, camel),
+        'tests/provider.test.mjs': renderConnectorTest(ctx, providerKey, connectorKey, camel),
+    };
+}
+function renderConnectorReadme(ctx, providerKey, connectorKey) {
+    return `# ${ctx.displayName}
+
+${ctx.description}
+
+A Xema **connector biome** scaffolded by \`@xemahq/create-biome\`.
+
+## What you already have, without authoring anything
+
+One \`ConnectorAdapterModule\` — the descriptors, the webhook verifier, the event
+mapper, the deterministic idempotency extractor and the onboarding manifest — is
+the ONLY thing this biome declares. From it the platform derives:
+
+- **connector capabilities**, filed under the \`${ctx.biomeId}\` domain;
+- the **connection-setup flow**, rendered from \`onboarding.fields\` (no bespoke UI);
+- **credential custody** — the secret is sealed by the credential broker and
+  resolved at use; this biome never reads or stores it;
+- **OAuth**, when the provider declares \`appAuthKind\` other than \`none\` plus its
+  authorize/token endpoints;
+- **preflight**, from the declared credential kind + scopes.
+
+You never write a capability descriptor, a connect dialog, or a token store.
+
+## Constraints (CI-enforced)
+
+\`tooling/boundaries/check-connector-biome.mjs\` requires a \`kind: "connector"\`
+biome to contribute ≥1 \`connector-adapter\`, to ship **no** product surface (no
+web target, no pages, no BFF), and to depend on or extend **no** other biome —
+so any app can reuse it. The scaffold satisfies all three; keep it that way.
+
+## Make it real
+
+1. Replace the \`${providerKey}\` provider/connector descriptors with the real
+   provider's identity, category, auth kind and scopes.
+2. Replace the verifier with the provider's ACTUAL signature scheme, and compare
+   in constant time. Never accept an unverified delivery.
+3. Replace the event mapper: return \`ok(null)\` for events you deliberately drop,
+   and \`err(adapterError('malformed-payload', …))\` for ones that are broken.
+   Never forward a fabricated envelope.
+4. Keep the idempotency key DETERMINISTIC — the provider's delivery id, or a
+   hash of the canonical body. Never time-based, never random.
+5. Declare every credential field the provider needs in \`onboarding.fields\`;
+   that list IS the connect form.
+
+\`\`\`sh
+pnpm build && pnpm test
+\`\`\`
+
+The connector wire key is \`${connectorKey}\`.
+`;
+}
+function renderConnectorAdapter(ctx, providerKey, connectorKey, camel) {
+    const constPrefix = constCase(providerKey);
+    return `import { createHash, timingSafeEqual } from 'node:crypto';
+
+import {
+  adapterError,
+  defineConnectorAdapter,
+  err,
+  ok,
+  type ConnectorAdapterModule,
+  type EventMapper,
+  type IdempotencyKeyExtractor,
+  type MappedEnvelope,
+  type WebhookVerifier,
+} from '@xemahq/biome-sdk/adapter';
+import {
+  ConnectorOnboardingKind,
+  CredentialFieldTransform,
+  CredentialFieldType,
+  CredentialKind,
+  ProviderAppAuthKind,
+  ProviderOrigin,
+  type ConnectorDescriptor,
+  type ProviderDescriptor,
+  type ProviderOnboardingManifest,
+} from '@xemahq/kernel-contracts/connector';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ${ctx.displayName} — ConnectorAdapterModule
+//
+// This module is the WHOLE biome. Everything a connector gets for free —
+// capabilities, the connect flow, credential custody, OAuth, preflight — is
+// derived from the declarations below. There is no capability descriptor to
+// write and no webhook route to mount: inbound deliveries terminate at the
+// single connector-gateway ingress edge, which routes them here by
+// \`provider\`.
+//
+// Replace every placeholder marked TODO with the real provider's behaviour.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Provider slug — the key the ingress edge routes deliveries by. */
+export const ${constPrefix}_PROVIDER_KEY = '${providerKey}';
+
+/** Human-readable provider name, shared by onboarding + both descriptors. */
+const ${constPrefix}_DISPLAY_NAME = '${ctx.displayName}';
+
+/** Lucide-react icon name, shared by onboarding + both descriptors. */
+const ${constPrefix}_ICON_NAME = 'Plug';
+
+const ${constPrefix}_DESCRIPTION = '${ctx.description.replaceAll("'", "\\'")}';
+
+/**
+ * Biome-contributed adapter kind. NOT a member of the kernel's built-in set —
+ * it is the canonical string this connector declares, and the value the
+ * gateway routes on.
+ */
+export const ${constPrefix}_ADAPTER_KIND = '${providerKey}';
+
+/** Header the provider stamps its signature on. TODO: use the real one. */
+const SIGNATURE_HEADER = 'x-${providerKey}-signature';
+
+// ── Webhook verifier — constant-time, fail-closed ───────────────────────────
+
+const ${camel}Verifier: WebhookVerifier = {
+  signatureHeader: SIGNATURE_HEADER,
+  // TODO: switch to the provider's real algorithm (e.g. 'hmac-sha256') and
+  // verify over the RAW body bytes, not a re-serialized object.
+  algorithm: 'none',
+  secretSource: 'org-connection-secret',
+  verify({ headers, secret }) {
+    const provided = headers[SIGNATURE_HEADER];
+    if (typeof provided !== 'string' || provided.length === 0) {
+      return err(
+        adapterError('verification-failed', \`missing \${SIGNATURE_HEADER} header\`),
+      );
+    }
+    if (provided.length !== secret.length) {
+      return err(adapterError('verification-failed', 'signature length mismatch'));
+    }
+    let equal: boolean;
+    try {
+      equal = timingSafeEqual(
+        Buffer.from(provided, 'utf8'),
+        Buffer.from(secret, 'utf8'),
+      );
+    } catch {
+      return err(adapterError('verification-failed', 'signature decode failed'));
+    }
+    return equal
+      ? ok(undefined)
+      : err(adapterError('verification-failed', 'signature mismatch'));
+  },
+};
+
+// ── Idempotency — deterministic, never time-based ───────────────────────────
+
+/**
+ * A retried delivery MUST produce the same key as its original, or the
+ * platform will process it twice. Prefer the provider's own delivery id; fall
+ * back to a hash of the canonical body so identical bytes dedup. An
+ * underivable key is a hard error — never fabricate a unique one.
+ */
+const ${camel}IdempotencyKeyExtractor: IdempotencyKeyExtractor = ({
+  rawBody,
+}) => {
+  if (rawBody && typeof rawBody === 'object') {
+    // TODO: read the provider's real delivery id field.
+    const deliveryId = (rawBody as Record<string, unknown>)['id'];
+    if (typeof deliveryId === 'string' && deliveryId.length > 0) {
+      return \`${providerKey}:\${deliveryId}\`;
+    }
+  }
+  const canonical =
+    typeof rawBody === 'string'
+      ? rawBody
+      : rawBody instanceof Uint8Array
+        ? Buffer.from(rawBody).toString('utf8')
+        : rawBody && typeof rawBody === 'object'
+          ? JSON.stringify(rawBody)
+          : '';
+  if (canonical.length === 0) {
+    throw new Error(
+      '${providerKey} webhook: cannot derive a deterministic idempotency key (no delivery id and empty body)',
+    );
+  }
+  return \`${providerKey}:\${createHash('sha256').update(canonical, 'utf8').digest('hex')}\`;
+};
+
+// ── Event mapper — provider payload → canonical envelope ────────────────────
+
+const ${camel}EventMapper: EventMapper = {
+  map({ rawEvent }) {
+    if (!rawEvent || typeof rawEvent !== 'object') {
+      return err(
+        adapterError('malformed-payload', '${providerKey} body is not an object'),
+      );
+    }
+    const payload = rawEvent as Record<string, unknown>;
+    const externalId = payload['id'];
+    if (typeof externalId !== 'string' || externalId.length === 0) {
+      // TODO: decide per event type. Return ok(null) to record-and-drop an
+      // event this connector deliberately does not model; return err(...) only
+      // when the payload is genuinely malformed.
+      return err(
+        adapterError('malformed-payload', '${providerKey} event: string \`id\` required'),
+      );
+    }
+    const envelope: MappedEnvelope = {
+      // TODO: the canonical entity kind + event this connector produces.
+      entityKind: 'record',
+      event: '${providerKey}.record.received',
+      payload,
+      externalId,
+    };
+    return ok(envelope);
+  },
+};
+
+// ── Onboarding manifest — this list IS the connect form ─────────────────────
+
+const ${camel}Onboarding: ProviderOnboardingManifest = {
+  provider: ${constPrefix}_PROVIDER_KEY,
+  displayName: ${constPrefix}_DISPLAY_NAME,
+  description: ${constPrefix}_DESCRIPTION,
+  iconName: ${constPrefix}_ICON_NAME,
+  kind: ConnectorOnboardingKind.CREDENTIALS,
+  supportedProjectBindingAdapterKinds: [],
+  fields: [
+    {
+      key: 'apiKey',
+      label: 'API key',
+      type: CredentialFieldType.PASSWORD,
+      required: true,
+      isSecret: true,
+      hint: 'Held by the credential broker and resolved at use — this biome never reads it.',
+      transform: CredentialFieldTransform.TRIM,
+    },
+  ],
+  hint: 'TODO: tell the operator where to obtain the credential.',
+};
+
+// ── Provider + connector descriptors ────────────────────────────────────────
+
+export const providerDescriptor: ProviderDescriptor = {
+  providerKey: ${constPrefix}_PROVIDER_KEY,
+  displayName: ${constPrefix}_DISPLAY_NAME,
+  description: ${constPrefix}_DESCRIPTION,
+  iconName: ${constPrefix}_ICON_NAME,
+  category: 'Other',
+  // No shared platform app ⇒ every connection carries its own complete secret,
+  // so the connector is usable with zero org-level setup. Switch to OAuth2 and
+  // declare the authorize/token endpoints when the provider has a shared app.
+  appAuthKind: ProviderAppAuthKind.None,
+  origin: ProviderOrigin.Biome,
+  allowOrgOverride: false,
+};
+
+export const connectorDescriptors: readonly ConnectorDescriptor[] = [
+  {
+    connectorKey: '${connectorKey}',
+    displayName: ${constPrefix}_DISPLAY_NAME,
+    description: ${constPrefix}_DESCRIPTION,
+    iconName: ${constPrefix}_ICON_NAME,
+    providerKey: ${constPrefix}_PROVIDER_KEY,
+    scopes: [],
+    connectionCredentialKind: CredentialKind.ApiKey,
+    adapterKind: ${constPrefix}_ADAPTER_KIND,
+  },
+];
+
+/**
+ * The provider module. The gateway's loader imports \`default\` (or the named
+ * \`connectorAdapters\` array) and registers every entry.
+ */
+export const ${camel}Provider: ConnectorAdapterModule = defineConnectorAdapter({
+  adapterKind: ${constPrefix}_ADAPTER_KIND,
+  provider: ${constPrefix}_PROVIDER_KEY,
+  displayName: ${constPrefix}_DISPLAY_NAME,
+  webhook: {
+    verifier: ${camel}Verifier,
+    eventMapper: ${camel}EventMapper,
+    idempotencyKeyExtractor: ${camel}IdempotencyKeyExtractor,
+  },
+  credentialKind: CredentialKind.ApiKey,
+  resources: {},
+  actions: {},
+  onboarding: ${camel}Onboarding,
+});
+
+const connectorAdapters: readonly ConnectorAdapterModule[] = [${camel}Provider];
+export default connectorAdapters;
+`;
+}
+function renderConnectorTest(ctx, providerKey, connectorKey, camel) {
+    const constPrefix = constCase(providerKey);
+    return `// ${ctx.displayName} — connector-adapter conformance tests.
+//
+// Run against the BUILT module (\`pnpm test\` builds first): these assert the
+// invariants the ingress edge relies on — fail-closed verification and a
+// deterministic idempotency key — so a change that breaks either is caught
+// here rather than as duplicate processing in production.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import connectorAdapters, {
+  ${constPrefix}_ADAPTER_KIND,
+  ${constPrefix}_PROVIDER_KEY,
+  connectorDescriptors,
+  providerDescriptor,
+  ${camel}Provider,
+} from '../dist/connector-adapters/index.js';
+
+test('the biome contributes exactly one ConnectorAdapterModule', () => {
+  assert.equal(connectorAdapters.length, 1);
+  assert.equal(connectorAdapters[0], ${camel}Provider);
+  assert.equal(${camel}Provider.provider, ${constPrefix}_PROVIDER_KEY);
+  assert.equal(${camel}Provider.adapterKind, ${constPrefix}_ADAPTER_KIND);
+});
+
+test('the descriptors that drive connect + custody are complete', () => {
+  assert.equal(providerDescriptor.providerKey, ${constPrefix}_PROVIDER_KEY);
+  assert.equal(connectorDescriptors.length, 1);
+  assert.equal(connectorDescriptors[0].connectorKey, '${connectorKey}');
+  assert.equal(connectorDescriptors[0].providerKey, ${constPrefix}_PROVIDER_KEY);
+  // The connect form is rendered from these fields; an empty list means the
+  // operator is shown a form that collects nothing.
+  assert.ok(${camel}Provider.onboarding.fields.length > 0);
+});
+
+test('verification fails closed on a missing or mismatched signature', () => {
+  const { verifier } = ${camel}Provider.webhook;
+  assert.equal(
+    verifier.verify({ rawBody: new Uint8Array(), headers: {}, secret: 's3cret' }).ok,
+    false,
+  );
+  assert.equal(
+    verifier.verify({
+      rawBody: new Uint8Array(),
+      headers: { [verifier.signatureHeader]: 'wrong!' },
+      secret: 's3cret',
+    }).ok,
+    false,
+  );
+  assert.equal(
+    verifier.verify({
+      rawBody: new Uint8Array(),
+      headers: { [verifier.signatureHeader]: 's3cret' },
+      secret: 's3cret',
+    }).ok,
+    true,
+  );
+});
+
+test('the idempotency key is deterministic across redeliveries', () => {
+  const extract = ${camel}Provider.webhook.idempotencyKeyExtractor;
+  const body = { id: 'evt_1' };
+  assert.equal(extract({ rawBody: body, headers: {} }), extract({ rawBody: body, headers: {} }));
+  assert.notEqual(
+    extract({ rawBody: body, headers: {} }),
+    extract({ rawBody: { id: 'evt_2' }, headers: {} }),
+  );
+});
+
+test('an underivable idempotency key throws rather than fabricating one', () => {
+  const extract = ${camel}Provider.webhook.idempotencyKeyExtractor;
+  assert.throws(() => extract({ rawBody: '', headers: {} }));
+});
+`;
+}
 export function renderServerBiomeFiles(ctx) {
     return {
         ...serverBiomeRootFiles(ctx),