@kosdev-code/kos-codegen-core 3.0.19 → 3.0.21

package/index.mjs

@@ -3,7 +3,7 @@ import * as path from "path";
 import * as ejs from "ejs";
 import fg from "fast-glob";
 import prettier from "prettier";
-import { Scope, Project, QuoteKind, IndentationText, VariableDeclarationKind, Node } from "ts-morph";
+import { Scope, Project, QuoteKind, IndentationText, VariableDeclarationKind, Node, SyntaxKind } from "ts-morph";
 import * as ts from "typescript";
 class TrackingFileSystem {
   inner;
@@ -474,6 +474,84 @@ function generateSplashProject(codegenFs, templateDir, options) {
     normalized
   );
 }
+const MODEL_PROJECT_SUFFIX = "-models";
+const DEFAULT_MODEL_LIBS_DIR = "libs";
+const JSONC_ESLINT_PARSER_VERSION = "^2.1.0";
+function resolveModelProjectLayout(codegenFs, options) {
+  const base = dashCase(options.name);
+  const projectName = base.endsWith(MODEL_PROJECT_SUFFIX) ? base : `${base}${MODEL_PROJECT_SUFFIX}`;
+  const libsDir = (options.libsDir || DEFAULT_MODEL_LIBS_DIR).replace(
+    /\\/g,
+    "/"
+  );
+  const scope = codegenFs ? readNpmScope(codegenFs) : void 0;
+  return {
+    projectName,
+    projectRoot: `${libsDir}/${projectName}`.replace(/^\/+/, ""),
+    importPath: scope ? `@${scope}/${projectName}` : projectName
+  };
+}
+function readNpmScope(codegenFs) {
+  if (!codegenFs.exists("package.json")) {
+    return void 0;
+  }
+  const name = readJson(codegenFs, "package.json").name;
+  if (!name?.startsWith("@")) {
+    return void 0;
+  }
+  return name.split("/")[0].slice(1);
+}
+function offsetFromRoot(projectRoot) {
+  return projectRoot.split("/").filter(Boolean).map(() => "../").join("");
+}
+function generateModelProject(codegenFs, templateDir, options) {
+  const layout = resolveModelProjectLayout(codegenFs, options);
+  generateFilesFromTemplates(
+    codegenFs,
+    path.join(templateDir, "project"),
+    layout.projectRoot,
+    {
+      ...layout,
+      projectNameCamelCase: camelCase(layout.projectName),
+      offsetFromRoot: offsetFromRoot(layout.projectRoot),
+      template: ""
+    }
+  );
+  registerTsconfigPath(codegenFs, layout);
+  ensureJsoncEslintParser(codegenFs);
+  return layout;
+}
+function registerTsconfigPath(codegenFs, layout) {
+  if (!codegenFs.exists("tsconfig.base.json")) {
+    return;
+  }
+  updateJson(codegenFs, "tsconfig.base.json", (json) => {
+    json.compilerOptions = json.compilerOptions ?? {};
+    json.compilerOptions.paths = json.compilerOptions.paths ?? {};
+    json.compilerOptions.paths[layout.importPath] = [
+      `${layout.projectRoot}/src/index.ts`
+    ];
+    return json;
+  });
+}
+function ensureJsoncEslintParser(codegenFs) {
+  if (!codegenFs.exists("package.json")) {
+    return;
+  }
+  const pkg = readJson(codegenFs, "package.json");
+  const devDependencies = pkg.devDependencies ?? {};
+  if ("jsonc-eslint-parser" in devDependencies) {
+    return;
+  }
+  devDependencies["jsonc-eslint-parser"] = JSONC_ESLINT_PARSER_VERSION;
+  pkg.devDependencies = Object.fromEntries(
+    // Codepoint order, matching what Nx's own dependency helper produces.
+    Object.entries(devDependencies).sort(
+      ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+    )
+  );
+  writeJson(codegenFs, "package.json", pkg);
+}
 function generateInit(codegenFs, options) {
   const logger = getCodegenLogger();
   const { appProject, modelProject, registrationProject } = options;
@@ -492,7 +570,6 @@ function generateInit(codegenFs, options) {
     modelDirectory: "lib",
     appDirectory: "app",
     components: true,
-    dataServices: true,
     internal: false,
     singleton: false,
     unitTests: true
@@ -926,6 +1003,58 @@ function normalizeOptions(codegenFs, options, projects) {
     template: ""
   };
 }
+const UPDATE_RELEASE_VERSION_SCRIPT = `import devkit from "@nx/devkit";
+import { resolve } from "path";
+import { readFileSync, writeFileSync } from "fs";
+import prettier from "prettier";
+
+// KOS artifact versioning: stamps the project's .kos.json "version" field
+// (which kabtool bakes into the KAB). Never touches package.json.
+// Driven by tag-based releases:
+//   nx run-many --target=version --args=--ver=$KOSBUILD_VERSION
+
+const { readCachedProjectGraph } = devkit;
+const [, , name, versionArg] = process.argv;
+
+// "{args.ver}" arrives literally when the target runs without --args=--ver=<v>;
+// treat that (or a missing arg) as "report current version, change nothing".
+const version =
+  versionArg && !versionArg.startsWith("{args") ? versionArg : undefined;
+
+if (!name) {
+  console.error("usage: update-release-version.mjs <project> <version>");
+  process.exit(1);
+}
+
+const graph = readCachedProjectGraph();
+const project = graph.nodes[name];
+if (!project) {
+  console.error("Unknown project: " + name);
+  process.exit(1);
+}
+
+const kosJsonPath = resolve(process.cwd(), project.data.root, ".kos.json");
+let kosJson;
+try {
+  kosJson = JSON.parse(readFileSync(kosJsonPath, "utf8"));
+} catch {
+  console.error("Missing or invalid .kos.json: " + kosJsonPath);
+  process.exit(1);
+}
+
+if (!version) {
+  console.log(name + ": " + kosJson.version + " (no --ver given; unchanged)");
+  process.exit(0);
+}
+
+const prettierOptions = await prettier.resolveConfig(kosJsonPath);
+const output = await prettier.format(
+  JSON.stringify({ ...kosJson, version }, null, 2),
+  { ...prettierOptions, parser: "json" }
+);
+writeFileSync(kosJsonPath, output);
+console.log(name + ": version -> " + version);
+`;
 function transformSourceFile(codegenFs, filePath, mutate) {
   const content = codegenFs.read(filePath);
   if (content === null) {
@@ -1031,12 +1160,137 @@ function ensureModuleConst(sourceFile, spec) {
   });
   return true;
 }
+function afterImports(sourceFile) {
+  const imports = sourceFile.getImportDeclarations();
+  return imports.length > 0 ? imports[imports.length - 1].getChildIndex() + 1 : 0;
+}
+function unquote$1(name) {
+  return name.replace(/^["']|["']$/g, "");
+}
+function getConstCatalogLiteral(sourceFile, name) {
+  const declaration = sourceFile.getVariableDeclaration(name);
+  if (!declaration) return null;
+  let initializer = declaration.getInitializer();
+  if (Node.isAsExpression(initializer)) {
+    initializer = initializer.getExpression();
+  }
+  if (!initializer || !Node.isObjectLiteralExpression(initializer)) {
+    throw new Error(
+      `"${name}" exists in ${sourceFile.getBaseName()} but is not an object literal.`
+    );
+  }
+  return initializer;
+}
+function ensureConstCatalogEntry(sourceFile, spec) {
+  const matches = spec.equals ?? ((existing, candidate) => existing === candidate);
+  let literal = getConstCatalogLiteral(sourceFile, spec.catalogName);
+  if (!literal) {
+    sourceFile.insertVariableStatement(afterImports(sourceFile), {
+      isExported: true,
+      declarationKind: VariableDeclarationKind.Const,
+      declarations: [{ name: spec.catalogName, initializer: "{} as const" }]
+    });
+    literal = getConstCatalogLiteral(sourceFile, spec.catalogName);
+    if (!literal) {
+      throw new Error(`Failed to create catalog "${spec.catalogName}".`);
+    }
+    literal.addPropertyAssignment({
+      name: spec.key,
+      initializer: spec.initializer,
+      leadingTrivia: spec.leadingTrivia
+    });
+    return { key: spec.key, created: true };
+  }
+  for (const property of literal.getProperties().filter(Node.isPropertyAssignment)) {
+    const existingKey = unquote$1(property.getName());
+    const existingInitializer = property.getInitializerOrThrow().getText();
+    if (matches(existingInitializer, spec.initializer)) {
+      return { key: existingKey, created: false };
+    }
+    if (existingKey === spec.key) {
+      throw new Error(
+        `"${spec.catalogName}.${spec.key}" already exists with a different value (${existingInitializer}). Use a different methodName, or reconcile the catalog by hand.`
+      );
+    }
+  }
+  literal.addPropertyAssignment({
+    name: spec.key,
+    initializer: spec.initializer,
+    leadingTrivia: spec.leadingTrivia
+  });
+  return { key: spec.key, created: true };
+}
+function ensureExportedTypeAlias(sourceFile, spec) {
+  if (sourceFile.getTypeAlias(spec.name)) return false;
+  sourceFile.addTypeAlias({
+    name: spec.name,
+    type: spec.type,
+    isExported: true,
+    docs: spec.docs ? [spec.docs] : void 0
+  });
+  return true;
+}
+function ensureExportedMapper(sourceFile, spec) {
+  if (sourceFile.getVariableDeclaration(spec.name)) return false;
+  sourceFile.addVariableStatement({
+    isExported: true,
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [
+      {
+        name: spec.name,
+        initializer: `(raw: ${spec.rawType}): ${spec.dataType} => raw`
+      }
+    ]
+  });
+  return true;
+}
+function ensureBarrelExport(sourceFile, moduleSpecifier) {
+  const present = sourceFile.getExportDeclarations().some((d) => d.getModuleSpecifierValue() === moduleSpecifier);
+  if (present) return false;
+  sourceFile.addExportDeclaration({ moduleSpecifier });
+  return true;
+}
+function ensureNamedExports(sourceFile, moduleSpecifier, names, isTypeOnly = false) {
+  const existing = sourceFile.getExportDeclarations().find(
+    (d) => d.getModuleSpecifierValue() === moduleSpecifier && d.isTypeOnly() === isTypeOnly
+  );
+  if (!existing) {
+    sourceFile.addExportDeclaration({
+      moduleSpecifier,
+      isTypeOnly,
+      namedExports: names.map((name) => {
+        return { name };
+      })
+    });
+    return true;
+  }
+  const present = new Set(existing.getNamedExports().map((e) => e.getName()));
+  const missing = names.filter((name) => !present.has(name));
+  if (missing.length === 0) return false;
+  existing.addNamedExports(
+    missing.map((name) => {
+      return { name };
+    })
+  );
+  return true;
+}
+function ensureExportedInterface(sourceFile, name, properties = [], extendsTypes = []) {
+  if (sourceFile.getInterface(name)) return false;
+  sourceFile.addInterface({
+    name,
+    isExported: true,
+    extends: extendsTypes,
+    properties
+  });
+  return true;
+}
 function addDecoratedMethod(cls, spec) {
   if (cls.getMethod(spec.name)) return false;
   cls.addMethod({
     name: spec.name,
     isAsync: spec.isAsync,
     returnType: spec.returnType,
+    docs: spec.docs ? [spec.docs] : void 0,
     parameters: spec.parameters?.map((p) => {
       return { name: p.name, type: p.type, hasQuestionToken: p.optional };
     }),
@@ -1044,6 +1298,7 @@ function addDecoratedMethod(cls, spec) {
     decorators: [
       {
         name: spec.decoratorName,
+        typeArguments: spec.decoratorTypeArgs,
         arguments: spec.decoratorArgsText ? [spec.decoratorArgsText] : []
       }
     ]
@@ -1126,17 +1381,28 @@ function listServiceCatalog(codegenFs, query, projects) {
       app,
       version,
       serviceModulePath: posix,
-      operations: readOperations(codegenFs, openapiPath)
+      operations: readOperations(codegenFs, openapiPath) ?? []
     });
   }
   return entries.sort(
     (a, b) => a.app.localeCompare(b.app) || a.version.localeCompare(b.version)
   );
 }
+function readServiceModuleOperations(codegenFs, serviceModuleFile) {
+  const moduleFile = serviceModuleFile.endsWith(".ts") ? serviceModuleFile : `${serviceModuleFile}.ts`;
+  const posix = moduleFile.split(path.sep).join("/");
+  const openapiPath = posix.replace(/service\.ts$/, "openapi.d.ts");
+  for (const candidate of [openapiPath, posix]) {
+    if (!codegenFs.exists(candidate)) continue;
+    const operations = readOperations(codegenFs, candidate);
+    if (operations) return operations;
+  }
+  return null;
+}
 function readOperations(codegenFs, openapiPath) {
   return readSourceFile(codegenFs, openapiPath, (sf) => {
     const paths = sf.getInterface("paths");
-    if (!paths) return [];
+    if (!paths) return null;
     const operations = [];
     for (const pathProp of paths.getProperties()) {
       const servicePath = unquote(pathProp.getName());
@@ -1170,58 +1436,6 @@ function readSummary(methodProp) {
 function unquote(name) {
   return name.replace(/^["']|["']$/g, "");
 }
-const UPDATE_RELEASE_VERSION_SCRIPT = `import devkit from "@nx/devkit";
-import { resolve } from "path";
-import { readFileSync, writeFileSync } from "fs";
-import prettier from "prettier";
-
-// KOS artifact versioning: stamps the project's .kos.json "version" field
-// (which kabtool bakes into the KAB). Never touches package.json.
-// Driven by tag-based releases:
-//   nx run-many --target=version --args=--ver=$KOSBUILD_VERSION
-
-const { readCachedProjectGraph } = devkit;
-const [, , name, versionArg] = process.argv;
-
-// "{args.ver}" arrives literally when the target runs without --args=--ver=<v>;
-// treat that (or a missing arg) as "report current version, change nothing".
-const version =
-  versionArg && !versionArg.startsWith("{args") ? versionArg : undefined;
-
-if (!name) {
-  console.error("usage: update-release-version.mjs <project> <version>");
-  process.exit(1);
-}
-
-const graph = readCachedProjectGraph();
-const project = graph.nodes[name];
-if (!project) {
-  console.error("Unknown project: " + name);
-  process.exit(1);
-}
-
-const kosJsonPath = resolve(process.cwd(), project.data.root, ".kos.json");
-let kosJson;
-try {
-  kosJson = JSON.parse(readFileSync(kosJsonPath, "utf8"));
-} catch {
-  console.error("Missing or invalid .kos.json: " + kosJsonPath);
-  process.exit(1);
-}
-
-if (!version) {
-  console.log(name + ": " + kosJson.version + " (no --ver given; unchanged)");
-  process.exit(0);
-}
-
-const prettierOptions = await prettier.resolveConfig(kosJsonPath);
-const output = await prettier.format(
-  JSON.stringify({ ...kosJson, version }, null, 2),
-  { ...prettierOptions, parser: "json" }
-);
-writeFileSync(kosJsonPath, output);
-console.log(name + ": version -> " + version);
-`;
 function appendBarrelExport(codegenFs, indexPath, exportPath) {
   const exportLine = `export * from '${exportPath}'`;
   const content = codegenFs.read(indexPath) ?? "";
@@ -1268,10 +1482,57 @@ function updateModelIndex(codegenFs, indexPath, modelPath) {
   const newContents = printer.printFile(updatedSourceFile);
   codegenFs.write(indexPath, newContents);
 }
-function generateHook(codegenFs, templateDir, options, cwd, projects) {
-  if (!options.appProject) {
-    throw new Error("No app project specified");
+function generateCompanionModel(codegenFs, templateDir, options, projects) {
+  const logger = getCodegenLogger();
+  const normalized = normalizeAllValues({
+    companionModelName: options.companionModelName,
+    modelName: options.modelName
+  });
+  const companionChildKosConfig = getKosProjectConfiguration(
+    codegenFs,
+    options.companionModelProject,
+    projects
+  );
+  const parentProject = findProjectByName(
+    codegenFs.root,
+    options.modelProject,
+    projects
+  );
+  const childProject = findProjectByName(
+    codegenFs.root,
+    options.companionModelProject,
+    projects
+  );
+  const projectRoot = childProject?.sourceRoot;
+  if (!projectRoot) {
+    logger.warn(`Companion child project source root not found`);
+    return;
+  }
+  let importPath = "";
+  if (parentProject) {
+    const pkgJsonPath = path.join(parentProject.root, "package.json");
+    try {
+      const pkgJson = readJson(codegenFs, pkgJsonPath);
+      importPath = pkgJson.name || "";
+    } catch {
+      importPath = "";
+    }
   }
+  const modelLocation = companionChildKosConfig?.generator?.defaults?.model?.folder || "";
+  const filePath = path.join(
+    projectRoot,
+    modelLocation,
+    normalized.companionModelNameDashCase
+  );
+  logger.info(`Generating companion model in ${filePath}`);
+  generateFilesFromTemplates(codegenFs, templateDir, filePath, {
+    ...options,
+    ...normalized,
+    importPath
+  });
+}
+function generateContainerModel(codegenFs, templateDir, options, cwd, projects) {
+  const logger = getCodegenLogger();
   const currentProject = getProject(codegenFs, cwd);
   const modelProjectName = options.modelProject || currentProject?.name;
   if (!modelProjectName) {
@@ -1279,57 +1540,110 @@ function generateHook(codegenFs, templateDir, options, cwd, projects) {
       "No model project found. Please specify a model project with --modelProject."
     );
   }
-  const modelName = options.name || getCurrentDirectoryName(cwd);
+  const modelName = options.modelName || getCurrentDirectoryName(cwd);
   if (!modelName) {
     throw new Error(
       "No model name found. Please specify a model name with --name."
     );
   }
-  const kosModelConfig = getKosModelConfiguration(
-    codegenFs,
-    modelProjectName,
-    modelName,
-    projects
-  );
-  options.singleton = kosModelConfig ? !!kosModelConfig.singleton : false;
-  options.name = modelName;
-  options.modelProject = modelProjectName;
+  options.modelName = modelName;
+  options.name = `${modelName}-container`;
   const normalized = normalizeOptions(codegenFs, options, projects);
-  const appProject = findProjectByName(
+  const projectConfig = findProjectByName(
     codegenFs.root,
-    normalized.appProject,
+    normalized.modelProject,
     projects
   );
-  if (!appProject) {
-    throw new Error(`App project '${normalized.appProject}' not found`);
+  if (!projectConfig) {
+    throw new Error(`Model project '${normalized.modelProject}' not found`);
   }
+  addKosModelConfiguration({
+    codegenFs,
+    modelName: normalized.nameDashCase,
+    projectName: projectConfig.name,
+    projectRoot: projectConfig.root,
+    singleton: !!options.singleton,
+    container: true,
+    // The container's exported registration bean (`export const <ProperCase>`).
+    factory: normalized.nameProperCase
+  });
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
-    appProject.name,
+    projectConfig.name,
     projects
   );
-  const componentLocation = kosConfig?.generator?.defaults?.component?.folder || "";
-  options.appDirectory = options.appDirectory || componentLocation;
-  const projectRoot = appProject.sourceRoot;
+  const modelLocation = kosConfig?.generator?.defaults?.model?.folder || "";
+  const internal = !!kosConfig?.generator?.internal;
+  options.modelDirectory = options.modelDirectory || modelLocation;
+  const projectRoot = projectConfig.sourceRoot;
   if (projectRoot) {
-    generateFilesFromTemplates(
-      codegenFs,
-      templateDir,
-      path.join(
-        projectRoot,
-        options.appDirectory,
-        "hooks",
-        normalized.nameDashCase
-      ),
-      normalized
+    logger.info(
+      `Generating container model ${normalized.nameDashCase} in ${projectRoot}`
     );
-    appendBarrelExport(
-      codegenFs,
-      path.join(projectRoot, options.appDirectory, "hooks", "index.ts"),
-      `./${normalized.nameDashCase}`
+    const modelNameDashCase = normalized.modelNameDashCase || normalized.nameDashCase;
+    const modelFolder = path.join(
+      projectRoot,
+      options.modelDirectory || "",
+      modelNameDashCase
     );
+    if (options.existingModel) {
+      addContainerToExistingModelFolder(codegenFs, templateDir, modelFolder, {
+        ...normalized,
+        internal
+      });
+    } else {
+      generateFilesFromTemplates(
+        codegenFs,
+        path.join(templateDir, "model"),
+        modelFolder,
+        { ...normalized, internal }
+      );
+    }
+    const modelIndex = path.join(projectRoot, "index.ts");
+    const modelPath = normalized.modelDirectory ? `${normalized.modelDirectory}/${modelNameDashCase}` : modelNameDashCase;
+    updateModelIndex(codegenFs, modelIndex, modelPath);
   }
 }
+function addContainerToExistingModelFolder(codegenFs, templateDir, modelFolder, substitutions) {
+  const containerFileName = `${substitutions.nameDashCase}-model.ts`;
+  const containerTemplate = path.join(
+    templateDir,
+    "model",
+    "__nameDashCase__-model.ts.template"
+  );
+  const rendered = ejs.render(
+    fs.readFileSync(containerTemplate, "utf-8"),
+    substitutions,
+    { filename: containerTemplate }
+  );
+  codegenFs.write(path.join(modelFolder, containerFileName), rendered);
+  const typesPath = path.join(modelFolder, "types", "index.d.ts");
+  if (codegenFs.read(typesPath) === null) {
+    codegenFs.write(typesPath, "");
+  }
+  transformSourceFile(codegenFs, typesPath, (sourceFile) => {
+    ensureExportedInterface(
+      sourceFile,
+      `${substitutions.nameProperCase}Options`
+    );
+  });
+  const barrelPath = path.join(modelFolder, "index.ts");
+  if (codegenFs.read(barrelPath) === null) {
+    codegenFs.write(barrelPath, "");
+  }
+  transformSourceFile(codegenFs, barrelPath, (sourceFile) => {
+    const moduleSpecifier = `./${containerFileName.replace(/\.ts$/, "")}`;
+    ensureNamedExports(sourceFile, moduleSpecifier, [
+      substitutions.nameProperCase
+    ]);
+    ensureNamedExports(
+      sourceFile,
+      moduleSpecifier,
+      [`${substitutions.nameProperCase}Model`],
+      true
+    );
+  });
+}
 function generateContext(codegenFs, templateDir, options, cwd, projects) {
   if (!options.appProject) {
     throw new Error("No app project specified");
@@ -1382,8 +1696,10 @@ function generateContext(codegenFs, templateDir, options, cwd, projects) {
     );
   }
 }
-function generateContainerModel(codegenFs, templateDir, options, cwd, projects) {
-  const logger = getCodegenLogger();
+function generateHook(codegenFs, templateDir, options, cwd, projects) {
+  if (!options.appProject) {
+    throw new Error("No app project specified");
+  }
   const currentProject = getProject(codegenFs, cwd);
   const modelProjectName = options.modelProject || currentProject?.name;
   if (!modelProjectName) {
@@ -1391,120 +1707,56 @@ function generateContainerModel(codegenFs, templateDir, options, cwd, projects)
       "No model project found. Please specify a model project with --modelProject."
     );
   }
-  const modelName = options.modelName || getCurrentDirectoryName(cwd);
+  const modelName = options.name || getCurrentDirectoryName(cwd);
   if (!modelName) {
     throw new Error(
       "No model name found. Please specify a model name with --name."
     );
   }
-  options.modelName = modelName;
-  options.name = `${modelName}-container`;
+  const kosModelConfig = getKosModelConfiguration(
+    codegenFs,
+    modelProjectName,
+    modelName,
+    projects
+  );
+  options.singleton = kosModelConfig ? !!kosModelConfig.singleton : false;
+  options.name = modelName;
+  options.modelProject = modelProjectName;
   const normalized = normalizeOptions(codegenFs, options, projects);
-  const projectConfig = findProjectByName(
+  const appProject = findProjectByName(
     codegenFs.root,
-    normalized.modelProject,
+    normalized.appProject,
     projects
   );
-  if (!projectConfig) {
-    throw new Error(`Model project '${normalized.modelProject}' not found`);
+  if (!appProject) {
+    throw new Error(`App project '${normalized.appProject}' not found`);
   }
-  addKosModelConfiguration({
-    codegenFs,
-    modelName: normalized.nameDashCase,
-    projectName: projectConfig.name,
-    projectRoot: projectConfig.root,
-    singleton: !!options.singleton,
-    container: true,
-    // The container's exported registration bean (`export const <ProperCase>`).
-    factory: normalized.nameProperCase
-  });
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
-    projectConfig.name,
+    appProject.name,
     projects
   );
-  const modelLocation = kosConfig?.generator?.defaults?.model?.folder || "";
-  const internal = !!kosConfig?.generator?.internal;
-  options.modelDirectory = options.modelDirectory || modelLocation;
-  const projectRoot = projectConfig.sourceRoot;
+  const componentLocation = kosConfig?.generator?.defaults?.component?.folder || "";
+  options.appDirectory = options.appDirectory || componentLocation;
+  const projectRoot = appProject.sourceRoot;
   if (projectRoot) {
-    logger.info(
-      `Generating container model ${normalized.nameDashCase} in ${projectRoot}`
-    );
-    const modelNameDashCase = normalized.modelNameDashCase || normalized.nameDashCase;
     generateFilesFromTemplates(
       codegenFs,
-      path.join(templateDir, "model"),
-      path.join(projectRoot, options.modelDirectory || "", modelNameDashCase),
-      { ...normalized, internal }
+      templateDir,
+      path.join(
+        projectRoot,
+        options.appDirectory,
+        "hooks",
+        normalized.nameDashCase
+      ),
+      normalized
+    );
+    appendBarrelExport(
+      codegenFs,
+      path.join(projectRoot, options.appDirectory, "hooks", "index.ts"),
+      `./${normalized.nameDashCase}`
     );
-    if (options.dataServices) {
-      logger.info(`Generating data services for ${modelNameDashCase}`);
-      generateFilesFromTemplates(
-        codegenFs,
-        path.join(templateDir, "services"),
-        path.join(
-          projectRoot,
-          options.modelDirectory,
-          modelNameDashCase,
-          "services"
-        ),
-        { ...normalized, internal }
-      );
-    }
-    const modelIndex = path.join(projectRoot, "index.ts");
-    const modelPath = normalized.modelDirectory ? `${normalized.modelDirectory}/${modelNameDashCase}` : modelNameDashCase;
-    updateModelIndex(codegenFs, modelIndex, modelPath);
-  }
-}
-function generateCompanionModel(codegenFs, templateDir, options, projects) {
-  const logger = getCodegenLogger();
-  const normalized = normalizeAllValues({
-    companionModelName: options.companionModelName,
-    modelName: options.modelName
-  });
-  const companionChildKosConfig = getKosProjectConfiguration(
-    codegenFs,
-    options.companionModelProject,
-    projects
-  );
-  const parentProject = findProjectByName(
-    codegenFs.root,
-    options.modelProject,
-    projects
-  );
-  const childProject = findProjectByName(
-    codegenFs.root,
-    options.companionModelProject,
-    projects
-  );
-  const projectRoot = childProject?.sourceRoot;
-  if (!projectRoot) {
-    logger.warn(`Companion child project source root not found`);
-    return;
-  }
-  let importPath = "";
-  if (parentProject) {
-    const pkgJsonPath = path.join(parentProject.root, "package.json");
-    try {
-      const pkgJson = readJson(codegenFs, pkgJsonPath);
-      importPath = pkgJson.name || "";
-    } catch {
-      importPath = "";
-    }
   }
-  const modelLocation = companionChildKosConfig?.generator?.defaults?.model?.folder || "";
-  const filePath = path.join(
-    projectRoot,
-    modelLocation,
-    normalized.companionModelNameDashCase
-  );
-  logger.info(`Generating companion model in ${filePath}`);
-  generateFilesFromTemplates(codegenFs, templateDir, filePath, {
-    ...options,
-    ...normalized,
-    importPath
-  });
 }
 function generateModel(params) {
   const {
@@ -1552,19 +1804,6 @@ function generateModel(params) {
     path.join(projectRoot, options.modelDirectory, normalized.nameDashCase),
     { ...normalized, internal }
   );
-  if (normalized.dataServices) {
-    generateFilesFromTemplates(
-      codegenFs,
-      path.join(modelTemplateDir, "services"),
-      path.join(
-        projectRoot,
-        options.modelDirectory,
-        normalized.nameDashCase,
-        "services"
-      ),
-      { ...normalized, internal }
-    );
-  }
   const modelIndex = path.join(projectRoot, "index.ts");
   const modelPath = options.modelDirectory ? `${options.modelDirectory}/${normalized.nameDashCase}` : normalized.nameDashCase;
   updateModelIndex(codegenFs, modelIndex, modelPath);
@@ -1595,8 +1834,7 @@ function generateModel(params) {
         ...options,
         name: `${normalized.name}-container`,
         modelName: normalized.name,
-        singleton: normalized.isContainerSingleton,
-        dataServices: normalized.dataServices
+        singleton: normalized.isContainerSingleton
       },
       cwd,
       projects
@@ -1617,6 +1855,55 @@ function generateModel(params) {
     );
   }
 }
+const DECLARATION_MARKER = "@kosModel";
+function findModelDeclarationFile(codegenFs, searchRoot, typeIds) {
+  const wanted = new Set(typeIds.filter(Boolean));
+  if (wanted.size === 0) return null;
+  const matches = [];
+  for (const filePath of codegenFs.listFiles(searchRoot)) {
+    if (!filePath.endsWith(".ts") || filePath.endsWith(".d.ts")) continue;
+    const content = codegenFs.read(filePath);
+    if (!content || !content.includes(DECLARATION_MARKER)) continue;
+    const declared = readDeclaredModelType(codegenFs, filePath);
+    if (declared && wanted.has(declared)) matches.push(filePath);
+  }
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    throw new Error(
+      `Model type '${[...wanted].join("' / '")}' is declared in more than one file:
+` + matches.sort().map((c) => `  - ${c}`).join("\n") + `
+Pass modelPath to pick one.`
+    );
+  }
+  return matches[0];
+}
+function readDeclaredModelType(codegenFs, filePath) {
+  try {
+    return readSourceFile(codegenFs, filePath, (sf) => {
+      const cls = sf.getClasses().find((c) => c.getDecorator("kosModel"));
+      const arg = cls?.getDecorator("kosModel")?.getArguments()[0];
+      if (!arg) return void 0;
+      const inner = arg.getKindName() === "ObjectLiteralExpression" ? modelTypeIdProperty(arg.getText()) : arg.getText();
+      if (!inner) return void 0;
+      return resolveToStringLiteral(inner.trim(), sf.getFullText());
+    });
+  } catch {
+    return void 0;
+  }
+}
+function modelTypeIdProperty(objectText) {
+  const m = objectText.match(/\bmodelTypeId\s*:\s*([^,}]+)/);
+  return m ? m[1] : void 0;
+}
+function resolveToStringLiteral(expression, fileText) {
+  const literal = expression.match(/^["'`](.*)["'`]$/);
+  if (literal) return literal[1];
+  if (!/^[A-Za-z_$][\w$]*$/.test(expression)) return void 0;
+  const declared = fileText.match(
+    new RegExp(`\\b(?:const|let|var)\\s+${expression}\\s*(?::[^=]+)?=\\s*["'\`]([^"'\`]+)["'\`]`)
+  );
+  return declared ? declared[1] : void 0;
+}
 function resolveModelFilePath(codegenFs, query, projects) {
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
@@ -1651,14 +1938,23 @@ function resolveModelFilePath(codegenFs, query, projects) {
   if (codegenFs.exists(modelFilePath)) {
     return { modelFilePath, internal, sourceRoot };
   }
+  const searchRoot = path.join(sourceRoot, modelLocation);
   const discovered = findModelFileByName(
     codegenFs,
-    path.join(sourceRoot, modelLocation),
+    searchRoot,
     modelNameDashCase
   );
   if (discovered) {
     return { modelFilePath: discovered, internal, sourceRoot };
   }
+  const declaredType = kosConfig?.models?.[query.modelName]?.type;
+  const byDeclaration = findModelDeclarationFile(codegenFs, searchRoot, [
+    query.modelName,
+    ...declaredType ? [declaredType] : []
+  ]);
+  if (byDeclaration) {
+    return { modelFilePath: byDeclaration, internal, sourceRoot };
+  }
   return { modelFilePath, internal, sourceRoot };
 }
 function findModelFileByName(codegenFs, searchRoot, modelNameDashCase) {
@@ -1674,6 +1970,184 @@ Pass modelPath to pick one.`
   }
   return candidates[0];
 }
+function resolveChildModelType(codegenFs, query, projects) {
+  const childProject = query.childModelProject || query.modelProject;
+  const childType = `${properCase(query.childModel)}Model`;
+  if (childProject !== query.modelProject) {
+    const project = findProjectByName(codegenFs.root, childProject, projects);
+    const pkgJson = project ? readJson(
+      codegenFs,
+      path.join(project.root, "package.json")
+    ) : void 0;
+    return { childType, childTypeModule: pkgJson?.name };
+  }
+  const { modelFilePath: childFilePath } = resolveModelFilePath(
+    codegenFs,
+    { modelName: query.childModel, modelProject: childProject },
+    projects
+  );
+  const relative = path.relative(path.dirname(query.modelFilePath), childFilePath).replace(/\.ts$/, "");
+  return {
+    childType,
+    childTypeModule: relative.startsWith(".") ? relative : `./${relative}`
+  };
+}
+function generateViewModel(codegenFs, templateDir, options, cwd, projects) {
+  const logger = getCodegenLogger();
+  if (!options.name) {
+    throw new Error(
+      "No ViewModel name found. Please specify a name with --name."
+    );
+  }
+  const currentProject = getProject(codegenFs, cwd);
+  const modelProjectName = options.modelProject || currentProject?.name;
+  if (!modelProjectName) {
+    throw new Error(
+      "No model project found. Please specify a model project with --project."
+    );
+  }
+  const normalized = normalizeOptions(
+    codegenFs,
+    { ...options, modelProject: modelProjectName },
+    projects
+  );
+  const projectConfig = findProjectByName(
+    codegenFs.root,
+    modelProjectName,
+    projects
+  );
+  if (!projectConfig) {
+    throw new Error(`Model project '${modelProjectName}' not found`);
+  }
+  const kosConfig = getKosProjectConfiguration(
+    codegenFs,
+    projectConfig.name,
+    projects
+  );
+  const modelDirectory = options.modelDirectory || kosConfig?.generator?.defaults?.model?.folder || "";
+  const internal = !!kosConfig?.generator?.internal;
+  const projectRoot = projectConfig.sourceRoot || path.join(projectConfig.root, "src");
+  const viewModelFolder = path.join(
+    projectRoot,
+    modelDirectory,
+    normalized.nameDashCase
+  );
+  const viewModelFilePath = path.join(
+    viewModelFolder,
+    `${normalized.nameDashCase}-view-model.ts`
+  );
+  if (codegenFs.exists(viewModelFilePath)) {
+    logger.info(`ViewModel already exists: ${viewModelFilePath}`);
+    return { viewModelFilePath, created: false };
+  }
+  const resolved = (options.models || []).map(
+    (source) => resolveSourceModel(
+      codegenFs,
+      source,
+      viewModelFilePath,
+      modelProjectName,
+      projects
+    )
+  );
+  logger.info(
+    `Generating ViewModel ${normalized.nameDashCase} in ${projectRoot}`
+  );
+  const constructorParams = resolved.map(({ name, type }) => ({ name, type }));
+  generateFilesFromTemplates(codegenFs, templateDir, viewModelFolder, {
+    ...normalized,
+    internal,
+    typeId: options.typeId || normalized.nameDashCase,
+    devToolsEnabled: !!options.devToolsEnabled,
+    constructorParams,
+    constructorArgs: constructorParams.map((param) => param.name).join(", "),
+    modelImports: groupImports(resolved)
+  });
+  updateModelIndex(
+    codegenFs,
+    path.join(projectRoot, "index.ts"),
+    modelDirectory ? `${modelDirectory}/${normalized.nameDashCase}` : normalized.nameDashCase
+  );
+  return { viewModelFilePath, created: true };
+}
+function resolveSourceModel(codegenFs, source, viewModelFilePath, modelProject, projects) {
+  const sourceProject = source.project || modelProject;
+  if (sourceProject === modelProject) {
+    const { modelFilePath } = resolveModelFilePath(
+      codegenFs,
+      { modelName: source.model, modelProject: sourceProject },
+      projects
+    );
+    if (!codegenFs.exists(modelFilePath)) {
+      throw new Error(
+        `Model '${source.model}' not found in project '${sourceProject}' (looked for ${modelFilePath})`
+      );
+    }
+  } else if (!findProjectByName(codegenFs.root, sourceProject, projects)) {
+    throw new Error(`Model project '${sourceProject}' not found`);
+  }
+  const { childType, childTypeModule } = resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath: viewModelFilePath,
+      modelProject,
+      childModel: source.model,
+      childModelProject: sourceProject
+    },
+    projects
+  );
+  return {
+    name: camelCase(source.model),
+    type: childType,
+    module: childTypeModule
+  };
+}
+function groupImports(resolved) {
+  const byModule = /* @__PURE__ */ new Map();
+  for (const { type, module } of resolved) {
+    if (!module) continue;
+    const types = byModule.get(module);
+    if (!types) {
+      byModule.set(module, [type]);
+    } else if (!types.includes(type)) {
+      types.push(type);
+    }
+  }
+  return [...byModule].map(([module, types]) => ({ module, types }));
+}
+function modelBaseName(modelFilePath, modelName) {
+  const base = path.basename(modelFilePath);
+  const match = base.match(/^(.*)-model\.ts$/);
+  return match ? match[1] : modelName;
+}
+function servicesFilePathFor(modelFilePath, modelBase) {
+  return path.join(
+    path.dirname(modelFilePath),
+    "services",
+    `${modelBase}-services.ts`
+  );
+}
+function header$1(modelBase) {
+  return `/**
+ * Service layer for the ${modelBase} model: the endpoints it calls and the
+ * types derived from them. Standalone service functions for callers outside a
+ * model context belong here too.
+ */
+`;
+}
+function ensureServicesModule(codegenFs, modelFilePath, modelBase) {
+  const servicesFilePath = servicesFilePathFor(modelFilePath, modelBase);
+  if (!codegenFs.exists(servicesFilePath)) {
+    codegenFs.write(servicesFilePath, header$1(modelBase));
+  }
+  const barrelPath = path.join(path.dirname(servicesFilePath), "index.ts");
+  if (!codegenFs.exists(barrelPath)) {
+    codegenFs.write(barrelPath, "");
+  }
+  transformSourceFile(codegenFs, barrelPath, (sf) => {
+    ensureBarrelExport(sf, `./${modelBase}-services`);
+  });
+  return servicesFilePath;
+}
 function normalizeAddFutureOptions(codegenFs, options, projects) {
   const projectConfiguration = findProjectByName(
     codegenFs.root,
@@ -1708,8 +2182,7 @@ function normalizeAddFutureOptions(codegenFs, options, projects) {
     projects
   );
   const modelDirectory = path.dirname(modelFilePath);
-  const servicesDirectory = path.join(modelDirectory, "services");
-  const servicesFilePath = codegenFs.exists(servicesDirectory) ? path.join(servicesDirectory, `${nameDashCase}-services.ts`) : void 0;
+  const servicesFilePath = servicesFilePathFor(modelFilePath, nameDashCase);
   const registrationFilePath = path.join(
     modelDirectory,
     `${nameDashCase}-registration.ts`
@@ -1919,170 +2392,78 @@ class ModelFileTransformer {
     });
   }
 }
+const SDK_MODULE = "@kosdev-code/kos-ui-sdk";
 class ServiceFileTransformer {
-  constructor(codegenFs, options) {
-    this.codegenFs = codegenFs;
-    this.options = options;
-  }
-  codegenFs;
-  options;
-  transform() {
-    const { servicesFilePath } = this.options;
-    if (!servicesFilePath || !this.codegenFs.exists(servicesFilePath)) {
-      this.createServicesFile();
-      return;
-    }
-    let content = this.codegenFs.read(servicesFilePath);
-    content = this.addFutureImports(content);
-    content = this.addFutureService(content);
-    content = this.addProgressTypes(content);
-    this.codegenFs.write(servicesFilePath, content);
-  }
-  createServicesFile() {
-    const { servicesFilePath, nameProperCase, nameDashCase, nameLowerCase } = this.options;
-    if (!servicesFilePath) {
-      return;
-    }
-    const content = `import {
-  KosLog,
-  type ClientResponse,
-  type DeepRequired,
-  type ElementType,
-  type ServiceResponse,
-  type FutureResponse
-} from '@kosdev-code/kos-ui-sdk';
-
-import API, { type KosApi, type ApiPath } from '../../../utils/service';
-
-const log = KosLog.createLogger({name: "${nameDashCase}-service", group: "Services"});
-
-const SERVICE_PATH: ApiPath = "ENTER_SERVICE_PATH"
-export type ${nameProperCase}ClientResponse = ClientResponse<
-  KosApi,
-  typeof SERVICE_PATH,
-  'get'
->;
-export type ${nameProperCase}Response = DeepRequired<${nameProperCase}ClientResponse>;
-
-/**
- * @category Service
- * Retrieves the initial ${nameLowerCase} data.
- */
-export const get${nameProperCase} = async (): Promise<ServiceResponse<${nameProperCase}Response>> => {
-  log.debug('sending GET for ${nameLowerCase}');
-  return await API.get(SERVICE_PATH);
-};
-
-/**
- * @category Service - Future Operation
- * Placeholder for a long-running operation that returns a Future for progress tracking
- *
- * Replace this with your actual long-running service operation
- */
-export const perform${nameProperCase}Operation = async (): Promise<FutureResponse> => {
-  // TODO: Implement your long-running service operation here
-  // This should return a Future that can be tracked for progress
-
-  log.debug('starting long-running ${nameLowerCase} operation');
-
-  // Example pattern:
-  // return API.post(OPERATION_SERVICE_PATH, {
-  //   // operation parameters
-  // });
-
-  // Placeholder - replace with actual implementation
-  throw new Error('perform${nameProperCase}Operation not yet implemented');
-};
-
-// Additional Future-aware service types (add as needed)
-export type ${nameProperCase}OperationProgress = {
-  // Define your progress data structure here
-  stage: string;
-  percentComplete: number;
-  currentItem?: string;
-  totalItems?: number;
-};
-
-export type ${nameProperCase}OperationResult = {
-  // Define your operation result structure here
-  success: boolean;
-  message?: string;
-  data?: any;
-};
-`;
-    this.codegenFs.write(servicesFilePath, content);
-  }
-  addFutureImports(content) {
-    if (content.includes("FutureResponse")) {
-      return content;
-    }
-    const importRegex = /import {\s*([^}]*)\s*} from '@kosdev-code\/kos-ui-sdk';/;
-    const importMatch = content.match(importRegex);
-    if (importMatch) {
-      const existingImports = importMatch[1];
-      if (existingImports.includes("FutureResponse")) {
-        return content;
-      }
-      const cleanedImports = existingImports.trim().replace(/,\s*$/, "");
-      const newImports = cleanedImports ? `${cleanedImports},
-  type FutureResponse` : `type FutureResponse`;
-      const newImportStatement = `import {
-  ${newImports}
-} from '@kosdev-code/kos-ui-sdk';`;
-      return content.replace(importMatch[0], newImportStatement);
-    }
-    return content;
+  constructor(codegenFs, options) {
+    this.codegenFs = codegenFs;
+    this.options = options;
+  }
+  codegenFs;
+  options;
+  transform() {
+    const { modelFilePath, nameDashCase } = this.options;
+    if (!modelFilePath) return;
+    const servicesFilePath = ensureServicesModule(
+      this.codegenFs,
+      modelFilePath,
+      nameDashCase
+    );
+    transformSourceFile(this.codegenFs, servicesFilePath, (sf) => {
+      ensureNamedImport(sf, SDK_MODULE, [
+        { name: "KosLog" },
+        { name: "FutureResponse", isTypeOnly: true }
+      ]);
+      ensureModuleConst(sf, {
+        name: "log",
+        initializer: `KosLog.createLogger({ name: "${nameDashCase}-service", group: "Services" })`
+      });
+      this.addFutureOperation(sf);
+      this.addProgressTypes(sf);
+    });
   }
-  addFutureService(content) {
+  addFutureOperation(sf) {
     const { nameProperCase, nameLowerCase } = this.options;
-    if (content.includes(`perform${nameProperCase}Operation`)) {
-      return content;
-    }
-    const futureService = `
-/**
- * @category Service - Future Operation
- * Placeholder for a long-running operation that returns a Future for progress tracking
- *
- * Replace this with your actual long-running service operation
- */
-export const perform${nameProperCase}Operation = async (): Promise<FutureResponse> => {
-  // TODO: Implement your long-running service operation here
-  // This should return a Future that can be tracked for progress
-
-  log.debug('starting long-running ${nameLowerCase} operation');
-
-  // Example pattern:
-  // return API.post(OPERATION_SERVICE_PATH, {
-  //   // operation parameters
-  // });
-
-  // Placeholder - replace with actual implementation
-  throw new Error('perform${nameProperCase}Operation not yet implemented');
-};`;
-    return content + "\n" + futureService;
+    const name = `perform${nameProperCase}Operation`;
+    if (sf.getVariableDeclaration(name)) return;
+    sf.addVariableStatement({
+      isExported: true,
+      declarationKind: VariableDeclarationKind.Const,
+      declarations: [
+        {
+          name,
+          initializer: `async (): Promise<FutureResponse> => {
+  log.debug("starting long-running ${nameLowerCase} operation");
+  throw new Error("${name} not yet implemented");
+}`
+        }
+      ],
+      docs: [
+        {
+          description: `@category Service - Future Operation
+A long-running operation returning a Future for progress tracking. Replace the body with the real service call.`
+        }
+      ]
+    });
   }
-  addProgressTypes(content) {
+  addProgressTypes(sf) {
     const { nameProperCase } = this.options;
-    if (content.includes(`${nameProperCase}OperationProgress`)) {
-      return content;
-    }
-    const progressTypes = `
-// Additional Future-aware service types (add as needed)
-export type ${nameProperCase}OperationProgress = {
-  // Define your progress data structure here
+    ensureExportedTypeAlias(sf, {
+      name: `${nameProperCase}OperationProgress`,
+      type: `{
   stage: string;
   percentComplete: number;
   currentItem?: string;
   totalItems?: number;
-};
-
-export type ${nameProperCase}OperationResult = {
-  // Define your operation result structure here
+}`
+    });
+    ensureExportedTypeAlias(sf, {
+      name: `${nameProperCase}OperationResult`,
+      type: `{
   success: boolean;
   message?: string;
-  data?: any;
-};`;
-    return content + "\n" + progressTypes;
+  data?: unknown;
+}`
+    });
   }
 }
 class RegistrationFileTransformer {
@@ -2241,11 +2622,25 @@ function buildDecoratorArgs(options) {
 }
 function addContainerSupportToModel(codegenFs, options, projects) {
   const logger = getCodegenLogger();
-  const childType = options.childType?.trim() || "IKosDataModel";
   const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
   if (!codegenFs.exists(modelFilePath)) {
     throw new Error(`Model file not found: ${modelFilePath}`);
   }
+  const resolvedChild = options.childModel ? resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath,
+      modelProject: options.modelProject,
+      childModel: options.childModel,
+      childModelProject: options.childModelProject
+    },
+    projects
+  ) : {
+    childType: options.childType,
+    childTypeModule: options.childTypeModule
+  };
+  const childType = resolvedChild.childType?.trim() || "IKosDataModel";
+  const childTypeModule = resolvedChild.childTypeModule;
   logger.info(
     `Adding container support (<${childType}>) to model: ${options.modelName}`
   );
@@ -2257,6 +2652,10 @@ function addContainerSupportToModel(codegenFs, options, projects) {
     ]);
     if (childType === "IKosDataModel") {
       ensureNamedImport(sf, sdk, [{ name: "IKosDataModel", isTypeOnly: true }]);
+    } else if (childTypeModule) {
+      ensureNamedImport(sf, childTypeModule, [
+        { name: childType, isTypeOnly: true }
+      ]);
     }
     const cls = getModelClass(sf);
     const className = cls.getName();
@@ -2286,6 +2685,140 @@ function addContainerSupportToModel(codegenFs, options, projects) {
   });
   return { modelFilePath };
 }
+function addParentAwareToModel(codegenFs, options, projects) {
+  const logger = getCodegenLogger();
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  if (!codegenFs.exists(modelFilePath)) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  logger.info(`Adding parent awareness to model: ${options.modelName}`);
+  let optionsTypeName;
+  transformSourceFile(codegenFs, modelFilePath, (sf) => {
+    const sdk = resolveSdkModuleSpecifier(sf);
+    ensureNamedImport(sf, sdk, [{ name: "kosParentAware" }]);
+    const cls = getModelClass(sf);
+    addClassDecorator(cls, "kosParentAware", {
+      argsText: options.parentId ? `{ parentId: ${JSON.stringify(options.parentId)} }` : ""
+    });
+    const ctor = cls.getConstructors()[0];
+    optionsTypeName = ctor?.getParameters()[1]?.getTypeNode()?.getText()?.replace(/<.*$/, "");
+  });
+  const optionsFilePath = optionsTypeName ? extendOptionsInterface(codegenFs, modelFilePath, optionsTypeName, logger) : void 0;
+  return { modelFilePath, optionsFilePath };
+}
+function extendOptionsInterface(codegenFs, modelFilePath, optionsTypeName, logger) {
+  const typesPath = path.join(
+    path.dirname(modelFilePath),
+    "types",
+    "index.d.ts"
+  );
+  const target = codegenFs.exists(typesPath) ? typesPath : modelFilePath;
+  let extended = false;
+  transformSourceFile(codegenFs, target, (sf) => {
+    const iface = sf.getInterface(optionsTypeName);
+    if (!iface) return;
+    const already = iface.getExtends().some((clause) => clause.getText().includes("KosParentAware"));
+    if (already) {
+      extended = true;
+      return;
+    }
+    ensureNamedImport(sf, "@kosdev-code/kos-ui-sdk", [
+      { name: "KosParentAware", isTypeOnly: true }
+    ]);
+    iface.addExtends("KosParentAware");
+    extended = true;
+  });
+  if (!extended) {
+    logger.warn(
+      `Could not find interface ${optionsTypeName}; add "extends KosParentAware" to it by hand.`
+    );
+    return void 0;
+  }
+  return target;
+}
+function firstDecoratorArg(decoratorText) {
+  const open = decoratorText.indexOf("(");
+  if (open === -1) return void 0;
+  const inner = decoratorText.slice(open + 1, decoratorText.lastIndexOf(")")).replace(/\s+/g, " ").trim();
+  return inner || void 0;
+}
+function collectDecorated(cls, decoratorName) {
+  const members = [];
+  const visit = (name, decoratorTextOf, typeText) => {
+    const text = decoratorTextOf();
+    if (text === void 0) return;
+    members.push({
+      name,
+      arg: firstDecoratorArg(text),
+      type: typeText || void 0
+    });
+  };
+  for (const m of cls.getMethods()) {
+    const dec = m.getDecorator(decoratorName);
+    if (dec) {
+      visit(m.getName(), () => dec.getText(), m.getReturnTypeNode()?.getText());
+    }
+  }
+  for (const p of cls.getProperties()) {
+    const dec = p.getDecorator(decoratorName);
+    if (dec) {
+      visit(p.getName(), () => dec.getText(), p.getTypeNode()?.getText());
+    }
+  }
+  return members;
+}
+function describeModel(codegenFs, options, projects) {
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  const content = codegenFs.read(modelFilePath);
+  if (content === null) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sf = project.createSourceFile(modelFilePath, content, {
+    overwrite: true
+  });
+  let modelType;
+  const modelTypeDecl = sf.getVariableDeclaration("MODEL_TYPE");
+  if (modelTypeDecl) {
+    const init = modelTypeDecl.getInitializer()?.getText();
+    if (init) modelType = init.replace(/^["'`]|["'`]$/g, "");
+  }
+  const cls = sf.getClasses().find((c) => c.getDecorator("kosModel")) ?? sf.getClasses().find((c) => c.isExported()) ?? sf.getClasses()[0];
+  if (!cls) {
+    return {
+      modelFilePath,
+      modelType,
+      classDecorators: [],
+      singleton: false,
+      isCompanion: false,
+      children: [],
+      dependencies: [],
+      topicHandlers: [],
+      configProperties: [],
+      serviceRequests: [],
+      effects: [],
+      futures: []
+    };
+  }
+  const classDecorators = cls.getDecorators().map((d) => d.getName());
+  const kosModelArg = cls.getDecorator("kosModel") ? firstDecoratorArg(cls.getDecorator("kosModel").getText()) : void 0;
+  const singleton = /\bsingleton\s*:\s*true\b/.test(kosModelArg ?? "");
+  return {
+    modelFilePath,
+    modelType,
+    className: cls.getName(),
+    classDecorators,
+    singleton,
+    isCompanion: classDecorators.includes("kosCompanion"),
+    children: collectDecorated(cls, "kosChild"),
+    dependencies: collectDecorated(cls, "kosDependency"),
+    topicHandlers: collectDecorated(cls, "kosTopicHandler"),
+    configProperties: collectDecorated(cls, "kosConfigProperty"),
+    serviceRequests: collectDecorated(cls, "kosServiceRequest"),
+    effects: collectDecorated(cls, "kosModelEffect"),
+    futures: collectDecorated(cls, "kosFuture")
+  };
+}
 function addModelEffectToModel(codegenFs, options, projects) {
   const logger = getCodegenLogger();
   const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
@@ -2361,7 +2894,18 @@ function addChildToModel(codegenFs, options, projects) {
   logger.info(
     `Adding @kosChild "${options.propertyName}" (${shape}) to ${options.modelName}`
   );
-  const childType = options.childType?.trim();
+  const resolvedChild = options.childModel ? resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath,
+      modelProject: options.modelProject,
+      childModel: options.childModel,
+      childModelProject: options.childModelProject
+    },
+    projects
+  ) : { childType: options.childType, childTypeModule: options.childPackage };
+  const childType = resolvedChild.childType?.trim();
+  const childTypeModule = resolvedChild.childTypeModule;
   transformSourceFile(codegenFs, modelFilePath, (sf) => {
     const sdk = resolveSdkModuleSpecifier(sf);
     const sdkImports = [
@@ -2369,8 +2913,8 @@ function addChildToModel(codegenFs, options, projects) {
     ];
     if (shape === "container") sdkImports.push({ name: "KosModelContainer" });
     ensureNamedImport(sf, sdk, sdkImports);
-    if (options.childPackage && childType && /^[A-Za-z_$][\w$]*$/.test(childType) && !FRAMEWORK_TYPES.has(childType)) {
-      ensureNamedImport(sf, options.childPackage, [
+    if (childTypeModule && childType && /^[A-Za-z_$][\w$]*$/.test(childType) && !FRAMEWORK_TYPES.has(childType)) {
+      ensureNamedImport(sf, childTypeModule, [
         { name: childType, isTypeOnly: true }
       ]);
     }
@@ -2516,6 +3060,154 @@ function addComputedToModel(codegenFs, options, projects) {
   });
   return { modelFilePath };
 }
+function mocksFilePathFor(modelFilePath, modelBase) {
+  return path.join(
+    path.dirname(modelFilePath),
+    "mocks",
+    `${modelBase}-mocks.ts`
+  );
+}
+function mockRegisterFunctionName(modelBase) {
+  return `register${pascalCase(modelBase)}Mocks`;
+}
+function toMockRoutePattern(servicePath) {
+  return servicePath.replace(/\{([^}]+)\}/g, ":$1");
+}
+function mockRouteCall(method, pattern, body) {
+  const shorthand = {
+    get: "get",
+    post: "post",
+    put: "put",
+    delete: "del"
+  };
+  const fn = shorthand[method];
+  return fn ? `KosMock.${fn}(${JSON.stringify(pattern)}, ${body});` : `KosMock.route(${JSON.stringify(method.toUpperCase())}, ${JSON.stringify(
+    pattern
+  )}, ${body});`;
+}
+function header(modelBase, registerFn) {
+  return `/**
+ * KosMock routes for the ${modelBase} model's PROVISIONAL endpoints — the ones
+ * this project's generated OpenAPI types do not declare.
+ *
+ * NOTHING IMPORTS THIS FILE. Call \`${registerFn}()\` from the app's dev entry,
+ * gated so it cannot run in a production build (\`import.meta.env.DEV\`, a
+ * dev-only entry module, or behind your own switch). Registering a route enables
+ * KosMock, and a mock that shipped would shadow the real endpoint once it exists.
+ *
+ * Unmatched requests still pass through to the real device (KosMock's hybrid
+ * default), so these routes shadow only the paths named below. Every mocked
+ * response carries the \`kos-mocked: true\` wire header, so mock-fed data is
+ * identifiable in devtools.
+ *
+ * DELETE THIS FILE once every endpoint below is in the generated types.
+ */
+`;
+}
+function ensureMockRoute(codegenFs, options) {
+  const mocksFilePath = mocksFilePathFor(
+    options.modelFilePath,
+    options.modelBase
+  );
+  const registerFunction = mockRegisterFunctionName(options.modelBase);
+  const routePattern = toMockRoutePattern(options.servicePath);
+  const sampleName = `SAMPLE_${constantCase(dashCase(options.endpointKey))}`;
+  const samplePlaceholder = !options.sampleText;
+  if (!codegenFs.exists(mocksFilePath)) {
+    codegenFs.write(mocksFilePath, header(options.modelBase, registerFunction));
+  }
+  const sdkSpecifier = options.sdkModuleSpecifier.startsWith(".") ? `../${options.sdkModuleSpecifier}` : options.sdkModuleSpecifier;
+  let routeCreated = false;
+  transformSourceFile(codegenFs, mocksFilePath, (sf) => {
+    ensureNamedImport(sf, sdkSpecifier, [{ name: "KosMock" }]);
+    ensureNamedImport(sf, "../services", [
+      { name: options.rawAlias, isTypeOnly: true }
+    ]);
+    ensureSample(sf, {
+      name: sampleName,
+      type: options.rawAlias,
+      servicePath: options.servicePath,
+      method: options.method,
+      sampleText: options.sampleText
+    });
+    const statement = mockRouteCall(
+      options.method,
+      routePattern,
+      `{ data: ${sampleName} }`
+    );
+    routeCreated = ensureRegisteredRoute(sf, {
+      registerFunction,
+      modelBase: options.modelBase,
+      statement,
+      // Matching on the pattern literal alone would collide across methods.
+      marker: `${options.method.toUpperCase()} ${routePattern}`,
+      matches: (existing) => existing.includes(JSON.stringify(routePattern)) && existing.includes(shorthandOrMethod(options.method))
+    });
+  });
+  return {
+    mocksFilePath,
+    registerFunction,
+    routePattern,
+    sampleName,
+    routeCreated,
+    samplePlaceholder
+  };
+}
+function shorthandOrMethod(method) {
+  const shorthand = {
+    get: "KosMock.get(",
+    post: "KosMock.post(",
+    put: "KosMock.put(",
+    delete: "KosMock.del("
+  };
+  return shorthand[method] ?? `"${method.toUpperCase()}"`;
+}
+function ensureSample(sf, spec) {
+  if (sf.getVariableDeclaration(spec.name)) return;
+  const lines = [
+    `Sample payload for \`${spec.method.toUpperCase()} ${spec.servicePath}\` — the`,
+    "UNWRAPPED `data` payload, i.e. exactly what the transform receives."
+  ];
+  if (!spec.sampleText) {
+    lines.push(
+      "",
+      "TODO: replace the placeholder with something the backend would actually",
+      "serve. Until then the route answers with nothing and the transform is",
+      "never exercised."
+    );
+  }
+  const docs = lines.join("\n");
+  sf.addVariableStatement({
+    isExported: true,
+    declarationKind: VariableDeclarationKind.Const,
+    docs: [docs],
+    declarations: [
+      {
+        name: spec.name,
+        type: spec.type,
+        initializer: spec.sampleText ?? `null as unknown as ${spec.type}`
+      }
+    ]
+  });
+}
+function ensureRegisteredRoute(sf, spec) {
+  let fn = sf.getFunction(spec.registerFunction);
+  if (!fn) {
+    fn = sf.addFunction({
+      name: spec.registerFunction,
+      isExported: true,
+      returnType: "void",
+      docs: [
+        `Arm the ${spec.modelBase} model's provisional endpoints. Call this from a dev-only entry point — never from code that ships.`
+      ]
+    });
+  }
+  const already = fn.getStatements().some((statement) => spec.matches(statement.getText()));
+  if (already) return false;
+  fn.addStatements(`// ${spec.marker}
+${spec.statement}`);
+  return true;
+}
 const SERVICE_MODULE_RE = /\/utils\/services\/.*\/service\.ts$/;
 function findServiceModules(codegenFs, sourceRoot) {
   return codegenFs.listFiles(sourceRoot).filter((f) => SERVICE_MODULE_RE.test(f.split(path.sep).join("/")));
@@ -2525,6 +3217,143 @@ function toImportSpecifier(fromFile, toFileNoExt) {
   if (!rel.startsWith(".")) rel = `./${rel}`;
   return rel;
 }
+function fromImportSpecifier(fromFile, specifier) {
+  return path.join(path.dirname(fromFile), specifier);
+}
+function assertServiceModuleAcceptsTransform(codegenFs, serviceModuleFile, modelProject) {
+  const file = `${serviceModuleFile}.ts`;
+  if (!codegenFs.exists(file)) return;
+  const typeParams = readSourceFile(codegenFs, file, (sf) => {
+    const alias = sf.getTypeAlias("EndpointCtx");
+    return alias ? alias.getTypeParameters().length : null;
+  });
+  if (typeParams === null || typeParams >= 2) return;
+  throw new Error(
+    `${file} predates the transform-aware service layer (EndpointCtx takes ${typeParams} type parameter). Run \`kosui api:generate --project ${modelProject} --helpers-only\` to refresh the helper layer in place (no spec fetch, openapi.d.ts untouched), then add the service request.`
+  );
+}
+function assertServiceModuleAcceptsProvisional(codegenFs, serviceModuleFile, modelProject) {
+  const file = `${serviceModuleFile}.ts`;
+  if (!codegenFs.exists(file)) return;
+  const declared = readSourceFile(
+    codegenFs,
+    file,
+    (sf) => Boolean(sf.getFunction("provisionalServiceRequest"))
+  );
+  if (declared) return;
+  throw new Error(
+    `${file} has no \`provisionalServiceRequest\` — the helper layer predates provisional endpoints. Run \`kosui api:generate --project ${modelProject} --helpers-only\` to refresh it in place (no spec fetch, openapi.d.ts untouched), then add the service request.`
+  );
+}
+function sameEndpoint(existing, candidate) {
+  const args = (text) => {
+    const match = text.match(
+      /^endpoint\s*\(\s*(['"])(.*?)\1(?:\s+as\s+ApiPath)?\s*,\s*(['"])(.*?)\3\s*,?\s*\)$/
+    );
+    return match ? [match[2], match[4].toLowerCase()] : null;
+  };
+  const a = args(existing.trim());
+  const b = args(candidate.trim());
+  return !!a && !!b && a[0] === b[0] && a[1] === b[1];
+}
+function editDistance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    previous = current;
+  }
+  return previous[b.length];
+}
+const NEAREST_SHOWN = 5;
+function provisionalEntryComment(servicePath, method, catalogName) {
+  return `/**
+ * PROVISIONAL — \`${method.toUpperCase()} ${servicePath}\` is NOT in this project's
+ * generated OpenAPI types. \`as ApiPath\` is standing in for a \`paths\` entry that
+ * does not exist, so nothing about this endpoint is checked against a spec and
+ * its response cannot be derived from one. Do not read this as a real endpoint.
+ *
+ * WHEN THE ENDPOINT LANDS:
+ *   1. regenerate this project's API types (\`kosui api:generate\`)
+ *   2. delete \` as ApiPath\` from the entry below
+ *   3. point the endpoint's \`…Raw\` alias at
+ *      \`EndpointResponse<typeof ${catalogName}.…>\`
+ *   4. swap \`provisionalServiceRequest\` for \`serviceRequest\` in the model
+ *   5. delete the model's \`mocks/\` module
+ *   6. KEEP the transform — it is real code and survives all of the above
+ */
+`;
+}
+function provisionalMethodDocs(servicePath, method) {
+  return [
+    `PROVISIONAL — \`${method.toUpperCase()} ${servicePath}\` is not in the`,
+    "generated OpenAPI types, so this request is served by a KosMock route, not",
+    "by the device. The feature it backs is NOT complete: report the missing",
+    "endpoint rather than treating this as finished.",
+    "",
+    "See the endpoint's entry in `./services` for what to undo when it lands."
+  ].join("\n");
+}
+function rawTypeDocs(servicePath, method, rawType) {
+  const shape = rawType ? [
+    "Stated by hand and unverified: there is no spec entry to check it",
+    "against."
+  ] : [
+    "TODO: state the shape the backend is expected to serve. `unknown`",
+    "compiles, but leaves the response boundary undescribed and the",
+    "transform with nothing to narrow."
+  ];
+  return [
+    `Raw wire shape of \`${method.toUpperCase()} ${servicePath}\` — the UNWRAPPED`,
+    "`data` payload, since the client strips the `{status, data}` envelope",
+    "before the transform runs.",
+    "",
+    ...shape,
+    "",
+    "Replace with `EndpointResponse<…>` once the endpoint is in the generated",
+    "types."
+  ].join("\n");
+}
+function removalSteps(spec) {
+  return [
+    `Regenerate the API types for ${spec.modelProject} (generate_api_types), and confirm ${spec.method.toUpperCase()} ${spec.servicePath} is now in them.`,
+    `In ${spec.servicesFilePath}: delete \` as ApiPath\` from \`${spec.catalogName}.${spec.endpointKey}\`.`,
+    `In ${spec.servicesFilePath}: point the endpoint's \`…Raw\` alias at \`EndpointResponse<typeof ${spec.catalogName}.${spec.endpointKey}>\` and drop the hand-written shape.`,
+    `In the model: swap \`provisionalServiceRequest\` for \`serviceRequest\` and drop its explicit type arguments — the response type comes from the spec again.`,
+    spec.mocksFilePath ? `Delete ${spec.mocksFilePath} (and the call to its register function in the app) once no provisional endpoint is left in it.` : `Delete the model's mocks module once no provisional endpoint is left in it.`,
+    `KEEP \`${spec.mapperName}\` and the data type it produces. The transform is real code; it is what let the model read the final shape all along.`
+  ];
+}
+function untypedEndpointError(spec) {
+  const methodsForPath = spec.operations.filter((op) => op.path === spec.servicePath).map((op) => op.method);
+  const pathTypedForOtherMethods = methodsForPath.length > 0;
+  const nearest = [...new Set(spec.operations.map((op) => op.path))].sort(
+    (a, b) => editDistance(a, spec.servicePath) - editDistance(b, spec.servicePath)
+  ).slice(0, NEAREST_SHOWN);
+  const waysForward = [
+    `The endpoint EXISTS on the device but this project has not pulled types for it: re-run api:generate (generate_api_types) for ${spec.modelProject}, then add the request unchanged. Confirm on the device first — kos-device search_services / describe_endpoint — since the live OpenAPI is what says whether it exists.`,
+    `The endpoint DOES NOT EXIST yet: pass mock:"auto" (the default) or mock:"always" to emit the provisional, mock-backed form — real decorator, lifecycle, error-first handler and transform, with a KosMock route standing in for the wire response.`,
+    `What is NOT supported: falling back to resolveServiceUrl / ServiceFactory.build / getAll to make the UI render. That compiles and looks finished, which is worse than the hole. A missing endpoint is a blocker to report, not a licence to route around the generated service layer.`
+  ];
+  const message = pathTypedForOtherMethods ? `${spec.method.toUpperCase()} ${spec.servicePath} is not in the generated OpenAPI types for ${spec.modelProject} — the path is typed, but only for: ${methodsForPath.map((m) => m.toUpperCase()).join(", ")}.` : `${spec.method.toUpperCase()} ${spec.servicePath} is not in the generated OpenAPI types for ${spec.modelProject} — the path is absent entirely. Nothing was written.`;
+  const error = new Error(message);
+  error.details = {
+    servicePath: spec.servicePath,
+    method: spec.method,
+    pathTypedForOtherMethods,
+    methodsForPath,
+    otherEndpointsInThisApi: nearest,
+    warning: "These are OTHER endpoints in this API, listed only so they can be ruled out — they are almost certainly NOT what you want. Do not substitute one for the requested path because the strings look similar.",
+    waysForward
+  };
+  return error;
+}
 function addServiceRequestToModel(codegenFs, options, projects) {
   const logger = getCodegenLogger();
   const { modelFilePath, sourceRoot } = resolveModelFilePath(
@@ -2535,14 +3364,15 @@ function addServiceRequestToModel(codegenFs, options, projects) {
   if (!codegenFs.exists(modelFilePath)) {
     throw new Error(`Model file not found: ${modelFilePath}`);
   }
-  let serviceImport = options.serviceModule;
-  if (!serviceImport && options.serviceModulePath) {
-    serviceImport = toImportSpecifier(
+  let serviceModuleFile;
+  if (options.serviceModulePath) {
+    serviceModuleFile = options.serviceModulePath.replace(/\.ts$/, "");
+  } else if (options.serviceModule) {
+    serviceModuleFile = fromImportSpecifier(
       modelFilePath,
-      options.serviceModulePath.replace(/\.ts$/, "")
+      options.serviceModule
     );
-  }
-  if (!serviceImport) {
+  } else {
     if (!sourceRoot) {
       throw new Error(
         "Cannot auto-resolve the service module without a project source root. Pass serviceModule."
@@ -2554,68 +3384,177 @@ function addServiceRequestToModel(codegenFs, options, projects) {
         "No generated service module found. Run `kosui api:generate` for this project first."
       );
     }
-    const specifiers = modules.map(
-      (m) => toImportSpecifier(modelFilePath, m.replace(/\.ts$/, ""))
-    );
     if (modules.length > 1) {
+      const specifiers = modules.map(
+        (m) => toImportSpecifier(modelFilePath, m.replace(/\.ts$/, ""))
+      );
       throw new Error(
         `Multiple service modules found — pass serviceModule (one of): ${specifiers.join(
           ", "
         )}`
       );
     }
-    serviceImport = specifiers[0];
+    serviceModuleFile = modules[0].replace(/\.ts$/, "");
   }
-  const method = options.method || "get";
+  assertServiceModuleAcceptsTransform(
+    codegenFs,
+    serviceModuleFile,
+    options.modelProject
+  );
+  const modelBase = modelBaseName(modelFilePath, options.modelName);
+  const servicesFilePath = servicesFilePathFor(modelFilePath, modelBase);
+  const serviceImportFromModel = toImportSpecifier(
+    modelFilePath,
+    serviceModuleFile
+  );
+  const serviceImportFromServices = toImportSpecifier(
+    servicesFilePath,
+    serviceModuleFile
+  );
+  const method = (options.method || "get").toLowerCase();
   const mode = options.mode ?? (options.lifecycle ? "lifecycle" : "method");
   const lifecycle = options.lifecycle || "LOAD";
+  const catalogName = `${pascalCase(modelBase)}Endpoints`;
+  const mockMode = options.mock ?? "auto";
+  const operations = readServiceModuleOperations(codegenFs, serviceModuleFile);
+  const pathValidated = operations !== null;
+  const operationTyped = operations === null || operations.some(
+    (op) => op.path === options.servicePath && op.method === method
+  );
+  if (!operationTyped && mockMode === "never") {
+    throw untypedEndpointError({
+      servicePath: options.servicePath,
+      method,
+      modelProject: options.modelProject,
+      operations: operations ?? []
+    });
+  }
+  const provisional = !operationTyped;
+  const writeMock = provisional || mockMode === "always";
+  if (provisional) {
+    assertServiceModuleAcceptsProvisional(
+      codegenFs,
+      serviceModuleFile,
+      options.modelProject
+    );
+  }
   logger.info(
-    `Adding ${mode}-driven @kosServiceRequest "${options.methodName}" (${method} ${options.servicePath}) to ${options.modelName}`
+    `Adding ${mode}-driven ${provisional ? "PROVISIONAL " : ""}@kosServiceRequest "${options.methodName}" (${method} ${options.servicePath}) to ${options.modelName}`
   );
+  if (provisional) {
+    logger.warn(
+      `${method.toUpperCase()} ${options.servicePath} is not in ${options.modelProject}'s generated OpenAPI types — emitting the provisional, mock-backed form. The feature is NOT complete until the endpoint lands.`
+    );
+  }
+  ensureServicesModule(codegenFs, modelFilePath, modelBase);
+  let endpointKey = options.methodName;
+  let endpointCreated = true;
+  let dataAlias = "";
+  let mapperName = "";
+  let ctxAlias = "";
+  let rawAlias = "";
+  transformSourceFile(codegenFs, servicesFilePath, (sf) => {
+    ensureNamedImport(sf, serviceImportFromServices, [{ name: "endpoint" }]);
+    if (provisional) {
+      ensureNamedImport(sf, serviceImportFromServices, [
+        { name: "ApiPath", isTypeOnly: true }
+      ]);
+    }
+    const pathText = provisional ? `${JSON.stringify(options.servicePath)} as ApiPath` : JSON.stringify(options.servicePath);
+    const entry = ensureConstCatalogEntry(sf, {
+      catalogName,
+      key: options.methodName,
+      initializer: `endpoint(${pathText}, ${JSON.stringify(method)})`,
+      equals: sameEndpoint,
+      leadingTrivia: provisional ? provisionalEntryComment(options.servicePath, method, catalogName) : void 0
+    });
+    endpointKey = entry.key;
+    endpointCreated = entry.created;
+    dataAlias = `${pascalCase(endpointKey)}Data`;
+    mapperName = `to${pascalCase(endpointKey)}Data`;
+    ctxAlias = `${pascalCase(endpointKey)}Ctx`;
+    rawAlias = `${pascalCase(endpointKey)}Raw`;
+    let rawType;
+    if (provisional) {
+      ensureExportedTypeAlias(sf, {
+        name: rawAlias,
+        type: options.rawType || "unknown",
+        docs: rawTypeDocs(options.servicePath, method, options.rawType)
+      });
+      rawType = rawAlias;
+    } else {
+      rawType = `EndpointResponse<typeof ${catalogName}.${endpointKey}>`;
+      ensureNamedImport(sf, serviceImportFromServices, [
+        { name: "EndpointResponse", isTypeOnly: true }
+      ]);
+      if (writeMock) {
+        ensureExportedTypeAlias(sf, {
+          name: rawAlias,
+          type: rawType,
+          docs: `Raw wire shape of \`${method.toUpperCase()} ${options.servicePath}\`, as the spec declares it — what a mock for this endpoint must serve.`
+        });
+      }
+    }
+    ensureExportedTypeAlias(sf, { name: dataAlias, type: rawType });
+    ensureExportedMapper(sf, {
+      name: mapperName,
+      rawType,
+      dataType: dataAlias
+    });
+    if (mode === "method") {
+      ensureNamedImport(sf, serviceImportFromServices, [
+        { name: "EndpointCtx", isTypeOnly: true }
+      ]);
+      ensureExportedTypeAlias(sf, {
+        name: ctxAlias,
+        type: `EndpointCtx<typeof ${catalogName}.${endpointKey}, ${dataAlias}>`
+      });
+    }
+  });
   transformSourceFile(codegenFs, modelFilePath, (sf) => {
-    const endpointConst = endpointConstName(options.methodName);
     const className = getModelClass(sf).getName();
     if (!className) throw new Error("Model class has no name.");
     const typeParams = getModelClass(sf).getTypeParameters().map((tp) => tp.getText());
-    ensureNamedImport(sf, serviceImport, [
-      { name: "endpoint" },
-      { name: "serviceRequest" }
-    ]);
-    ensureModuleConst(sf, {
-      name: endpointConst,
-      initializer: `endpoint(${JSON.stringify(
-        options.servicePath
-      )}, ${JSON.stringify(method)})`
-    });
+    const decoratorName = provisional ? "provisionalServiceRequest" : "serviceRequest";
+    const decoratorTypeArgs = provisional ? [rawAlias, dataAlias] : void 0;
+    ensureNamedImport(sf, serviceImportFromModel, [{ name: decoratorName }]);
     if (mode === "lifecycle") {
-      ensureNamedImport(sf, serviceImport, [
-        { name: "EndpointResponse", isTypeOnly: true }
+      ensureNamedImport(sf, "./services", [
+        { name: catalogName },
+        { name: mapperName },
+        { name: dataAlias, isTypeOnly: true },
+        ...provisional ? [{ name: rawAlias, isTypeOnly: true }] : []
       ]);
       ensureNamedImport(sf, resolveSdkModuleSpecifier(sf), [
         { name: "DependencyLifecycle" }
       ]);
       addDecoratedMethod(getModelClass(sf), {
         name: options.methodName,
-        decoratorName: "serviceRequest",
-        decoratorArgsText: `${endpointConst}, { lifecycle: DependencyLifecycle.${lifecycle} }`,
+        decoratorName,
+        decoratorTypeArgs,
+        decoratorArgsText: `${catalogName}.${endpointKey}, { lifecycle: DependencyLifecycle.${lifecycle}, transform: ${mapperName} }`,
+        docs: provisional ? provisionalMethodDocs(options.servicePath, method) : void 0,
         // The manager invokes phase handlers error-first, passing (null, data)
         // on success. The `error` half is only ever reached because
         // `serviceRequest` supplies an errorHandler — the bare decorator
         // defaults to `throw`, which fails the phase instead of calling back.
         parameters: [
           { name: "error", type: "string | null" },
-          {
-            name: "data",
-            type: `EndpointResponse<typeof ${endpointConst}>`
-          }
+          { name: "data", type: dataAlias }
         ],
         returnType: "void",
         statements: "// TODO: apply `data` to the model"
       });
       return;
     }
-    ensureNamedImport(sf, serviceImport, [
-      { name: "EndpointCtx", isTypeOnly: true }
+    ensureNamedImport(sf, "./services", [
+      { name: catalogName },
+      { name: mapperName },
+      { name: ctxAlias, isTypeOnly: true },
+      ...provisional ? [
+        { name: rawAlias, isTypeOnly: true },
+        { name: dataAlias, isTypeOnly: true }
+      ] : []
     ]);
     ensureNamedImport(sf, resolveSdkModuleSpecifier(sf), [
       { name: "executeServiceRequest" },
@@ -2630,16 +3569,12 @@ function addServiceRequestToModel(codegenFs, options, projects) {
     addClassDecorator(getModelClass(sf), "kosLoggerAware", { argsText: "" });
     addDecoratedMethod(getModelClass(sf), {
       name: options.methodName,
-      decoratorName: "serviceRequest",
-      decoratorArgsText: endpointConst,
+      decoratorName,
+      decoratorTypeArgs,
+      decoratorArgsText: `${catalogName}.${endpointKey}, { transform: ${mapperName} }`,
+      docs: provisional ? provisionalMethodDocs(options.servicePath, method) : void 0,
       // Optional: the framework appends the context, callers never pass it.
-      parameters: [
-        {
-          name: "$ctx",
-          type: `EndpointCtx<typeof ${endpointConst}>`,
-          optional: true
-        }
-      ],
+      parameters: [{ name: "$ctx", type: ctxAlias, optional: true }],
       isAsync: true,
       returnType: "Promise<void>",
       statements: [
@@ -2649,169 +3584,43 @@ function addServiceRequestToModel(codegenFs, options, projects) {
       ].join("\n")
     });
   });
-  return { modelFilePath, serviceModule: serviceImport, mode };
-}
-function endpointConstName(methodName) {
-  const snake = methodName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").toUpperCase();
-  return `ENDPOINT_${snake}`;
-}
-function modelElementType(typeText) {
-  let m;
-  if (m = typeText.match(/^([A-Za-z_]\w*Model)\s*\[\]$/)) return m[1];
-  if (m = typeText.match(/^Array<\s*([A-Za-z_]\w*Model)\s*>$/)) return m[1];
-  if (m = typeText.match(/^(?:Map|Set)<[^>]*?\b([A-Za-z_]\w*Model)\b[^>]*>$/))
-    return m[1];
-  return null;
-}
-function validateModel(codegenFs, options, projects) {
-  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
-  const content = codegenFs.read(modelFilePath);
-  if (content === null) {
-    throw new Error(`Model file not found: ${modelFilePath}`);
-  }
-  const project = new Project({ useInMemoryFileSystem: true });
-  const sf = project.createSourceFile(modelFilePath, content, {
-    overwrite: true
-  });
-  const findings = [];
-  const hasKosModel = sf.getClasses().some((c) => c.getDecorator("kosModel"));
-  if (!hasKosModel) {
-    findings.push({
-      level: "error",
-      rule: "missing-kosModel",
-      message: "No @kosModel decorator found — this is not a KOS model."
-    });
-  }
-  const imports = sf.getImportDeclarations();
-  const mobxImport = imports.find(
-    (d) => /^mobx(-react-lite)?$/.test(d.getModuleSpecifierValue())
-  );
-  if (mobxImport) {
-    findings.push({
-      level: "error",
-      rule: "mobx-import",
-      message: "Imports mobx directly. Reactivity is internal to KOS — remove the mobx import and use KOS reactivity / container models."
-    });
-  }
-  const barrelServiceRequest = imports.find(
-    (d) => d.getModuleSpecifierValue() === "@kosdev-code/kos-ui-sdk" && d.getNamedImports().some((n) => n.getName() === "kosServiceRequest")
-  );
-  if (barrelServiceRequest) {
-    findings.push({
-      level: "warning",
-      rule: "untyped-service-request",
-      message: "kosServiceRequest imported from the SDK barrel. Use the typed decorator from the api:generate'd service module so paths are validated against the OpenAPI types."
-    });
-  }
-  for (const cls of sf.getClasses()) {
-    for (const prop of cls.getProperties()) {
-      const name = prop.getName();
-      const typeText = (prop.getTypeNode()?.getText() ?? "").replace(/\s+/g, " ").trim();
-      const initText = prop.getInitializer()?.getText() ?? "";
-      const hasChild = !!prop.getDecorator("kosChild");
-      const isModelContainer = /\bI?KosModelContainer\s*</.test(typeText) || /new\s+KosModelContainer\b/.test(initText);
-      if (isModelContainer && !hasChild) {
-        findings.push({
-          level: "warning",
-          rule: "container-missing-kosChild",
-          message: `Property '${name}' is a model container but is not marked @kosChild — add @kosChild so its models join the model graph and lifecycle.`
-        });
-        continue;
-      }
-      const elem = modelElementType(typeText);
-      if (elem && !isModelContainer) {
-        findings.push({
-          level: "warning",
-          rule: "raw-model-collection",
-          message: `Property '${name}' is a raw ${typeText} of models — prefer a KosModelContainer<${elem}> (indexing, sorting, lifecycle, delta handling) marked @kosChild.`
-        });
-      }
-    }
-  }
-  const hasError = findings.some((f) => f.level === "error");
-  return { modelFilePath, ok: !hasError, findings };
-}
-function firstDecoratorArg(decoratorText) {
-  const open = decoratorText.indexOf("(");
-  if (open === -1) return void 0;
-  const inner = decoratorText.slice(open + 1, decoratorText.lastIndexOf(")")).replace(/\s+/g, " ").trim();
-  return inner || void 0;
-}
-function collectDecorated(cls, decoratorName) {
-  const members = [];
-  const visit = (name, decoratorTextOf, typeText) => {
-    const text = decoratorTextOf();
-    if (text === void 0) return;
-    members.push({
-      name,
-      arg: firstDecoratorArg(text),
-      type: typeText || void 0
-    });
-  };
-  for (const m of cls.getMethods()) {
-    const dec = m.getDecorator(decoratorName);
-    if (dec) {
-      visit(m.getName(), () => dec.getText(), m.getReturnTypeNode()?.getText());
-    }
-  }
-  for (const p of cls.getProperties()) {
-    const dec = p.getDecorator(decoratorName);
-    if (dec) {
-      visit(p.getName(), () => dec.getText(), p.getTypeNode()?.getText());
-    }
-  }
-  return members;
-}
-function describeModel(codegenFs, options, projects) {
-  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
-  const content = codegenFs.read(modelFilePath);
-  if (content === null) {
-    throw new Error(`Model file not found: ${modelFilePath}`);
-  }
-  const project = new Project({ useInMemoryFileSystem: true });
-  const sf = project.createSourceFile(modelFilePath, content, {
-    overwrite: true
-  });
-  let modelType;
-  const modelTypeDecl = sf.getVariableDeclaration("MODEL_TYPE");
-  if (modelTypeDecl) {
-    const init = modelTypeDecl.getInitializer()?.getText();
-    if (init) modelType = init.replace(/^["'`]|["'`]$/g, "");
-  }
-  const cls = sf.getClasses().find((c) => c.getDecorator("kosModel")) ?? sf.getClasses().find((c) => c.isExported()) ?? sf.getClasses()[0];
-  if (!cls) {
-    return {
+  const mock = writeMock ? ensureMockRoute(codegenFs, {
+    modelFilePath,
+    modelBase,
+    sdkModuleSpecifier: readSourceFile(
+      codegenFs,
       modelFilePath,
-      modelType,
-      classDecorators: [],
-      singleton: false,
-      isCompanion: false,
-      children: [],
-      dependencies: [],
-      topicHandlers: [],
-      configProperties: [],
-      serviceRequests: [],
-      effects: [],
-      futures: []
-    };
-  }
-  const classDecorators = cls.getDecorators().map((d) => d.getName());
-  const kosModelArg = cls.getDecorator("kosModel") ? firstDecoratorArg(cls.getDecorator("kosModel").getText()) : void 0;
-  const singleton = /\bsingleton\s*:\s*true\b/.test(kosModelArg ?? "");
+      resolveSdkModuleSpecifier
+    ),
+    rawAlias,
+    servicePath: options.servicePath,
+    method,
+    endpointKey,
+    sampleText: options.sample
+  }) : void 0;
   return {
     modelFilePath,
-    modelType,
-    className: cls.getName(),
-    classDecorators,
-    singleton,
-    isCompanion: classDecorators.includes("kosCompanion"),
-    children: collectDecorated(cls, "kosChild"),
-    dependencies: collectDecorated(cls, "kosDependency"),
-    topicHandlers: collectDecorated(cls, "kosTopicHandler"),
-    configProperties: collectDecorated(cls, "kosConfigProperty"),
-    serviceRequests: collectDecorated(cls, "kosServiceRequest"),
-    effects: collectDecorated(cls, "kosModelEffect"),
-    futures: collectDecorated(cls, "kosFuture")
+    servicesFilePath,
+    serviceModule: serviceImportFromModel,
+    mode,
+    endpointKey,
+    endpointCreated,
+    pathValidated,
+    provisional,
+    mocksFilePath: mock?.mocksFilePath,
+    mockRegisterFunction: mock?.registerFunction,
+    mockRoute: mock && `${method.toUpperCase()} ${mock.routePattern}`,
+    mockSamplePlaceholder: mock?.samplePlaceholder,
+    removalSteps: provisional ? removalSteps({
+      modelProject: options.modelProject,
+      servicePath: options.servicePath,
+      method,
+      catalogName,
+      endpointKey,
+      servicesFilePath,
+      mocksFilePath: mock?.mocksFilePath,
+      mapperName
+    }) : void 0
   };
 }
 const DEFAULT_SDK_PACKAGE = "@kosdev-code/kos-ui-sdk";
@@ -2997,6 +3806,82 @@ function lookupSdkType(codegenFs, options, projects) {
     )}). Check the name, or it may be internal / not part of the public surface.`
   };
 }
+function modelElementType(typeText) {
+  let m;
+  if (m = typeText.match(/^([A-Za-z_]\w*Model)\s*\[\]$/)) return m[1];
+  if (m = typeText.match(/^Array<\s*([A-Za-z_]\w*Model)\s*>$/)) return m[1];
+  if (m = typeText.match(/^(?:Map|Set)<[^>]*?\b([A-Za-z_]\w*Model)\b[^>]*>$/))
+    return m[1];
+  return null;
+}
+function validateModel(codegenFs, options, projects) {
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  const content = codegenFs.read(modelFilePath);
+  if (content === null) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sf = project.createSourceFile(modelFilePath, content, {
+    overwrite: true
+  });
+  const findings = [];
+  const hasKosModel = sf.getClasses().some((c) => c.getDecorator("kosModel"));
+  if (!hasKosModel) {
+    findings.push({
+      level: "error",
+      rule: "missing-kosModel",
+      message: "No @kosModel decorator found — this is not a KOS model."
+    });
+  }
+  const imports = sf.getImportDeclarations();
+  const mobxImport = imports.find(
+    (d) => /^mobx(-react-lite)?$/.test(d.getModuleSpecifierValue())
+  );
+  if (mobxImport) {
+    findings.push({
+      level: "error",
+      rule: "mobx-import",
+      message: "Imports mobx directly. Reactivity is internal to KOS — remove the mobx import and use KOS reactivity / container models."
+    });
+  }
+  const barrelServiceRequest = imports.find(
+    (d) => d.getModuleSpecifierValue() === "@kosdev-code/kos-ui-sdk" && d.getNamedImports().some((n) => n.getName() === "kosServiceRequest")
+  );
+  if (barrelServiceRequest) {
+    findings.push({
+      level: "warning",
+      rule: "untyped-service-request",
+      message: "kosServiceRequest imported from the SDK barrel. Use the typed decorator from the api:generate'd service module so paths are validated against the OpenAPI types."
+    });
+  }
+  for (const cls of sf.getClasses()) {
+    for (const prop of cls.getProperties()) {
+      const name = prop.getName();
+      const typeText = (prop.getTypeNode()?.getText() ?? "").replace(/\s+/g, " ").trim();
+      const initText = prop.getInitializer()?.getText() ?? "";
+      const hasChild = !!prop.getDecorator("kosChild");
+      const isModelContainer = /\bI?KosModelContainer\s*</.test(typeText) || /new\s+KosModelContainer\b/.test(initText);
+      if (isModelContainer && !hasChild) {
+        findings.push({
+          level: "warning",
+          rule: "container-missing-kosChild",
+          message: `Property '${name}' is a model container but is not marked @kosChild — add @kosChild so its models join the model graph and lifecycle.`
+        });
+        continue;
+      }
+      const elem = modelElementType(typeText);
+      if (elem && !isModelContainer) {
+        findings.push({
+          level: "warning",
+          rule: "raw-model-collection",
+          message: `Property '${name}' is a raw ${typeText} of models — prefer a KosModelContainer<${elem}> (indexing, sorting, lifecycle, delta handling) marked @kosChild.`
+        });
+      }
+    }
+  }
+  const hasError = findings.some((f) => f.level === "error");
+  return { modelFilePath, ok: !hasError, findings };
+}
 const PLUGIN_TYPES = {
   CUI: "cui",
   UTILITY: "utility",
@@ -3551,9 +4436,76 @@ function updatePluginConfiguration(codegenFs, projectConfig, options) {
     );
   }
 }
+function parse(content) {
+  const singleQuoted = /^\s*import\b[^"']*'/m.test(content);
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    manipulationSettings: {
+      indentationText: IndentationText.TwoSpaces,
+      quoteKind: singleQuoted ? QuoteKind.Single : QuoteKind.Double
+    }
+  });
+  return project.createSourceFile("registration-chain.ts", content, {
+    overwrite: true
+  });
+}
+function chainCalls(sf, name) {
+  return sf.getDescendantsOfKind(SyntaxKind.CallExpression).filter((call) => {
+    const callee = call.getExpression();
+    return callee.getKind() === SyntaxKind.PropertyAccessExpression && callee.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName() === name;
+  });
+}
+function indentOfCall(sf, call) {
+  const text = sf.getFullText();
+  const nameNode = call.getExpression().asKindOrThrow(SyntaxKind.PropertyAccessExpression).getNameNode();
+  const lineStart = text.lastIndexOf("\n", nameNode.getStart()) + 1;
+  return text.slice(lineStart).match(/^[ \t]*/)?.[0] ?? "";
+}
+function countChainEntries(content) {
+  return chainCalls(parse(content), "model").length;
+}
+function upsertChainEntry(content, bean, importSpec) {
+  const sf = parse(content);
+  const modelCalls = chainCalls(sf, "model");
+  const registered = modelCalls.some((call) => {
+    const [arg, ...rest] = call.getArguments();
+    return rest.length === 0 && arg?.getText() === bean;
+  });
+  if (registered) return { changed: false, note: "already registered" };
+  let anchor;
+  let indent;
+  if (modelCalls.length > 0) {
+    anchor = modelCalls.reduce(
+      (last, call) => call.getEnd() > last.getEnd() ? call : last
+    );
+    indent = indentOfCall(sf, anchor);
+  } else {
+    const starts = chainCalls(sf, "models").filter(
+      (call) => call.getArguments().length === 0
+    );
+    anchor = starts[starts.length - 1];
+    if (!anchor) {
+      return {
+        changed: false,
+        error: "no .models() chain found in the registration file"
+      };
+    }
+    const text = sf.getFullText();
+    const lineStart = text.lastIndexOf("\n", anchor.getStart()) + 1;
+    indent = (text.slice(lineStart).match(/^[ \t]*/)?.[0] ?? "") + "  ";
+  }
+  anchor.replaceWithText(`${anchor.getText()}
+${indent}.model(${bean})`);
+  const imported = sf.getImportDeclarations().some(
+    (decl) => decl.getNamedImports().some((named) => named.getName() === bean)
+  );
+  if (!imported) ensureNamedImport(sf, importSpec, [{ name: bean }]);
+  return { changed: true, content: sf.getFullText(), importAdded: !imported };
+}
 export {
   BasePluginHandler,
   CONTRIBUTION_TYPE_MAP,
+  DEFAULT_MODEL_LIBS_DIR,
   DirectFileSystem,
   KAB_OUTPUT_DIR,
   KAB_OUTPUT_PATH,
@@ -3575,6 +4527,7 @@ export {
   addJavaArtifactToManifests,
   addKosModelConfiguration,
   addModelEffectToModel,
+  addParentAwareToModel,
   addPropertyToModel,
   addServiceRequestToModel,
   addTopicHandlerToModel,
@@ -3583,6 +4536,7 @@ export {
   buildSbomTarget,
   camelCase,
   constantCase,
+  countChainEntries,
   dashCase,
   describeModel,
   discoverJavaArtifacts,
@@ -3601,8 +4555,10 @@ export {
   generateHook,
   generateInit,
   generateModel,
+  generateModelProject,
   generatePolyglotWorkspace,
   generateSplashProject,
+  generateViewModel,
   getCodegenLogger,
   getCurrentDirectoryName,
   getKosModelConfigProp,
@@ -3620,10 +4576,12 @@ export {
   readNxJson,
   resolveKabPath,
   resolveModelFilePath,
+  resolveModelProjectLayout,
   setCodegenLogger,
   syncCiManifests,
   updateJson,
   updateModelIndex,
+  upsertChainEntry,
   validateModel,
   writeJson
 };