@xemahq/create-biome 0.3.0 → 0.3.1

package/src/lib/template-files.ts

@@ -0,0 +1,1701 @@
+/**
+ * In-source template bodies for the in-tree biome scaffold. Embedded as plain
+ * TS strings (rather than an out-of-tree `templates/` folder copied at
+ * runtime) so the scaffolder's behavior is fully testable without filesystem
+ * fixtures, and so `pnpm dlx @xemahq/create-biome` ships in one tarball.
+ *
+ * Each renderer returns the set of files to write, keyed by biome-root-
+ * relative path. The scaffolder writes them under `<target>/<key>`.
+ *
+ * The SERVER renderers mirror a real first-party biome-api (e.g.
+ * `repos/xema-base/biomes/agent-runtime/api/memory-api`): a minimal NestJS
+ * service bootstrapped by `XemaServiceModule.forBiome(...)` reading a generated
+ * `<api>.bootstrap.generated.ts` descriptor, pnpm `catalog:` deps, a flat
+ * ESLint config, `nest-cli.json` with the Swagger plugin, and a
+ * `@XemaResource`-annotated controller whose routes PROJECT into real
+ * capabilities with no descriptor authored anywhere.
+ *
+ * The WEB renderer mirrors a real web biome (`biomes/platform/documents-web`):
+ * a `defineWebBiome` default export contributing a nav item, a project-scoped
+ * lazy list page, and a `navHidden` detail page that is the landing target of
+ * the search-type contribution's `routeTemplate` — so the scaffolded deep link
+ * resolves instead of 404-ing.
+ *
+ * The CONNECTOR renderer mirrors a real connector biome
+ * (`repos/xema-community/biomes/connector-telegram`): one
+ * `ConnectorAdapterModule` built with `defineConnectorAdapter`, no NestJS API
+ * and no web surface, which is exactly what
+ * `tooling/boundaries/check-connector-biome.mjs` requires.
+ */
+
+import { apiNameForBiome } from './manifest-builder.js';
+
+export interface TemplateContext {
+  readonly biomeId: string;
+  readonly displayName: string;
+  readonly description: string;
+}
+
+export type TemplateFiles = Readonly<Record<string, string>>;
+
+// ── Shared helpers ──────────────────────────────────────────────────
+
+function camelize(kebab: string): string {
+  return kebab.replaceAll(/-([a-z0-9])/g, (_, ch: string) => ch.toUpperCase());
+}
+
+function pascalize(kebab: string): string {
+  const camel = camelize(kebab);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+
+function constCase(kebab: string): string {
+  return kebab.replaceAll('-', '_').toUpperCase();
+}
+
+function snakeCase(kebab: string): string {
+  return kebab.replaceAll('-', '_');
+}
+
+/**
+ * The sample RESOURCE noun the scaffolded controller owns.
+ *
+ * Deliberately `item` and not the biome id: the biome id is already the
+ * capability `<domain>`, and `@XemaResource` names the `<resource>` — using the
+ * id for both would emit `<id>:<id>.list@1` and teach the author that the two
+ * are the same axis. `item` also keeps the whole scaffold coherent: it is the
+ * `authz.resourceType` and the `<snake_id>_item` docType the seeded search-type
+ * contribution declares, and the `{sourceId}` its `routeTemplate` resolves.
+ *
+ * Rename it and every derived capability ref follows automatically — that is
+ * the entire point of deriving rather than declaring.
+ */
+const SAMPLE_RESOURCE = 'item';
+
+/** URL collection segment for {@link SAMPLE_RESOURCE}. */
+const SAMPLE_RESOURCE_PLURAL = 'items';
+
+/**
+ * Source directory of the sample resource module. A CONSTANT, not a value
+ * derived from the biome id: the previous scaffold derived the import path in
+ * `app.module.ts` by de-Pascal-casing the module class name while writing the
+ * file under the raw biome id — two independent derivations of one path that
+ * agreed for most ids and silently diverged for others. One constant cannot
+ * diverge from itself.
+ */
+const FEATURE_DIR = SAMPLE_RESOURCE_PLURAL;
+
+/**
+ * Exported class of the sample resource module. Named after the RESOURCE, not
+ * the biome, so the class name, the file path and the import in `app.module.ts`
+ * all derive from one constant. The generated conformance test imports this
+ * exact symbol from the compiled module — a mismatch between the class name and
+ * the file name is not a typecheck error, it is a silent empty capability scan.
+ */
+const FEATURE_MODULE_CLASS = 'ItemsModule';
+
+// ── Server biome: top-level content directories ──────────────────────
+
+/**
+ * The content directories every real biome carries. They are seeded at
+ * biome-discovery time; an empty directory is legal, so each ships a README
+ * placeholder (mirroring the `.gitkeep`/README convention in real biomes) that
+ * tells the author what to drop in.
+ */
+function serverBiomeRootFiles(ctx: TemplateContext): TemplateFiles {
+  return {
+    'README.md': `# ${ctx.displayName}
+
+${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
+# from this biome directory
+xema dev
+\`\`\`
+
+\`xema dev\` boots the biome against a local platform (the workspace source
+always wins — no publish, no token). When it does what you want:
+
+\`\`\`sh
+xema biome publish
+\`\`\`
+
+## Layout
+
+- \`xema-biome.json\` — the biome manifest (validated by \`BiomeManifestSchema\` at boot).
+- \`api/${apiNameForBiome(ctx.biomeId)}/\` — the NestJS service this biome ships,
+  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, 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
+
+When this biome lives inside the Xema monorepo, wire it into the workspace
+toolchain after scaffolding:
+
+\`\`\`sh
+# from the monorepo root
+pnpm install
+node tooling/codegen/generate-service-bootstrap.mjs   # sync the bootstrap descriptor
+pnpm refresh                                           # openapi -> client -> build
+\`\`\`
+`,
+    'skills/README.md': `# Skills
+
+Drop Skill folder bundles here, one per directory:
+
+\`\`\`
+skills/<slug>/SKILL.md
+\`\`\`
+
+\`SKILL.md\` is the only strict file (YAML frontmatter \`name\` + \`description\`,
+then a free-form markdown body). \`reference/\`, \`scripts/\`, and \`assets/\` are
+optional and mounted as-is. \`scope\` and \`phases\` are NOT frontmatter — they
+are server-resolved.
+`,
+    'agents/README.md': `# Agents
+
+Drop agent definitions here, one \`<slug>.md\` per agent. Each agent MUST also
+be declared in \`xema-biome.json\` under \`xema.agents[]\` (\`slug\` + \`mode\`) — the
+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/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
+workspace. See \`xema://manifest/primary-agent-base\` for the base to extend.
+`,
+  };
+}
+
+// ── Server biome: the NestJS API service ─────────────────────────────
+
+/**
+ * Render the NestJS API service under `api/<id>-api/`. Returns files keyed
+ * relative to the BIOME ROOT (so the `api/<id>-api/` prefix is included).
+ */
+function serverApiFiles(ctx: TemplateContext): TemplateFiles {
+  const apiName = apiNameForBiome(ctx.biomeId);
+  const apiDir = `api/${apiName}`;
+  const constName = `${constCase(apiName)}_BOOTSTRAP`;
+
+  return {
+    [`${apiDir}/package.json`]: `${JSON.stringify(
+      {
+        name: apiName,
+        version: '0.1.0',
+        private: true,
+        scripts: {
+          clean: 'rm -rf dist',
+          build: 'nest build',
+          format: 'prettier --write "src/**/*.ts"',
+          start: 'nest start',
+          'start:dev': 'nest start --watch',
+          lint: 'eslint "src/**/*.ts"',
+          'lint:fix': 'eslint "src/**/*.ts" --fix',
+          typecheck: 'tsc --noEmit',
+          // `test` builds first on purpose: the conformance tests assert the
+          // capabilities this service's routes PROJECT, and that assertion is
+          // only meaningful against compiled output carrying real decorator
+          // metadata. A test script that silently ran against a stale `dist`
+          // would pass while the source was broken.
+          test: 'nest build && node --test "test/*.test.mjs"',
+          openapi: 'NODE_PATH=node_modules xema-openapi',
+          'client:generate': 'xema-client-generate',
+        },
+        dependencies: {
+          '@nestjs/common': 'catalog:',
+          '@nestjs/config': 'catalog:',
+          '@nestjs/core': 'catalog:',
+          '@nestjs/platform-express': 'catalog:',
+          '@nestjs/swagger': 'catalog:',
+          '@xemahq/identity-client': 'catalog:',
+          '@xemahq/kernel-contracts': 'catalog:',
+          '@xemahq/platform-common': 'catalog:',
+          '@xemahq/service-registry-nest': 'catalog:',
+          '@xemahq/xema-decorators': 'catalog:',
+          '@xemahq/xema-service-nest': 'catalog:',
+          'class-transformer': 'catalog:',
+          'class-validator': 'catalog:',
+          'reflect-metadata': 'catalog:',
+          rxjs: 'catalog:',
+          'swagger-ui-express': 'catalog:',
+        },
+        devDependencies: {
+          '@eslint/js': 'catalog:',
+          '@nestjs/cli': 'catalog:',
+          '@nestjs/schematics': 'catalog:',
+          '@types/express': 'catalog:',
+          '@types/node': 'catalog:',
+          '@xemahq/api-client-generator': 'catalog:',
+          dotenv: 'catalog:',
+          eslint: 'catalog:',
+          'eslint-config-prettier': 'catalog:',
+          orval: 'catalog:',
+          prettier: 'catalog:',
+          typescript: 'catalog:',
+          'typescript-eslint': 'catalog:',
+        },
+        xema: {
+          api: {
+            serviceId: apiName,
+            biomeId: ctx.biomeId,
+            title: `${ctx.displayName} API`,
+            description: ctx.description,
+          },
+        },
+      },
+      null,
+      2,
+    )}\n`,
+    [`${apiDir}/tsconfig.json`]: `${JSON.stringify(
+      {
+        extends: '../../../../tsconfig.base.json',
+        compilerOptions: {
+          outDir: 'dist',
+          rootDir: 'src',
+          types: ['node'],
+          baseUrl: '.',
+        },
+        include: ['src/**/*.ts'],
+        exclude: ['node_modules', 'dist'],
+      },
+      null,
+      2,
+    )}\n`,
+    [`${apiDir}/nest-cli.json`]: `${JSON.stringify(
+      {
+        $schema: 'https://json.schemastore.org/nest-cli',
+        collection: '@nestjs/schematics',
+        sourceRoot: 'src',
+        compilerOptions: {
+          deleteOutDir: true,
+          plugins: [
+            {
+              name: '@nestjs/swagger',
+              options: {
+                classValidatorShim: true,
+                introspectComments: true,
+              },
+            },
+          ],
+        },
+      },
+      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),
+    [`${apiDir}/src/config/index.ts`]: renderConfigIndex(),
+    [`${apiDir}/src/health/health.module.ts`]: HEALTH_MODULE,
+    [`${apiDir}/src/health/health.controller.ts`]: HEALTH_CONTROLLER,
+    [`${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(),
+  };
+}
+
+/**
+ * Seed bootstrap descriptor. `generate-service-bootstrap.mjs` is the single
+ * source of truth and overwrites this file from the manifest; we seed a valid
+ * file so the service typechecks before the author runs codegen. The body is
+ * kept BYTE-IDENTICAL to what the codegen emits for a fresh biome (same
+ * header, JSDoc, and field order — semver 0.1.0, biome-api, identity-api
+ * floor) so a freshly-scaffolded biome passes `generate-service-bootstrap.mjs
+ * --check` in CI without an immediate regenerate. The `manifestRel` line is
+ * the ONE field that differs by checkout location; codegen rewrites it.
+ *
+ * `biomeId` + `biomeVersion` are load-bearing, not decorative:
+ * `isHttpCapabilityProjectionEnabled` gates HTTP capability projection on BOTH
+ * being present, because a projected capability is stamped with its biome
+ * provenance and provenance cannot be guessed. A descriptor missing them boots
+ * fine and projects NOTHING — the exact silent no-op this scaffold exists to
+ * make impossible. `capabilityDomain` mirrors `xema.capabilityDomain`.
+ */
+function renderBootstrapPlaceholder(
+  apiName: string,
+  constName: string,
+  displayName: string,
+  biomeId: string,
+): string {
+  return `// AUTO-GENERATED by tooling/codegen/generate-service-bootstrap.mjs — DO NOT EDIT.
+// Source of truth: biomes/${biomeId}/xema-biome.json (xema.ships.apis[] + top-level version).
+// Regenerate: \`node tooling/codegen/generate-service-bootstrap.mjs\`.
+import {
+  ServiceKind,
+  type BiomeServiceDescriptor,
+} from '@xemahq/xema-service-nest';
+
+/**
+ * Bootstrap identity for ${apiName}, consumed by
+ * \`XemaServiceModule.forBiome(${constName})\`. Edit the biome manifest,
+ * not this file.
+ */
+export const ${constName}: BiomeServiceDescriptor = {
+  name: '${apiName}',
+  semver: '0.1.0',
+  serviceKind: ServiceKind.BiomeApi,
+  displayName: '${displayName}',
+  requiresServices: ['identity-api'],
+  exposesCapabilities: [],
+  biomeId: '${biomeId}',
+  biomeVersion: '0.1.0',
+  capabilityDomain: '${biomeId}',
+};
+`;
+}
+
+function renderMainTs(apiName: string, ctx: TemplateContext): string {
+  return `import { bootstrapXemaService } from '@xemahq/xema-service-nest';
+
+import { AppModule } from './app.module';
+import { requiredEnvVars } from './config';
+
+const swaggerDescription = \`
+${ctx.description}
+\`.trim();
+
+void bootstrapXemaService({
+  appModule: AppModule,
+  serviceName: '${apiName}',
+  swaggerTitle: '${ctx.displayName} API',
+  swaggerDescription,
+  requiredEnvVars,
+});
+`;
+}
+
+function renderAppModule(apiName: string, constName: string): string {
+  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';
+import { ResponseEnvelopeInterceptor } from '@xemahq/platform-common';
+import { XemaServiceModule } from '@xemahq/xema-service-nest';
+
+import { appConfig } from './config';
+import { ${constName} } from './generated/${apiName}.bootstrap.generated';
+import { HealthModule } from './health/health.module';
+import { ${featureModule} } from './${featureFile}/${featureFile}.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true, load: [appConfig] }),
+    // One-call platform bootstrap: Service Registry + Identity bootstrap +
+    // Auth (JWT + request context) + the runtime route/capability scanner.
+    // Service identity is the single source of truth in xema-biome.json,
+    // surfaced via the generated descriptor.
+    XemaServiceModule.forBiome(${constName}),
+    HealthModule,
+    ${featureModule},
+  ],
+  providers: [
+    { provide: APP_INTERCEPTOR, useClass: ResponseEnvelopeInterceptor },
+  ],
+})
+export class AppModule {}
+`;
+}
+
+/**
+ * Flat ESLint config for the generated API.
+ *
+ * SELF-CONTAINED on purpose: it uses only the four lint devDependencies the
+ * generated `package.json` declares, and extends no repo-relative shared config.
+ * A scaffolded biome must lint cleanly wherever it is generated — including
+ * outside the Xema monorepo, where `../../../../eslint.api-decorators-rules.mjs`
+ * does not exist. Adopt the shared config once the biome lives in-tree.
+ *
+ * Typed rules are scoped to `src/**\/*.ts` because `projectService` needs the
+ * file to be in a tsconfig program; the `.mjs` conformance tests are not, and
+ * pointing typed rules at them would fail the lint on a freshly-generated biome.
+ */
+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(): string {
+  return `import { registerAs } from '@nestjs/config';
+
+/**
+ * Environment variables this service requires at boot. \`bootstrapXemaService\`
+ * fail-fasts if any is missing. The platform bootstrap injects the registry /
+ * identity wiring; add service-specific required vars here as the biome grows.
+ */
+export const requiredEnvVars: readonly string[] = ['IDENTITY_API_URL'];
+
+export const appConfig = registerAs('app', () => ({
+  port: Number(process.env.PORT ?? '3000'),
+}));
+`;
+}
+
+const HEALTH_MODULE = `import { Module } from '@nestjs/common';
+
+import { HealthController } from './health.controller';
+
+@Module({ controllers: [HealthController] })
+export class HealthModule {}
+`;
+
+const HEALTH_CONTROLLER = `import { Controller, Get } from '@nestjs/common';
+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({ reason: PublicRouteReason.K8sProbe })
+  live(): { status: 'ok' } {
+    return { status: 'ok' };
+  }
+
+  @Get('ready')
+  @XemaPublicRoute({ reason: PublicRouteReason.K8sProbe })
+  ready(): { status: 'ok' } {
+    return { status: 'ok' };
+  }
+}
+`;
+
+function renderFeatureModule(): string {
+  return `import { Module } from '@nestjs/common';
+
+import { ItemsController } from './items.controller';
+import { ItemsService } from './items.service';
+
+@Module({
+  controllers: [ItemsController],
+  providers: [ItemsService],
+})
+export class ${FEATURE_MODULE_CLASS} {}
+`;
+}
+
+/**
+ * The controller that makes the scaffold's central promise true: FOUR
+ * agent-callable capabilities, in the graph, with schemas — from route
+ * metadata alone. No `@XemaCapability`, no `*.capability.contribution.json`.
+ */
+function renderFeatureController(ctx: TemplateContext): string {
+  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 renderItemDto(): string {
+  return `import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+/**
+ * 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;
+}
+
+export class CreateItemDto {
+  @ApiProperty({ description: 'Human-readable title.', maxLength: 200 })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(200)
+  title!: string;
+}
+`;
+}
+
+function renderFeatureService(): string {
+  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 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\`);
+    }
+  }
+}
+`;
+}
+
+// ── Server biome: conformance tests ──────────────────────────────────
+
+/**
+ * Validates the biome's own declarations against the kernel schemas that the
+ * platform validates them against at boot — so a broken manifest or a broken
+ * search-type contribution fails here, in the author's terminal, instead of at
+ * install time in someone else's cluster.
+ */
+function renderManifestTest(ctx: TemplateContext): string {
+  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);
+});
+`;
+}
+
+/**
+ * The test that makes "nobody hand-writes a capability descriptor" checkable.
+ *
+ * It runs the SAME derivation the running service runs — `scanApiSurfaces` →
+ * `stampRouteExtensions` → `deriveHttpCapabilities` — against an un-listened
+ * Nest app, so it needs no database, no registry, no network. If a route stops
+ * projecting, or projects under a ref nobody expected, this fails.
+ */
+function renderCapabilitiesTest(ctx: TemplateContext, apiName: string): string {
+  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/);
+});
+`;
+}
+
+// ── Web biome ────────────────────────────────────────────────────────
+
+export interface WebTemplateContext extends TemplateContext {
+  /** The web biome id (e.g. `<id>-web`). */
+  readonly webBiomeId: string;
+  /** Display name shown in the nav rail. */
+  readonly navLabel: string;
+}
+
+/**
+ * Render the web biome's source files, keyed relative to the WEB BIOME ROOT
+ * (`biomes/<tier>/<id>-web/`). Mirrors `biomes/platform/documents-web`.
+ */
+export function webBiomeFiles(ctx: WebTemplateContext): TemplateFiles {
+  const pageComponent = `${pascalize(ctx.biomeId)}Page`;
+  const detailComponent = `${pascalize(ctx.biomeId)}DetailPage`;
+  const navId = ctx.biomeId;
+  return {
+    'package.json': `${JSON.stringify(
+      {
+        name: `@xemahq/biomes-${ctx.webBiomeId}`,
+        version: '0.1.0',
+        description: ctx.description,
+        license: 'Apache-2.0',
+        private: true,
+        type: 'module',
+        main: 'src/index.tsx',
+        types: 'src/index.tsx',
+        files: ['src', 'xema-biome.json'],
+        scripts: {
+          typecheck: 'tsc --noEmit',
+          lint: 'tsc --noEmit',
+          format: 'prettier --write "src/**/*.{ts,tsx}"',
+        },
+        peerDependencies: {
+          '@tanstack/react-query': '^5.0.0',
+          react: '^18.3.1',
+          'react-dom': '^18.3.1',
+        },
+        devDependencies: {
+          '@tanstack/react-query': '^5.83.0',
+          '@types/react': '^18.3.0',
+          '@types/react-dom': '^18.3.0',
+          'lucide-react': '^0.462.0',
+          prettier: '3.6.2',
+          react: '^18.3.1',
+          'react-dom': '^18.3.1',
+          typescript: '5.9.3',
+        },
+      },
+      null,
+      2,
+    )}\n`,
+    'tsconfig.json': WEB_TSCONFIG,
+    '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 = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "isolatedModules": true,
+    "useDefineForClassFields": true,
+    // Mirror the HOST root tsconfig — biome sources import host primitives
+    // authored under the host's compiler flags.
+    "exactOptionalPropertyTypes": false,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["../../../src/*"],
+      "@xemahq/ui-kernel": ["../../../src/lib/shared/ui-kernel/index.ts"],
+      "@xemahq/ui-kernel/*": ["../../../src/lib/shared/ui-kernel/*"],
+      "@xemahq/*": ["../../../src/lib/shared/*", "../../../src/lib/api/orval/clients/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}
+`;
+
+function renderWebIndex(
+  ctx: WebTemplateContext,
+  pageComponent: string,
+  detailComponent: string,
+  navId: string,
+): string {
+  return `import { defineWebBiome } from '@xemahq/ui-kernel';
+import { LayoutGrid } from 'lucide-react';
+
+/**
+ * Frontend module entry-point for the \`${ctx.webBiomeId}\` biome.
+ *
+ * \`defineWebBiome\` builds the biome from a declarative page list: each page's
+ * \`slug\` single-sources BOTH its nav route and its route path (they can never
+ * drift), and the page is lazily loaded behind a \`<Suspense>\` boundary. Declare
+ * WHAT each surface is via \`category\` — the HOST owns WHERE that category renders
+ * in the menu, so you never pick a global section/weight.
+ *
+ * The host bootstrap fetches \`GET /platform/biomes/web\`, dynamically imports
+ * this module for any entry where \`enabled === true\`, and registers the default
+ * export via \`registerFrontendBiome()\`. Pass \`init\`/\`panels\`/\`session\` to
+ * \`defineWebBiome\` for bespoke contributions; add more entries to \`pages\` (with
+ * \`navHidden: true\` for deeplink-only detail routes).
+ */
+const ${camelize(ctx.webBiomeId)}Biome = defineWebBiome({
+  id: '${ctx.webBiomeId}',
+  displayName: '${ctx.navLabel}',
+  pages: [
+    {
+      slug: '${navId}',
+      label: '${ctx.navLabel}',
+      icon: LayoutGrid,
+      // One of: primary | build | operate | knowledge | admin | account
+      category: 'build',
+      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: WebTemplateContext,
+  detailComponent: string,
+): string {
+  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: WebTemplateContext, pageComponent: string): string {
+  return `import { useBiomeRouteParams } from '@/lib/biomes/biome-host-next';
+
+/**
+ * Sample project-scoped page for the \`${ctx.webBiomeId}\` biome. Reads the
+ * project id bound by the biome route matcher via the host
+ * \`useBiomeRouteParams\` bridge hook (NEVER \`next/navigation\` — biome pages
+ * must go through the host's route-params context).
+ */
+export default function ${pageComponent}(): JSX.Element {
+  const { projectId } = useBiomeRouteParams<{ projectId?: string }>();
+
+  return (
+    <div className="p-6">
+      <h1 className="text-xl font-semibold">${ctx.navLabel}</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        ${ctx.description}
+      </p>
+      <p className="mt-4 text-sm">
+        Project scope:{' '}
+        <code>{projectId ?? '(none — open from a project)'}</code>
+      </p>
+    </div>
+  );
+}
+`;
+}
+
+// ── Connector biome ──────────────────────────────────────────────────
+
+/**
+ * Render a CONNECTOR biome, keyed relative to the biome root.
+ *
+ * Mirrors `repos/xema-community/biomes/connector-telegram`: one
+ * `ConnectorAdapterModule` and nothing else. The module is the SINGLE source
+ * of the provider/connector descriptors — the biome ships no parallel
+ * `*.connector-adapter.contribution.json`, because two declarations of the same
+ * descriptor is exactly the drift this scaffold exists to prevent. The
+ * `xema.contributes: ["connector-adapter"]` whitelist in the manifest is what
+ * `tooling/boundaries/check-connector-biome.mjs` reads.
+ */
+export function connectorBiomeFiles(ctx: TemplateContext): TemplateFiles {
+  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: TemplateContext,
+  providerKey: string,
+  connectorKey: string,
+): string {
+  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: TemplateContext,
+  providerKey: string,
+  connectorKey: string,
+  camel: string,
+): string {
+  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: TemplateContext,
+  providerKey: string,
+  connectorKey: string,
+  camel: string,
+): string {
+  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: {} }));
+});
+`;
+}
+
+// ── Public renderers ─────────────────────────────────────────────────
+
+/**
+ * All files for a SERVER biome (manifest is written separately by the
+ * scaffolder), keyed relative to the biome root `biomes/<id>/`.
+ */
+export function renderServerBiomeFiles(ctx: TemplateContext): TemplateFiles {
+  return {
+    ...serverBiomeRootFiles(ctx),
+    ...serverApiFiles(ctx),
+  };
+}