@xemahq/api-client-generator 0.1.5 → 0.3.0

package/dist/lib/seed-openapi-env.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.openApiScratchSchema = openApiScratchSchema;
 exports.seedOpenApiEnv = seedOpenApiEnv;
 const DUMMY_ENCRYPTION_KEY_HEX = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
 const DUMMY_BASE64_KEY = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
@@ -10,14 +11,22 @@ function seed(vars) {
         }
     }
 }
-function seedOpenApiEnv() {
+const SCRATCH_DB_NAME = 'dummy_openapi';
+function openApiScratchSchema(serviceId) {
+    return `extract_${serviceId.replace(/[^a-zA-Z0-9]+/g, '_')}`
+        .toLowerCase()
+        .slice(0, 63);
+}
+function seedOpenApiEnv(serviceId) {
+    const schema = openApiScratchSchema(serviceId);
     seed({
         NODE_ENV: 'development',
         XEMA_OPENAPI_EXTRACTION: '1',
-        DATABASE_URL: 'postgresql://dummy:dummy@localhost:5432/dummy_openapi',
+        DATABASE_URL: `postgresql://dummy:dummy@localhost:5432/${SCRATCH_DB_NAME}?schema=${schema}`,
         DB_HOST: 'localhost',
         DB_PORT: '5432',
-        DB_NAME: 'dummy_openapi',
+        DB_NAME: SCRATCH_DB_NAME,
+        DB_SCHEMA: schema,
         DB_USER: 'dummy',
         DB_PASSWORD: 'dummy',
         REDIS_URL: 'redis://localhost:6379',
@@ -31,38 +40,19 @@ function seedOpenApiEnv() {
         OPENCODE_WORKER_PASSWORD: 'dummy-worker-password',
         XEMA_ETCD_ENDPOINTS: 'localhost:2379',
         EVENT_HUB_URL: 'http://localhost:3128',
-        USER_API_URL: 'http://localhost:3050',
+        WEBHOOK_URL: 'http://localhost:3000/webhooks/events',
         BACKLOG_API_URL: 'http://localhost:3100',
         MEMORY_API_URL: 'http://localhost:3060',
         LLM_REGISTRY_API_URL: 'http://localhost:3112',
         LLM_GATEWAY_API_URL: 'http://localhost:3110',
-        POOL_API_URL: 'http://localhost:3145',
         ARTIFACT_STORE_API_URL: 'http://localhost:3130',
         KNOWLEDGE_BASE_API_URL: 'http://localhost:3200',
         PROJECT_REGISTRY_API_URL: 'http://localhost:3300',
-        INTEGRATION_ADAPTERS_API_URL: 'http://localhost:3900',
+        CONNECTOR_GATEWAY_API_URL: 'http://localhost:3900',
         DESIGN_SYSTEM_BUILDER_API_URL: 'http://localhost:3210',
         SEARCH_API_URL: 'http://localhost:3220',
         BILLING_API_URL: 'http://localhost:3140',
         CAPABILITY_REGISTRY_API_URL: 'http://localhost:3700',
-        MCP_KNOWLEDGE_BASE_URL: 'http://localhost:3201/mcp',
-        MCP_BACKLOG_URL: 'http://localhost:3101/mcp',
-        MCP_DOC_TEMPLATE_URL: 'http://localhost:3231/mcp',
-        MCP_PROJECT_REGISTRY_URL: 'http://localhost:3301/mcp',
-        MCP_SEARCH_URL: 'http://localhost:3221/mcp',
-        KNOWLEDGE_BASE_MCP_URL: 'http://localhost:3201/mcp',
-        BACKLOG_MCP_URL: 'http://localhost:3101/mcp',
-        ARTIFACT_STORE_MCP_URL: 'http://localhost:3131/mcp',
-        MEMORY_MCP_URL: 'http://localhost:3061/mcp',
-        CATALOG_MCP_URL: 'http://localhost:3111/mcp',
-        REVIEW_GATE_MCP_URL: 'http://localhost:3501/mcp',
-        AUDIT_LOG_MCP_URL: 'http://localhost:3601/mcp',
-        PROJECT_REGISTRY_MCP_URL: 'http://localhost:3301/mcp',
-        DOC_TEMPLATE_MCP_URL: 'http://localhost:3231/mcp',
-        PHASE_GATE_MCP_URL: 'http://localhost:3801/mcp',
-        UI_TEMPLATES_MCP_URL: 'http://localhost:3901/mcp',
-        SEARCH_MCP_URL: 'http://localhost:3221/mcp',
-        DESIGN_SYSTEM_BUILDER_MCP_URL: 'http://localhost:3211/mcp',
         SCM_WEBHOOK_SECRET: 'dummy-webhook-secret',
         SCM_WEBHOOK_BASE_URL: 'http://localhost:3500/webhooks',
         GITEA_URL: 'http://localhost:3000',

package/dist/lib/seed-openapi-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"seed-openapi-env.js","sourceRoot":"","sources":["../../src/lib/seed-openapi-env.ts"],"names":[],"mappings":";;AA6BA,wCAgGC;AA7GD,MAAM,wBAAwB,GAC5B,kEAAkE,CAAC;AACrE,MAAM,gBAAgB,GAAG,8CAA8C,CAAC;AAGxE,SAAS,IAAI,CAAC,IAA4B;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;YACnC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAgB,cAAc;IAC5B,IAAI,CAAC;QACH,QAAQ,EAAE,aAAa;QASvB,uBAAuB,EAAE,GAAG;QAG5B,YAAY,EAAE,uDAAuD;QACrE,OAAO,EAAE,WAAW;QACpB,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,eAAe;QACxB,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE,OAAO;QACpB,SAAS,EAAE,wBAAwB;QACnC,cAAc,EAAE,uBAAuB;QAGvC,gBAAgB,EAAE,uBAAuB;QACzC,2BAA2B,EAAE,aAAa;QAC1C,kBAAkB,EAChB,kEAAkE;QACpE,UAAU,EAAE,oCAAoC;QAChD,kBAAkB,EAAE,iDAAiD;QACrE,kBAAkB,EAAE,0BAA0B;QAC9C,wBAAwB,EAAE,uBAAuB;QAKjD,mBAAmB,EAAE,gBAAgB;QAGrC,aAAa,EAAE,uBAAuB;QAGtC,YAAY,EAAE,uBAAuB;QACrC,eAAe,EAAE,uBAAuB;QACxC,cAAc,EAAE,uBAAuB;QACvC,oBAAoB,EAAE,uBAAuB;QAC7C,mBAAmB,EAAE,uBAAuB;QAC5C,YAAY,EAAE,uBAAuB;QACrC,sBAAsB,EAAE,uBAAuB;QAC/C,sBAAsB,EAAE,uBAAuB;QAC/C,wBAAwB,EAAE,uBAAuB;QACjD,4BAA4B,EAAE,uBAAuB;QACrD,6BAA6B,EAAE,uBAAuB;QACtD,cAAc,EAAE,uBAAuB;QACvC,eAAe,EAAE,uBAAuB;QACxC,2BAA2B,EAAE,uBAAuB;QAGpD,sBAAsB,EAAE,2BAA2B;QACnD,eAAe,EAAE,2BAA2B;QAC5C,oBAAoB,EAAE,2BAA2B;QACjD,wBAAwB,EAAE,2BAA2B;QACrD,cAAc,EAAE,2BAA2B;QAC3C,sBAAsB,EAAE,2BAA2B;QACnD,eAAe,EAAE,2BAA2B;QAC5C,sBAAsB,EAAE,2BAA2B;QACnD,cAAc,EAAE,2BAA2B;QAC3C,eAAe,EAAE,2BAA2B;QAC5C,mBAAmB,EAAE,2BAA2B;QAChD,iBAAiB,EAAE,2BAA2B;QAC9C,wBAAwB,EAAE,2BAA2B;QACrD,oBAAoB,EAAE,2BAA2B;QACjD,kBAAkB,EAAE,2BAA2B;QAC/C,oBAAoB,EAAE,2BAA2B;QACjD,cAAc,EAAE,2BAA2B;QAC3C,6BAA6B,EAAE,2BAA2B;QAG1D,kBAAkB,EAAE,sBAAsB;QAC1C,oBAAoB,EAAE,gCAAgC;QACtD,SAAS,EAAE,uBAAuB;QAClC,gBAAgB,EAAE,aAAa;QAC/B,gBAAgB,EAAE,kBAAkB;QAGpC,qBAAqB,EAAE,wBAAwB;QAC/C,qBAAqB,EAAE,gBAAgB;QACvC,2BAA2B,EACzB,kEAAkE;QACpE,uBAAuB,EACrB,kEAAkE;QAGpE,yBAAyB,EAAE,+BAA+B;QAC1D,uBAAuB,EAAE,6BAA6B;KACvD,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"seed-openapi-env.js","sourceRoot":"","sources":["../../src/lib/seed-openapi-env.ts"],"names":[],"mappings":";;AA0CA,oDAIC;AAMD,wCAoFC;AAxHD,MAAM,wBAAwB,GAC5B,kEAAkE,CAAC;AACrE,MAAM,gBAAgB,GAAG,8CAA8C,CAAC;AAGxE,SAAS,IAAI,CAAC,IAA4B;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;YACnC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC;AAGD,MAAM,eAAe,GAAG,eAAe,CAAC;AAYxC,SAAgB,oBAAoB,CAAC,SAAiB;IACpD,OAAO,WAAW,SAAS,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAAE;SACzD,WAAW,EAAE;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAMD,SAAgB,cAAc,CAAC,SAAiB;IAC9C,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,CAAC;QACH,QAAQ,EAAE,aAAa;QASvB,uBAAuB,EAAE,GAAG;QAO5B,YAAY,EAAE,2CAA2C,eAAe,WAAW,MAAM,EAAE;QAC3F,OAAO,EAAE,WAAW;QACpB,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,eAAe;QACxB,SAAS,EAAE,MAAM;QACjB,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE,OAAO;QACpB,SAAS,EAAE,wBAAwB;QACnC,cAAc,EAAE,uBAAuB;QAGvC,gBAAgB,EAAE,uBAAuB;QACzC,2BAA2B,EAAE,aAAa;QAC1C,kBAAkB,EAChB,kEAAkE;QACpE,UAAU,EAAE,oCAAoC;QAChD,kBAAkB,EAAE,iDAAiD;QACrE,kBAAkB,EAAE,0BAA0B;QAC9C,wBAAwB,EAAE,uBAAuB;QAKjD,mBAAmB,EAAE,gBAAgB;QAMrC,aAAa,EAAE,uBAAuB;QACtC,WAAW,EAAE,uCAAuC;QAGpD,eAAe,EAAE,uBAAuB;QACxC,cAAc,EAAE,uBAAuB;QACvC,oBAAoB,EAAE,uBAAuB;QAC7C,mBAAmB,EAAE,uBAAuB;QAC5C,sBAAsB,EAAE,uBAAuB;QAC/C,sBAAsB,EAAE,uBAAuB;QAC/C,wBAAwB,EAAE,uBAAuB;QACjD,yBAAyB,EAAE,uBAAuB;QAClD,6BAA6B,EAAE,uBAAuB;QACtD,cAAc,EAAE,uBAAuB;QACvC,eAAe,EAAE,uBAAuB;QACxC,2BAA2B,EAAE,uBAAuB;QAGpD,kBAAkB,EAAE,sBAAsB;QAC1C,oBAAoB,EAAE,gCAAgC;QACtD,SAAS,EAAE,uBAAuB;QAClC,gBAAgB,EAAE,aAAa;QAC/B,gBAAgB,EAAE,kBAAkB;QAGpC,qBAAqB,EAAE,wBAAwB;QAC/C,qBAAqB,EAAE,gBAAgB;QACvC,2BAA2B,EACzB,kEAAkE;QACpE,uBAAuB,EACrB,kEAAkE;QAGpE,yBAAyB,EAAE,+BAA+B;QAC1D,uBAAuB,EAAE,6BAA6B;KACvD,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/service-config.d.ts

@@ -16,5 +16,5 @@ export declare function resolveServiceContext(serviceDir: string): ResolvedServi
 export declare function surfaceClientShortName(serviceId: string, surface: ApiSurface): string;
 export declare function surfaceClientPackageName(serviceId: string, surface: ApiSurface): string;
 export declare function surfaceClientDir(ctx: ResolvedServiceContext, surface: ApiSurface): string;
-export declare function surfaceSpecPath(ctx: ResolvedServiceContext, surface: ApiSurface): string;
+export declare function surfaceSpecPath(ctx: ResolvedServiceContext, surface: ApiSurface, outDir?: string): string;
 //# sourceMappingURL=service-config.d.ts.map

package/dist/lib/service-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-config.d.ts","sourceRoot":"","sources":["../../src/lib/service-config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAerD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IAErC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAE5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAGD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYlD;AAOD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,CA8ChF;AAeD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GAClB,MAAM,CAUR;AAGD,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GAClB,MAAM,CAER;AAGD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,sBAAsB,EAC3B,OAAO,EAAE,UAAU,GAClB,MAAM,CAMR;AAGD,wBAAgB,eAAe,CAC7B,GAAG,EAAE,sBAAsB,EAC3B,OAAO,EAAE,UAAU,GAClB,MAAM,CAER"}
+{"version":3,"file":"service-config.d.ts","sourceRoot":"","sources":["../../src/lib/service-config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAerD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IAErC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAE5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAGD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYlD;AAOD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,CA8ChF;AAeD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GAClB,MAAM,CAUR;AAGD,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GAClB,MAAM,CAER;AAGD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,sBAAsB,EAC3B,OAAO,EAAE,UAAU,GAClB,MAAM,CAMR;AAGD,wBAAgB,eAAe,CAC7B,GAAG,EAAE,sBAAsB,EAC3B,OAAO,EAAE,UAAU,EAWnB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAER"}

package/dist/lib/service-config.js

@@ -74,7 +74,7 @@ function surfaceClientDir(ctx, surface) {
     const dirName = surfaceClientShortName(ctx.api.serviceId, surface).replace(/-client$/, '');
     return (0, node_path_1.join)(ctx.repoRoot, 'packages', 'clients', dirName);
 }
-function surfaceSpecPath(ctx, surface) {
-    return (0, node_path_1.join)(ctx.serviceDir, `openapi.${surface}.json`);
+function surfaceSpecPath(ctx, surface, outDir) {
+    return (0, node_path_1.join)(outDir ?? ctx.serviceDir, `openapi.${surface}.json`);
 }
 //# sourceMappingURL=service-config.js.map

package/dist/lib/service-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"service-config.js","sourceRoot":"","sources":["../../src/lib/service-config.ts"],"names":[],"mappings":";;AAqCA,oCAYC;AAOD,sDA8CC;AAeD,wDAaC;AAGD,4DAKC;AAGD,4CASC;AAGD,0CAKC;AA9JD,qCAAmD;AACnD,yCAAmD;AAEnD,6DAAqD;AAkCrD,SAAgB,YAAY,CAAC,KAAa;IACxC,IAAI,GAAG,GAAG,IAAA,mBAAO,EAAC,KAAK,CAAC,CAAC;IACzB,OAAO,GAAG,KAAK,IAAA,mBAAO,EAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,IAAI,IAAA,oBAAU,EAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC;YACjD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,GAAG,GAAG,IAAA,mBAAO,EAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,IAAI,KAAK,CACb,2EAA2E;QACzE,mBAAmB,KAAK,GAAG,CAC9B,CAAC;AACJ,CAAC;AAOD,SAAgB,qBAAqB,CAAC,UAAkB;IACtD,MAAM,OAAO,GAAG,IAAA,gBAAI,EAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACjD,IAAI,CAAC,IAAA,oBAAU,EAAC,OAAO,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,kDAAkD,OAAO,YAAY;YACnE,qCAAqC,CACxC,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,OAAO,EAAE,MAAM,CAAC,CAGnD,CAAC;IACF,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC;IAC1B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,yBAAyB,OAAO,wCAAwC;YACtE,mEAAmE;YACnE,sCAAsC,CACzC,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC;IACvD,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAC3E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,oCAAoC,KAAK,+BAA+B;gBACtE,uBAAuB,OAAO,GAAG,CACpC,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CACb,yBAAyB,OAAO,oCAAoC;YAClE,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,UAAU,EAAE,IAAA,mBAAO,EAAC,UAAU,CAAC;QAC/B,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC;QAClC,GAAG,EAAE;YACH,SAAS,EAAE,SAAmB;YAC9B,OAAO,EAAE,OAAiB;YAC1B,KAAK,EAAE,KAAe;YACtB,GAAG,CAAC,OAAO,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5D;QACD,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;AACJ,CAAC;AAeD,SAAgB,sBAAsB,CACpC,SAAiB,EACjB,OAAmB;IAEnB,IAAI,OAAO,KAAK,4BAAU,CAAC,MAAM,EAAE,CAAC;QAClC,OAAO,GAAG,SAAS,SAAS,CAAC;IAC/B,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC;IACxB,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChD,OAAO,GAAG,IAAI,IAAI,OAAO,aAAa,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,SAAS,IAAI,OAAO,SAAS,CAAC;AAC1C,CAAC;AAGD,SAAgB,wBAAwB,CACtC,SAAiB,EACjB,OAAmB;IAEnB,OAAO,WAAW,sBAAsB,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC;AACjE,CAAC;AAGD,SAAgB,gBAAgB,CAC9B,GAA2B,EAC3B,OAAmB;IAEnB,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,OAAO,CACxE,UAAU,EACV,EAAE,CACH,CAAC;IACF,OAAO,IAAA,gBAAI,EAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAC5D,CAAC;AAGD,SAAgB,eAAe,CAC7B,GAA2B,EAC3B,OAAmB;IAEnB,OAAO,IAAA,gBAAI,EAAC,GAAG,CAAC,UAAU,EAAE,WAAW,OAAO,OAAO,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"service-config.js","sourceRoot":"","sources":["../../src/lib/service-config.ts"],"names":[],"mappings":"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"}

package/dist/lib/service-nest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-nest.d.ts","sourceRoot":"","sources":["../../src/lib/service-nest.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,OAAO,eAAe,CAAC;IACjD,QAAQ,CAAC,aAAa,EAAE,OAAO,aAAa,CAAC;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAClD,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;CACnD;AAQD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAY/D;AAED,YAAY,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"service-nest.d.ts","sourceRoot":"","sources":["../../src/lib/service-nest.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,OAAO,eAAe,CAAC;IACjD,QAAQ,CAAC,aAAa,EAAE,OAAO,aAAa,CAAC;IAC7C,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAClD,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IAChD,QAAQ,CAAC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;CACnD;AAWD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAY/D;AAED,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/lib/service-nest.js.map

@@ -1 +1 @@
-{"version":3,"file":"service-nest.js","sourceRoot":"","sources":["../../src/lib/service-nest.ts"],"names":[],"mappings":";;AAwCA,0CAYC;AAlBD,SAAS,WAAW,CAAC,UAAkB,EAAE,OAAe;IACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAEnE,OAAO,OAAO,CAAC,QAAQ,CAA4B,CAAC;AACtD,CAAC;AAED,SAAgB,eAAe,CAAC,UAAkB;IAChD,MAAM,IAAI,GAAG,WAAW,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,WAAW,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IAC3D,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAmB;QACjC,eAAe,EAAE,OAAO,CAAC,eAAyC;QAClE,aAAa,EAAE,OAAO,CAAC,aAAqC;QAC5D,gBAAgB,EAAE,IAAI,CAAC,gBAA0C;QACjE,eAAe,EAAE,IAAI,CAAC,eAAwC;QAC9D,gBAAgB,EAAE,IAAI,CAAC,gBAA0C;KAClE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"service-nest.js","sourceRoot":"","sources":["../../src/lib/service-nest.ts"],"names":[],"mappings":";;AA2CA,0CAYC;AArBD,SAAS,WAAW,CAClB,UAAkB,EAClB,OAAe;IAEf,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAEnE,OAAO,OAAO,CAAC,QAAQ,CAA4B,CAAC;AACtD,CAAC;AAED,SAAgB,eAAe,CAAC,UAAkB;IAChD,MAAM,IAAI,GAAG,WAAW,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,WAAW,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IAC3D,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAmB;QACjC,eAAe,EAAE,OAAO,CAAC,eAAyC;QAClE,aAAa,EAAE,OAAO,CAAC,aAAqC;QAC5D,gBAAgB,EAAE,IAAI,CAAC,gBAA0C;QACjE,eAAe,EAAE,IAAI,CAAC,eAAwC;QAC9D,gBAAgB,EAAE,IAAI,CAAC,gBAA0C;KAClE,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/api-client-generator",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Layer 1 — the single, central OpenAPI + ORVAL client generator for every Xema NestJS service. Replaces the per-service orval.config.ts / scripts/extract-openapi.ts / scripts/build-client-index.js trio with two bins (xema-openapi, xema-client-generate). Extracts one OpenAPI document per ApiSurface (public/internal/operator) using the @XemaApiSurface decorator metadata, generates one ORVAL client package per non-empty surface (all sharing the owning service's version), and stamps deterministic `xema` provenance metadata into each generated client package.json. No heuristics: a route ships in a surface only if it (or its controller) is explicitly classified.",
   "keywords": [
     "xema",
@@ -30,14 +30,15 @@
     "xema-client-generate": "dist/bin/xema-client-generate.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "peerDependencies": {
     "@nestjs/common": "^10 || ^11",
     "@nestjs/core": "^10 || ^11",
     "@nestjs/swagger": "^7 || ^8 || ^11",
     "@nestjs/testing": "^10 || ^11",
-    "@xemahq/xema-decorators": "^0.1.1 || ^0.2.0",
+    "@xemahq/xema-decorators": ">=0.4.0",
     "orval": "^8",
     "reflect-metadata": "^0.2",
     "ts-node": ">=10",
@@ -62,7 +63,7 @@
     "prettier": "3.6.2",
     "reflect-metadata": "0.2.2",
     "typescript": "5.9.3",
-    "@xemahq/xema-decorators": "0.2.3"
+    "@xemahq/xema-decorators": "0.5.2"
   },
   "exports": {
     ".": {
@@ -75,6 +76,7 @@
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
     "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint .",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/src/bin/xema-client-generate.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * `xema-client-generate` — generate (and compile) one ORVAL client package per
+ * surface that has an `openapi.<surface>.json` spec in the current working
+ * directory. Run AFTER `xema-openapi`.
+ *
+ * Service package.json: `"client:generate": "xema-client-generate"`.
+ */
+import { runClientGenerateCli } from '../lib/generate-clients';
+
+runClientGenerateCli();

package/src/bin/xema-openapi.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * `xema-openapi` — extract one OpenAPI document per ApiSurface from the NestJS
+ * service in the current working directory.
+ *
+ * Run from a service dir (where package.json carries `xema.api`). Self-registers
+ * ts-node + tsconfig-paths from the SERVICE's own toolchain so the service's TS
+ * `AppModule` compiles on import, then delegates to the generator.
+ *
+ * Service package.json: `"openapi": "NODE_PATH=node_modules xema-openapi"`.
+ */
+// `node:module` is a side-effect-free builtin, so a static import is
+// equivalent to the `require()` this used to do (the file compiles to
+// CommonJS) — and it drops an inline `import()` type annotation whose only
+// job was to type that `require`. The DYNAMIC requires below are different:
+// they resolve paths computed at runtime, after `ts-node.register()` has
+// patched the require hook, and must stay `require()`.
+import { Module } from 'node:module';
+import { delimiter } from 'node:path';
+
+function registerTsNode(cwd: string): void {
+  const tsNode = require.resolve('ts-node', { paths: [cwd] });
+
+  (require(tsNode) as { register: (o: unknown) => void }).register({
+    transpileOnly: true,
+  });
+  try {
+    const paths = require.resolve('tsconfig-paths/register', { paths: [cwd] });
+    require(paths);
+  } catch {
+    // tsconfig-paths is optional — services without path aliases don't need it.
+  }
+}
+
+function ensureNodePath(): void {
+  process.env.NODE_PATH = process.env.NODE_PATH
+    ? `node_modules${delimiter}${process.env.NODE_PATH}`
+    : 'node_modules';
+  (Module as unknown as { _initPaths: () => void })._initPaths();
+}
+
+ensureNodePath();
+registerTsNode(process.cwd());
+
+// Require AFTER ts-node is registered so the service's TS modules compile.
+
+const { runOpenApiCli } = require('../lib/extract-openapi') as {
+  runOpenApiCli: () => void;
+};
+
+runOpenApiCli();

package/src/index.ts

@@ -0,0 +1,9 @@
+// Public programmatic surface of the central API-client generator.
+export * from './lib/service-config';
+export * from './lib/overrides';
+export * from './lib/seed-openapi-env';
+export * from './lib/default-stubs';
+export * from './lib/extract-openapi';
+export * from './lib/repo-post-process';
+export * from './lib/client-package';
+export * from './lib/generate-clients';

package/src/lib/client-package.ts

@@ -0,0 +1,215 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import { ApiSurface } from '@xemahq/xema-decorators';
+
+import { CANONICAL_CUSTOM_FETCH } from './custom-fetch-template';
+import {
+  surfaceClientDir,
+  surfaceClientPackageName,
+  type ResolvedServiceContext,
+} from './service-config';
+
+/** The authoritative package→Xema mapping stamped into each generated client. */
+export interface GeneratedClientXemaBlock {
+  readonly kind: 'api-client';
+  readonly surface: ApiSurface;
+  readonly service: string;
+  readonly biome: string;
+  readonly target: 'server';
+  readonly generator: string;
+  readonly source: string;
+}
+
+const CLIENT_TSCONFIG = {
+  compilerOptions: {
+    target: 'ES2022',
+    module: 'commonjs',
+    lib: ['ES2022', 'DOM'],
+    types: [],
+    strict: true,
+    esModuleInterop: true,
+    skipLibCheck: true,
+    declaration: true,
+    outDir: './dist',
+    rootDir: './src',
+  },
+  include: ['src/**/*.ts'],
+};
+
+function generatorTag(): string {
+  const pkg = require('../../package.json') as { version: string };
+  return `@xemahq/api-client-generator@${pkg.version}`;
+}
+
+function recordOrEmpty(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value))
+    : {};
+}
+
+/** Parse a release semver core `x.y.z` (any prerelease/build suffix ignored). */
+function parseVersionCore(v: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/**
+ * Resolve the client `version` MONOTONICALLY. A published client MUST NEVER be
+ * downgraded by regeneration: we keep whichever of the existing client version
+ * and the service version is greater. A forward bump happens only when the
+ * service version genuinely exceeds the client's (an intentional, monotonic
+ * move). If either version is unparseable, the existing version is kept — the
+ * fail-safe default is "never downgrade".
+ *
+ * A fresh client (no existing version) adopts the service version.
+ */
+export function resolveMonotonicVersion(
+  existing: unknown,
+  serviceVersion: string,
+): string {
+  if (typeof existing !== 'string' || existing.trim() === '') {
+    return serviceVersion;
+  }
+  const e = parseVersionCore(existing);
+  const s = parseVersionCore(serviceVersion);
+  if (!e || !s) {
+    return existing;
+  }
+  const [eMaj, eMin, ePat] = e;
+  const [sMaj, sMin, sPat] = s;
+  if (sMaj !== eMaj) {
+    return sMaj > eMaj ? serviceVersion : existing;
+  }
+  if (sMin !== eMin) {
+    return sMin > eMin ? serviceVersion : existing;
+  }
+  if (sPat !== ePat) {
+    return sPat > ePat ? serviceVersion : existing;
+  }
+  return existing;
+}
+
+/**
+ * Ensure the surface client package exists and carries the canonical stable
+ * metadata + the authoritative `xema` provenance block. Preserves any
+ * pre-existing `dependencies`/`peerDependencies` on an existing client.
+ *
+ * Returns the absolute client `src` directory (orval's output target).
+ */
+export function ensureClientPackage(
+  ctx: ResolvedServiceContext,
+  surface: ApiSurface,
+): { clientDir: string; clientSrc: string } {
+  const clientDir = surfaceClientDir(ctx, surface);
+  const clientSrc = join(clientDir, 'src');
+  mkdirSync(clientSrc, { recursive: true });
+
+  const packageName = surfaceClientPackageName(ctx.api.serviceId, surface);
+  const xema: GeneratedClientXemaBlock = {
+    kind: 'api-client',
+    surface,
+    service: ctx.api.serviceId,
+    biome: ctx.api.biomeId,
+    target: 'server',
+    generator: generatorTag(),
+    source: `openapi.${surface}.json`,
+  };
+
+  const pkgPath = join(clientDir, 'package.json');
+  const existing = existsSync(pkgPath)
+    ? (JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>)
+    : {};
+  const existingScripts = recordOrEmpty(existing.scripts);
+  const existingDevDeps = recordOrEmpty(existing.devDependencies);
+  const existingPublishConfig = recordOrEmpty(existing.publishConfig);
+  // Start from the existing (hand-maintained) package and override ONLY the
+  // fields the generator is explicitly responsible for. Every other field
+  // authored by hand — `dependencies` (e.g. zod), `peerDependencies`, extra
+  // scripts (`clean`/`typecheck`), extra devDependencies (`@types/node`),
+  // license/repository/exports/etc. — is preserved verbatim. Regeneration is
+  // metadata-stable: it never silently drops hand-maintained config and, per
+  // {@link resolveMonotonicVersion}, never downgrades the package version.
+  const pkg: Record<string, unknown> = {
+    ...existing,
+    name: packageName,
+    version: resolveMonotonicVersion(existing.version, ctx.version),
+    main: './dist/index.js',
+    types: './dist/index.d.ts',
+    files: ['dist'],
+    scripts: {
+      ...existingScripts,
+      // Generator-owned: the client must build and build-before-publish.
+      build: 'tsc -p tsconfig.json',
+      prepublishOnly: 'npm run build',
+    },
+    // This block used to be replaced WHOLESALE, which silently dropped
+    // `access: "public"` from every client on every regeneration — contradicting
+    // the promise three lines above. npm refuses to publish a SCOPED package
+    // without it, so each regeneration quietly armed a publish failure, and the
+    // fix (re-adding `access`) had to be re-applied by hand every time.
+    //
+    // `access` defaults to `public` because every generated @xemahq client is a
+    // public package; a hand-authored override still wins. `registry` stays
+    // generator-owned.
+    publishConfig: {
+      access: 'public',
+      ...existingPublishConfig,
+      registry: 'https://registry.npmjs.org/',
+    },
+    devDependencies: {
+      ...existingDevDeps,
+      // Generator-owned: tsc is required to build the generated client.
+      typescript: 'catalog:',
+    },
+    // Generator-owned: the authoritative provenance block is always rewritten.
+    xema,
+  };
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+
+  const tsconfigPath = join(clientDir, 'tsconfig.json');
+  if (!existsSync(tsconfigPath)) {
+    writeFileSync(
+      tsconfigPath,
+      `${JSON.stringify(CLIENT_TSCONFIG, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  ensureCustomFetch(ctx, clientSrc);
+
+  return { clientDir, clientSrc };
+}
+
+/**
+ * custom-fetch.ts is hand-maintained runtime config, identical across all
+ * clients. For an existing client it is left untouched. For a freshly
+ * scaffolded surface client we copy the service's public-surface sibling's
+ * custom-fetch when present (the most authoritative local copy), else write
+ * the canonical embedded template.
+ */
+function ensureCustomFetch(
+  ctx: ResolvedServiceContext,
+  clientSrc: string,
+): void {
+  const target = join(clientSrc, 'custom-fetch.ts');
+  if (existsSync(target)) {
+    return;
+  }
+  const publicSibling = join(
+    surfaceClientDir(ctx, ApiSurface.Public),
+    'src',
+    'custom-fetch.ts',
+  );
+  if (existsSync(publicSibling)) {
+    cpSync(publicSibling, target);
+    return;
+  }
+  writeFileSync(target, CANONICAL_CUSTOM_FETCH, 'utf8');
+}

package/src/lib/client-readme.ts

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ApiSurface } from '@xemahq/xema-decorators';
+
+/**
+ * Generated API clients carry a README emitted from the canonical package-README
+ * template (see the `write-package-readme` skill). It is fully generator-owned —
+ * never hand-edit a generated client's README; change this emitter and
+ * regenerate. The content is derived ONLY from the client's own identity (name,
+ * the owning service's title, the repo license) so it never needs updating when
+ * other packages change.
+ */
+
+/** Teal accent — the banner taxonomy colour for a generated API client. */
+const CLIENT_ACCENT = '#14B8A6';
+
+function detectRepoSpdx(repoRoot: string): string {
+  const licensePath = join(repoRoot, 'LICENSE');
+  if (existsSync(licensePath)) {
+    const head = readFileSync(licensePath, 'utf8').slice(0, 200);
+    if (/Apache License/i.test(head)) {
+      return 'Apache-2.0';
+    }
+    if (/all rights reserved/i.test(head)) {
+      return 'Proprietary';
+    }
+  }
+  return 'Proprietary';
+}
+
+function banner(packageName: string, tagline: string): string {
+  return [
+    `<svg width="680" height="120" viewBox="0 0 680 120" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="${packageName}">`,
+    `  <rect width="680" height="120" rx="14" fill="#0B1020"/>`,
+    `  <g transform="translate(28,34)">`,
+    `    <path d="M26 0 L52 15 L52 45 L26 60 L0 45 L0 15 Z" fill="${CLIENT_ACCENT}" opacity="0.18"/>`,
+    `    <path d="M26 12 L41 21 L41 39 L26 48 L11 39 L11 21 Z" fill="${CLIENT_ACCENT}"/>`,
+    `  </g>`,
+    `  <text x="92" y="52" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="22" fill="#F8FAFC" font-weight="700">${packageName}</text>`,
+    `  <text x="92" y="80" font-family="ui-sans-serif,system-ui,sans-serif" font-size="15" fill="#94A3B8">${tagline}</text>`,
+    `  <text x="652" y="105" text-anchor="end" font-family="ui-sans-serif,system-ui,sans-serif" font-size="12" fill="#475569">xema.dev</text>`,
+    `</svg>`,
+  ].join('\n');
+}
+
+/**
+ * Write `README.md` for a generated client package. Returns nothing; always
+ * overwrites (the README is generator-owned).
+ */
+export function ensureClientReadme(params: {
+  clientDir: string;
+  packageName: string;
+  serviceTitle: string;
+  surface: ApiSurface;
+  repoRoot: string;
+}): void {
+  const { clientDir, packageName, serviceTitle, surface, repoRoot } = params;
+  const enc = encodeURIComponent(packageName);
+  const spdx = detectRepoSpdx(repoRoot);
+  const surfaceWord = surface === ApiSurface.Public ? '' : `${surface} `;
+  const tagline = `Typed, generated ${surfaceWord}HTTP client for the ${serviceTitle}.`;
+  const licenseLine =
+    spdx === 'Apache-2.0'
+      ? 'Apache-2.0 &copy; Xema — [xema.dev](https://xema.dev)'
+      : 'Proprietary — &copy; Xema. All rights reserved. — [xema.dev](https://xema.dev)';
+
+  const md = `<!-- Generated by @xemahq/api-client-generator. Do not edit by hand. -->
+<p align="center">
+${banner(packageName, tagline)}
+</p>
+
+<p align="center">
+  <a href="https://xema.dev">Website</a> &middot;
+  <a href="https://www.npmjs.com/package/${packageName}">npm</a>
+</p>
+
+<p align="center">
+  <img alt="npm" src="https://img.shields.io/npm/v/${enc}?color=2563eb&label=npm">
+  <img alt="license" src="https://img.shields.io/npm/l/${enc}?color=10b981">
+  <img alt="types" src="https://img.shields.io/npm/types/${enc}?color=3178c6">
+</p>
+
+# ${packageName}
+
+> ${tagline}
+
+## Overview
+
+Auto-generated TypeScript client for the **${serviceTitle}**. It exports typed
+request functions and response models that mirror the service's OpenAPI surface,
+so callers get end-to-end type safety without hand-writing HTTP calls. This
+package is produced by \`@xemahq/api-client-generator\` and regenerated whenever
+the service's API changes — do not edit it by hand.
+
+## When to use it
+
+- Use it from any TypeScript service or app that calls the ${serviceTitle} over HTTP.
+- You get compile-time types for every endpoint and payload; regenerate to pick
+  up API changes rather than editing the client.
+
+## Installation
+
+\`\`\`bash
+pnpm add ${packageName}
+\`\`\`
+
+## Usage
+
+\`\`\`ts
+// Every endpoint function and response model is exported from the package root.
+import * as client from '${packageName}';
+\`\`\`
+
+Call the typed endpoint functions; request and response shapes are fully typed
+from the service's OpenAPI spec.
+
+## License
+
+${licenseLine}
+`;
+
+  writeFileSync(join(clientDir, 'README.md'), md, 'utf8');
+}