@jskit-ai/jskit-cli 0.2.67 → 0.2.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.67",
+  "version": "0.2.69",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.66",
-    "@jskit-ai/kernel": "0.1.58",
-    "@jskit-ai/shell-web": "0.1.57"
+    "@jskit-ai/jskit-catalog": "0.1.68",
+    "@jskit-ai/kernel": "0.1.60",
+    "@jskit-ai/shell-web": "0.1.59"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/mutationWhen.js

@@ -69,8 +69,9 @@ function normalizeMutationWhen(value) {
   const notContains = String(source.notContains || "").trim();
   const includes = ensureArray(source.in).map((entry) => String(entry || "").trim()).filter(Boolean);
   const excludes = ensureArray(source.notIn).map((entry) => String(entry || "").trim()).filter(Boolean);
+  const hasText = typeof source.hasText === "boolean" ? source.hasText : null;
 
-  if (!option && !config && allConditions.length < 1 && anyConditions.length < 1) {
+  if (!option && !config && allConditions.length < 1 && anyConditions.length < 1 && hasText == null) {
     return null;
   }
 
@@ -84,7 +85,8 @@ function normalizeMutationWhen(value) {
     contains,
     notContains,
     includes,
-    excludes
+    excludes,
+    hasText
   };
 }
 
@@ -270,6 +272,12 @@ function shouldApplyMutationWhen(
   const notContains = normalizeWhenComparisonValue(when.notContains);
   const includes = ensureArray(when.includes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
   const excludes = ensureArray(when.excludes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
+  const hasText = typeof when.hasText === "boolean" ? when.hasText : null;
+  const sourceText = normalizeWhenSourceValue(sourceValue);
+
+  if (hasText != null && (sourceText.length > 0) !== hasText) {
+    return false;
+  }
 
   if (equals && optionValue !== equals) {
     return false;

package/src/server/commandHandlers/appCommandCatalog.js

@@ -30,18 +30,24 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
   verify: Object.freeze({
     name: "verify",
     summary: "Run the JSKIT baseline app verification flow.",
-    usage: "jskit app verify",
-    options: Object.freeze([]),
+    usage: "jskit app verify [--against <base-ref>]",
+    options: Object.freeze([
+      Object.freeze({
+        label: "--against <base-ref>",
+        description: "Resolve changed-file checks against a branch, tag, or commit in addition to any local dirty UI files."
+      })
+    ]),
     defaults: Object.freeze([
       "Runs npm scripts lint, test, test:client, and build only when those scripts are present.",
       "Runs jskit doctor after the normal app checks.",
+      "Use --against <base-ref> in CI or PR validation so doctor evaluates changed-file checks against the branch delta too.",
       "The scaffolded npm run verify wrapper can append npm run --if-present verify:app afterwards."
     ])
   }),
   "verify-ui": Object.freeze({
     name: "verify-ui",
     summary: "Run a targeted Playwright command and write a UI verification receipt for jskit doctor.",
-    usage: "jskit app verify-ui --command <shell-command> --feature <label> --auth-mode <mode>",
+    usage: "jskit app verify-ui --command <shell-command> --feature <label> --auth-mode <mode> [--against <base-ref>]",
     options: Object.freeze([
       Object.freeze({
         label: "--command <shell-command>",
@@ -54,12 +60,16 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
       Object.freeze({
         label: "--auth-mode <mode>",
         description: "Auth path used by the Playwright flow: none | dev-auth-login-as | session-bootstrap | custom-local."
+      }),
+      Object.freeze({
+        label: "--against <base-ref>",
+        description: "Record changed UI files against a branch, tag, or commit instead of only the current dirty worktree."
       })
     ]),
     defaults: Object.freeze([
       "Requires a git working tree so the receipt can record the currently changed UI files.",
       "Writes .jskit/verification/ui.json after the command succeeds.",
-      "Doctor expects the receipt to match the current dirty UI file set."
+      "Doctor expects the receipt to match the current dirty UI file set, or the same --against <base-ref> delta when used."
     ])
   }),
   "update-packages": Object.freeze({
@@ -176,6 +186,9 @@ function buildAppCommandOptionMeta(subcommandName = "") {
   if (definition.name === "update-packages" || definition.name === "release") {
     optionMeta.registry = { inputType: "text" };
   }
+  if (definition.name === "verify" || definition.name === "verify-ui") {
+    optionMeta.against = { inputType: "text" };
+  }
   if (definition.name === "verify-ui") {
     optionMeta.command = { inputType: "text" };
     optionMeta.feature = { inputType: "text" };

package/src/server/commandHandlers/appCommands/linkLocalPackages.js

@@ -60,6 +60,17 @@ async function verifySymlinkTarget(targetPath = "", sourceDir = "", {
   }
 }
 
+async function replaceWithSymlink(targetPath = "", sourceDir = "", {
+  packageName = ""
+} = {}) {
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await rm(targetPath, { recursive: true, force: true });
+  await symlink(sourceDir, targetPath, resolveSymlinkType());
+  await verifySymlinkTarget(targetPath, sourceDir, {
+    packageName
+  });
+}
+
 async function maybeLinkCompanionPackages({
   appRoot = "",
   repoRoot = "",
@@ -105,15 +116,19 @@ async function maybeLinkCompanionPackages({
       );
     }
 
-    const targetPath = path.join(appRoot, "node_modules", companion.packageName);
-    await mkdir(path.dirname(targetPath), { recursive: true });
-    await rm(targetPath, { recursive: true, force: true });
-    await symlink(sourceDir, targetPath, resolveSymlinkType());
-    await verifySymlinkTarget(targetPath, sourceDir, {
+    const appTargetPath = path.join(appRoot, "node_modules", companion.packageName);
+    await replaceWithSymlink(appTargetPath, sourceDir, {
       packageName: companion.packageName
     });
     stdout.write(`[link-local] linked ${companion.packageName} -> ${sourceDir}\n`);
     linkedCount += 1;
+
+    const repoTargetPath = path.join(repoRoot, "node_modules", companion.packageName);
+    await replaceWithSymlink(repoTargetPath, sourceDir, {
+      packageName: `${companion.packageName} (repo root)`
+    });
+    stdout.write(`[link-local] linked repo companion ${companion.packageName} -> ${sourceDir}\n`);
+    linkedCount += 1;
   }
 
   return linkedCount;
@@ -150,8 +165,9 @@ async function runAppLinkLocalPackagesCommand(ctx = {}, { appRoot = "", options
 
   for (const [packageDirName, sourceDir] of [...packageMap.entries()].sort((left, right) => left[0].localeCompare(right[0]))) {
     const targetPath = path.join(scopeDirectory, packageDirName);
-    await rm(targetPath, { recursive: true, force: true });
-    await symlink(sourceDir, targetPath, resolveSymlinkType());
+    await replaceWithSymlink(targetPath, sourceDir, {
+      packageName: `@jskit-ai/${packageDirName}`
+    });
     stdout.write(`[link-local] linked @jskit-ai/${packageDirName} -> ${sourceDir}\n`);
     await linkPackageBinEntries({
       appRoot,

package/src/server/commandHandlers/appCommands/verify.js

@@ -9,6 +9,9 @@ const BASELINE_VERIFY_SCRIPTS = Object.freeze([
 
 async function runAppVerifyCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr }) {
   const { createCliError } = ctx;
+  const inlineOptions =
+    options?.inlineOptions && typeof options.inlineOptions === "object" ? options.inlineOptions : {};
+  const against = String(inlineOptions.against || "").trim();
 
   if (options?.dryRun) {
     throw createCliError("jskit app verify does not support --dry-run.", { exitCode: 1 });
@@ -23,7 +26,12 @@ async function runAppVerifyCommand(ctx = {}, { appRoot = "", options = {}, stdou
     });
   }
 
-  await runLocalJskit(appRoot, ["doctor"], {
+  const doctorArgs = ["doctor"];
+  if (against) {
+    doctorArgs.push("--against", against);
+  }
+
+  await runLocalJskit(appRoot, doctorArgs, {
     stdout,
     stderr,
     createCliError

package/src/server/commandHandlers/appCommands/verifyUi.js

@@ -24,6 +24,7 @@ async function runAppVerifyUiCommand(ctx = {}, { appRoot = "", options = {}, std
   const command = String(inlineOptions.command || "").trim();
   const feature = String(inlineOptions.feature || "").trim();
   const authMode = String(inlineOptions["auth-mode"] || "").trim();
+  const against = String(inlineOptions.against || "").trim();
 
   if (!command) {
     throw createCliError("jskit app verify-ui requires --command <shell-command>.", {
@@ -52,16 +53,18 @@ async function runAppVerifyUiCommand(ctx = {}, { appRoot = "", options = {}, std
     );
   }
 
-  const changedUiState = resolveChangedUiFilesFromGit(appRoot);
+  const changedUiState = resolveChangedUiFilesFromGit(appRoot, { against });
   if (!changedUiState.available) {
-    throw createCliError("jskit app verify-ui requires a git working tree so it can record changed UI files.", {
-      exitCode: 1
-    });
+    const message = against
+      ? `jskit app verify-ui could not resolve changed UI files against ${JSON.stringify(against)}: ${changedUiState.error || "unknown git error"}.`
+      : "jskit app verify-ui requires a git working tree so it can record changed UI files.";
+    throw createCliError(message, { exitCode: 1 });
   }
   if (changedUiState.paths.length < 1) {
-    throw createCliError("jskit app verify-ui found no changed UI files in src/ or packages/.", {
-      exitCode: 1
-    });
+    const message = against
+      ? `jskit app verify-ui found no changed UI files in src/ or packages/ against ${JSON.stringify(against)}.`
+      : "jskit app verify-ui found no changed UI files in src/ or packages/.";
+    throw createCliError(message, { exitCode: 1 });
   }
 
   runExternalShellCommand(command, {
@@ -84,6 +87,7 @@ async function runAppVerifyUiCommand(ctx = {}, { appRoot = "", options = {}, std
         feature,
         command,
         authMode,
+        ...(against ? { against } : {}),
         changedUiFiles: changedUiState.paths
       },
       null,

package/src/server/commandHandlers/health.js

@@ -80,6 +80,34 @@ function createHealthCommands(ctx = {}) {
     "useCrudView",
     "useCrudAddEdit"
   ]);
+  const FEATURE_SERVER_SCAFFOLD_SHAPE = "feature-server-v1";
+  const FEATURE_SERVER_DEFAULT_LANE = "default";
+  const FEATURE_SERVER_JSON_REST_MODE = "json-rest";
+  const FEATURE_SERVER_PERSISTENT_MODES = new Set([
+    "json-rest",
+    "custom-knex"
+  ]);
+  const FEATURE_SERVER_COMPLEX_MARKER_RELATIVE_PATHS = Object.freeze([
+    "src/server/inputSchemas.js",
+    "src/server/actions.js",
+    "src/server/service.js",
+    "src/server/repository.js",
+    "src/server/registerRoutes.js"
+  ]);
+  const FEATURE_SERVER_PERSISTENCE_IMPORT_SOURCE_PATTERNS = Object.freeze([
+    /^@jskit-ai\/json-rest-api-core(?:\/|$)/u,
+    /^@jskit-ai\/database-runtime(?:\/|$)/u,
+    /^@jskit-ai\/database-runtime-mysql(?:\/|$)/u,
+    /^knex(?:\/|$)/u,
+    /^\.{1,2}\/.*repository(?:\.[A-Za-z0-9]+)?$/u
+  ]);
+  const MAIN_SERVER_BASELINE_RELATIVE_PATHS = new Set([
+    "src/server/index.js",
+    "src/server/MainServiceProvider.js",
+    "src/server/loadAppConfig.js"
+  ]);
+  const MAIN_SERVER_DOMAIN_FILE_PATTERN =
+    /^src\/server\/(?!(?:index|MainServiceProvider|loadAppConfig)\.[A-Za-z0-9]+$).+/u;
 
   function collectDescriptorContainerTokens({ packageId, side, values, issues }) {
     const declaredTokens = new Set();
@@ -490,6 +518,331 @@ function createHealthCommands(ctx = {}) {
     return bindings;
   }
 
+  function collectStaticImportSummaries(sourceText = "") {
+    const imports = [];
+    const importPattern = /^\s*import\s+[\s\S]*?\s+from\s+["']([^"']+)["'];?/gmu;
+
+    for (const match of sourceText.matchAll(importPattern)) {
+      const sourcePath = String(match[1] || "").trim();
+      if (!sourcePath) {
+        continue;
+      }
+      imports.push({
+        sourcePath,
+        lineNumber: resolveLineNumberFromIndex(sourceText, match.index || 0)
+      });
+    }
+
+    return imports;
+  }
+
+  function normalizeFeatureLaneMetadata(descriptor = {}) {
+    const metadata = ensureObject(ensureObject(ensureObject(descriptor).metadata).jskit);
+    return {
+      scaffoldShape: String(metadata.scaffoldShape || "").trim(),
+      scaffoldMode: String(metadata.scaffoldMode || "").trim(),
+      lane: String(metadata.lane || "").trim()
+    };
+  }
+
+  function isFeatureLanePersistenceImportSource(sourcePath = "") {
+    const normalizedSourcePath = String(sourcePath || "").trim();
+    if (!normalizedSourcePath) {
+      return false;
+    }
+    return FEATURE_SERVER_PERSISTENCE_IMPORT_SOURCE_PATTERNS.some((pattern) => pattern.test(normalizedSourcePath));
+  }
+
+  function findFirstPatternMatch(sourceText = "", patternEntries = []) {
+    let firstMatch = null;
+
+    for (const rawEntry of ensureArray(patternEntries)) {
+      const entry = ensureObject(rawEntry);
+      const pattern = entry.pattern instanceof RegExp ? entry.pattern : null;
+      if (!pattern) {
+        continue;
+      }
+      const match = pattern.exec(sourceText);
+      if (!match) {
+        continue;
+      }
+      if (!firstMatch || (match.index || 0) < firstMatch.index) {
+        firstMatch = {
+          index: match.index || 0,
+          label: String(entry.label || pattern.source).trim() || pattern.source
+        };
+      }
+    }
+
+    if (!firstMatch) {
+      return null;
+    }
+
+    return {
+      ...firstMatch,
+      lineNumber: resolveLineNumberFromIndex(sourceText, firstMatch.index)
+    };
+  }
+
+  function resolvePrimaryServerProviderPath(packageEntry) {
+    const rootDir = String(packageEntry?.rootDir || "").trim();
+    if (!rootDir) {
+      return "";
+    }
+
+    const providers = ensureArray(ensureObject(ensureObject(packageEntry?.descriptor).runtime).server?.providers);
+    for (const rawProvider of providers) {
+      const provider = ensureObject(rawProvider);
+      const entrypoint = String(provider.entrypoint || "").trim();
+      if (!entrypoint || entrypoint.includes("*")) {
+        continue;
+      }
+      return path.resolve(rootDir, entrypoint);
+    }
+
+    return "";
+  }
+
+  function resolvePackageDisplayPath(packageEntry) {
+    const relativeDir = String(packageEntry?.relativeDir || "").trim();
+    if (relativeDir) {
+      return relativeDir;
+    }
+    return String(packageEntry?.packageId || "").trim() || "package";
+  }
+
+  async function collectFeatureLaneRuleIssuesForPackage({ appRoot, packageEntry, issues }) {
+    const metadata = normalizeFeatureLaneMetadata(packageEntry?.descriptor);
+    if (metadata.scaffoldShape !== FEATURE_SERVER_SCAFFOLD_SHAPE) {
+      return;
+    }
+
+    const rootDir = String(packageEntry?.rootDir || "").trim();
+    if (!rootDir) {
+      return;
+    }
+
+    const packageDisplayPath = resolvePackageDisplayPath(packageEntry);
+    const isDefaultLane = metadata.lane === FEATURE_SERVER_DEFAULT_LANE;
+    const isPersistentMode = FEATURE_SERVER_PERSISTENT_MODES.has(metadata.scaffoldMode);
+
+    const servicePath = path.join(rootDir, "src", "server", "service.js");
+    if (isDefaultLane && (await fileExists(servicePath))) {
+      const serviceSource = await readFile(servicePath, "utf8");
+      const serviceRelativePath = normalizeRelativePath(appRoot, servicePath);
+      const knexMatch = findFirstPatternMatch(serviceSource, [
+        { pattern: /\bjskit\.database\.knex\b/u, label: "jskit.database.knex" },
+        { pattern: /\bcreateWithTransaction\s*\(/u, label: "createWithTransaction(...)" },
+        { pattern: /\bknex\b/u, label: "knex" }
+      ]);
+      if (knexMatch) {
+        issues.push(
+          `${serviceRelativePath}:${knexMatch.lineNumber}: [feature-lane:service-knex] default-lane service code must not use knex directly (${knexMatch.label}). Move persistence into src/server/repository.js or switch the package to an explicit weird-custom lane.`
+        );
+      }
+
+      const offendingServiceImports = collectStaticImportSummaries(serviceSource)
+        .filter((entry) => isFeatureLanePersistenceImportSource(entry.sourcePath));
+      if (offendingServiceImports.length > 0) {
+        const firstImport = offendingServiceImports[0];
+        const importSources = sortStrings(
+          [...new Set(offendingServiceImports.map((entry) => String(entry.sourcePath || "").trim()).filter(Boolean))]
+        );
+        issues.push(
+          `${serviceRelativePath}:${firstImport.lineNumber}: [feature-lane:service-persistence-import] default-lane service code must not import persistence helpers directly (${importSources.join(", ")}). Use the injected repository seam instead.`
+        );
+      }
+    }
+
+    const providerPath = resolvePrimaryServerProviderPath(packageEntry);
+    if (isDefaultLane && providerPath && (await fileExists(providerPath))) {
+      const providerSource = await readFile(providerPath, "utf8");
+      const providerRelativePath = normalizeRelativePath(appRoot, providerPath);
+      const providerPersistenceMatch = findFirstPatternMatch(providerSource, [
+        { pattern: /\bcreateJsonRestContext\s*\(/u, label: "createJsonRestContext(...)" },
+        { pattern: /\.resources\b/u, label: ".resources" },
+        { pattern: /\bjskit\.database\.knex\b/u, label: "jskit.database.knex" },
+        { pattern: /\bcreateWithTransaction\s*\(/u, label: "createWithTransaction(...)" },
+        { pattern: /\bknex\s*\./u, label: "knex." }
+      ]);
+      if (providerPersistenceMatch) {
+        issues.push(
+          `${providerRelativePath}:${providerPersistenceMatch.lineNumber}: [feature-lane:provider-persistence-direct] default-lane providers may wire repositories but must not perform persistence work directly (${providerPersistenceMatch.label}). Move json-rest/database calls into src/server/repository.js.`
+        );
+      }
+    }
+
+    const repositoryPath = path.join(rootDir, "src", "server", "repository.js");
+    if (isPersistentMode && !(await fileExists(repositoryPath))) {
+      issues.push(
+        `${packageDisplayPath}/src/server/repository.js: [feature-lane:repository-required] generated persistent feature packages require src/server/repository.js for scaffoldMode "${metadata.scaffoldMode}".`
+      );
+      return;
+    }
+
+    if (
+      isDefaultLane &&
+      metadata.scaffoldMode === FEATURE_SERVER_JSON_REST_MODE &&
+      (await fileExists(repositoryPath))
+    ) {
+      const repositorySource = await readFile(repositoryPath, "utf8");
+      const repositoryRelativePath = normalizeRelativePath(appRoot, repositoryPath);
+      const directDatabaseMatch = findFirstPatternMatch(repositorySource, [
+        { pattern: /\bjskit\.database\.knex\b/u, label: "jskit.database.knex" },
+        { pattern: /\bcreateWithTransaction\s*\(/u, label: "createWithTransaction(...)" },
+        { pattern: /\bknex\b/u, label: "knex" }
+      ]);
+      const usesJsonRest = /@jskit-ai\/json-rest-api-core|createJsonRestContext\s*\(|\.resources\b|json-rest-api/iu.test(repositorySource);
+      if (directDatabaseMatch || !usesJsonRest) {
+        const locationSuffix = directDatabaseMatch ? `:${directDatabaseMatch.lineNumber}` : "";
+        issues.push(
+          `${repositoryRelativePath}${locationSuffix}: [feature-lane:repository-default-path] default-lane persistent repositories must stay on internal json-rest-api. Use the injected json-rest-api seam or mark the package as an explicit weird-custom lane.`
+        );
+      }
+    }
+  }
+
+  async function collectMainPackageFeatureLaneWarnings({ appRoot, appLocalRegistry, warnings }) {
+    const mainPackageEntry = [...appLocalRegistry.values()].find((packageEntry) => {
+      const packageId = String(packageEntry?.packageId || "").trim();
+      const relativeDir = String(packageEntry?.relativeDir || "").trim();
+      return packageId === "@local/main" || relativeDir === "packages/main";
+    });
+    if (!mainPackageEntry) {
+      return;
+    }
+
+    const rootDir = String(mainPackageEntry.rootDir || "").trim();
+    if (!rootDir) {
+      return;
+    }
+
+    const reasons = [];
+    const serverFilePaths = [];
+    await collectAppSourceFiles(path.join(rootDir, "src", "server"), undefined, serverFilePaths);
+    const relativeServerFiles = sortStrings(serverFilePaths.map((absolutePath) => normalizeRelativePath(rootDir, absolutePath)));
+    const extraDomainFiles = relativeServerFiles.filter(
+      (relativePath) =>
+        !MAIN_SERVER_BASELINE_RELATIVE_PATHS.has(relativePath) &&
+        MAIN_SERVER_DOMAIN_FILE_PATTERN.test(relativePath)
+    );
+    if (extraDomainFiles.length > 0) {
+      reasons.push(`extra server domain files: ${extraDomainFiles.join(", ")}`);
+    }
+
+    const providerPath = path.join(rootDir, "src", "server", "MainServiceProvider.js");
+    if (await fileExists(providerPath)) {
+      const providerSource = await readFile(providerPath, "utf8");
+      const actionBindingCount = (providerSource.match(/\bapp\.actions\s*\(/gu) || []).length;
+      const serviceBindingCount = (providerSource.match(/\bapp\.(?:service|singleton)\s*\(/gu) || []).length;
+      const routeRegistrationCount = (providerSource.match(/\brouter\.register\s*\(/gu) || []).length;
+
+      if (actionBindingCount > 0) {
+        reasons.push("MainServiceProvider registers actions directly");
+      }
+      if (serviceBindingCount > 1) {
+        reasons.push(`MainServiceProvider registers ${serviceBindingCount} service/singleton bindings directly`);
+      }
+      if (routeRegistrationCount > 0) {
+        reasons.push("MainServiceProvider registers HTTP routes directly");
+      }
+    }
+
+    if (reasons.length > 0) {
+      warnings.push(
+        `packages/main: [feature-lane:main-glue-only] packages/main should stay composition/glue. Found ${reasons.join("; ")}. Move substantial server feature logic into a dedicated package generated with feature-server-generator scaffold.`
+      );
+    }
+  }
+
+  async function collectHandmadeFeatureLaneWarnings({ appLocalRegistry, warnings }) {
+    const packageEntries = sortStrings([...appLocalRegistry.keys()])
+      .map((packageId) => appLocalRegistry.get(packageId))
+      .filter(Boolean);
+
+    for (const packageEntry of packageEntries) {
+      const relativeDir = String(packageEntry?.relativeDir || "").trim();
+      if (relativeDir === "packages/main") {
+        continue;
+      }
+
+      const rootDir = String(packageEntry?.rootDir || "").trim();
+      if (!rootDir) {
+        continue;
+      }
+
+      const metadata = normalizeFeatureLaneMetadata(packageEntry?.descriptor);
+      if (metadata.scaffoldShape === FEATURE_SERVER_SCAFFOLD_SHAPE) {
+        continue;
+      }
+
+      const descriptor = ensureObject(packageEntry?.descriptor);
+      const capabilities = ensureObject(descriptor.capabilities);
+      const providedCapabilities = ensureArray(capabilities.provides)
+        .map((value) => String(value || "").trim())
+        .filter(Boolean);
+      const dependsOn = ensureArray(descriptor.dependsOn)
+        .map((value) => String(value || "").trim())
+        .filter(Boolean);
+      if (
+        providedCapabilities.some((value) => value.startsWith("crud.")) ||
+        dependsOn.includes("@jskit-ai/crud-core")
+      ) {
+        continue;
+      }
+
+      const serverProviders = ensureArray(ensureObject(ensureObject(descriptor.runtime).server).providers);
+      const hasDirectServerProvider = serverProviders.some((rawProvider) => {
+        const provider = ensureObject(rawProvider);
+        const entrypoint = String(provider.entrypoint || "").trim();
+        return entrypoint.startsWith("src/server/") && /Provider\.[A-Za-z0-9]+$/u.test(entrypoint);
+      });
+      if (!hasDirectServerProvider) {
+        continue;
+      }
+
+      const markerPaths = [];
+      for (const relativePath of FEATURE_SERVER_COMPLEX_MARKER_RELATIVE_PATHS) {
+        if (await fileExists(path.join(rootDir, relativePath))) {
+          markerPaths.push(relativePath);
+        }
+      }
+
+      const looksLikeFeatureCapability = providedCapabilities.some((value) => value.startsWith("feature."));
+      if (!(markerPaths.length >= 3 || (looksLikeFeatureCapability && markerPaths.length >= 2))) {
+        continue;
+      }
+
+      warnings.push(
+        `${relativeDir || String(packageEntry?.packageId || "").trim()}: [feature-lane:handmade-feature] package looks like a substantial non-CRUD server feature (${markerPaths.join(", ")}) but is missing metadata.jskit.scaffoldShape="${FEATURE_SERVER_SCAFFOLD_SHAPE}". Start from jskit generate feature-server-generator scaffold <feature-name> for this lane instead of hand-making the topology.`
+      );
+    }
+  }
+
+  async function collectFeatureLaneDoctorIssues({ appRoot, appLocalRegistry, issues, warnings }) {
+    const packageEntries = sortStrings([...appLocalRegistry.keys()])
+      .map((packageId) => appLocalRegistry.get(packageId))
+      .filter(Boolean);
+
+    for (const packageEntry of packageEntries) {
+      await collectFeatureLaneRuleIssuesForPackage({
+        appRoot,
+        packageEntry,
+        issues
+      });
+    }
+
+    await collectMainPackageFeatureLaneWarnings({
+      appRoot,
+      appLocalRegistry,
+      warnings
+    });
+    await collectHandmadeFeatureLaneWarnings({
+      appLocalRegistry,
+      warnings
+    });
+  }
+
   function hasTopLevelObjectProperty(sourceText = "", propertyName = "") {
     const normalizedPropertyName = String(propertyName || "").trim();
     const normalizedSourceText = String(sourceText || "").trim();
@@ -801,20 +1154,32 @@ function createHealthCommands(ctx = {}) {
     }
   }
 
-  async function collectUiVerificationDoctorIssues({ appRoot, issues }) {
+  async function collectUiVerificationDoctorIssues({ appRoot, issues, against = "" }) {
     if (!(await directoryLooksLikeJskitAppRoot(appRoot))) {
       return;
     }
 
-    const changedUiState = resolveChangedUiFilesFromGit(appRoot);
-    if (!changedUiState.available || changedUiState.paths.length < 1) {
+    const normalizedAgainst = String(against || "").trim();
+    const changedUiState = resolveChangedUiFilesFromGit(appRoot, {
+      against: normalizedAgainst
+    });
+    if (!changedUiState.available) {
+      if (normalizedAgainst) {
+        issues.push(
+          `[ui:verification] could not resolve changed UI files against ${JSON.stringify(normalizedAgainst)}: ${changedUiState.error || "unknown git error"}`
+        );
+      }
+      return;
+    }
+    if (changedUiState.paths.length < 1) {
       return;
     }
 
     const receiptPath = path.join(appRoot, UI_VERIFICATION_RECEIPT_RELATIVE_PATH);
     if (!(await fileExists(receiptPath))) {
+      const againstSegment = normalizedAgainst ? ` --against ${JSON.stringify(normalizedAgainst)}` : "";
       issues.push(
-        `[ui:verification] changed UI files require a matching ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} receipt. Run jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>. Current files: ${changedUiState.paths.join(", ")}`
+        `[ui:verification] changed UI files require a matching ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} receipt. Run jskit app verify-ui${againstSegment} --command "<playwright command>" --feature "<label>" --auth-mode <mode>. Current files: ${changedUiState.paths.join(", ")}`
       );
       return;
     }
@@ -837,6 +1202,13 @@ function createHealthCommands(ctx = {}) {
       return;
     }
 
+    if (normalizedAgainst && receipt.against !== normalizedAgainst) {
+      issues.push(
+        `[ui:verification] ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} was recorded against ${JSON.stringify(receipt.against || "<dirty-worktree>")} but doctor is checking against ${JSON.stringify(normalizedAgainst)}. Re-run jskit app verify-ui with the same --against value.`
+      );
+      return;
+    }
+
     if (JSON.stringify(receipt.changedUiFiles) !== JSON.stringify(changedUiState.paths)) {
       issues.push(
         `[ui:verification] ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} does not match the current changed UI file set. Re-run jskit app verify-ui after the latest UI edits. Current files: ${changedUiState.paths.join(", ")}`
@@ -898,11 +1270,13 @@ function createHealthCommands(ctx = {}) {
 
   async function commandDoctor({ cwd, options, stdout }) {
     const appRoot = await resolveAppRootFromCwd(cwd);
+    const against = String(options?.inlineOptions?.against || "").trim();
     const { lock } = await loadLockFile(appRoot);
     const packageRegistry = await loadPackageRegistry();
     const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
     const combinedPackageRegistry = mergePackageRegistries(packageRegistry, appLocalRegistry);
     const issues = [];
+    const warnings = [];
     const installed = ensureObject(lock.installedPackages);
     await hydratePackageRegistryFromInstalledNodeModules({
       appRoot,
@@ -938,14 +1312,22 @@ function createHealthCommands(ctx = {}) {
     });
     await collectUiVerificationDoctorIssues({
       appRoot,
-      issues
+      issues,
+      against
+    });
+    await collectFeatureLaneDoctorIssues({
+      appRoot,
+      appLocalRegistry,
+      issues,
+      warnings
     });
 
     const payload = {
       appRoot,
       lockVersion: lock.lockVersion,
       installedPackages: sortStrings(Object.keys(installed)),
-      issues
+      issues,
+      warnings: sortStrings(warnings)
     };
 
     if (options.json) {
@@ -953,13 +1335,21 @@ function createHealthCommands(ctx = {}) {
     } else {
       stdout.write(`App root: ${appRoot}\n`);
       stdout.write(`Installed packages: ${payload.installedPackages.length}\n`);
-      if (issues.length === 0) {
+      if (issues.length === 0 && payload.warnings.length === 0) {
         stdout.write("Doctor status: healthy\n");
+      } else if (issues.length === 0) {
+        stdout.write(`Doctor status: warnings (${payload.warnings.length} warning(s))\n`);
+        for (const warning of payload.warnings) {
+          stdout.write(`! ${warning}\n`);
+        }
       } else {
         stdout.write(`Doctor status: unhealthy (${issues.length} issue(s))\n`);
         for (const issue of issues) {
           stdout.write(`- ${issue}\n`);
         }
+        for (const warning of payload.warnings) {
+          stdout.write(`! ${warning}\n`);
+        }
       }
     }
 

package/src/server/commandHandlers/list.js

@@ -12,6 +12,8 @@ const MAIN_CLIENT_PROVIDERS_RELATIVE_PATH = "packages/main/src/client/providers"
 const COMPONENT_TOKEN_PATTERN = /\bcomponentToken\s*:\s*["']([^"']+)["']/g;
 const REGISTER_MAIN_CLIENT_COMPONENT_PATTERN = /registerMainClientComponent\(\s*["']([^"']+)["']\s*,/g;
 const LINK_ITEM_TOKEN_SUFFIX = "link-item";
+const JSKIT_SCOPE_PREFIX = "@jskit-ai/";
+const FEATURE_SERVER_GENERATOR_PACKAGE_ID = "@jskit-ai/feature-server-generator";
 const PROVIDER_SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx"]);
 const READ_FILE_IGNORE_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EISDIR", "EACCES", "EPERM"]);
 const READ_DIRECTORY_IGNORE_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
@@ -41,6 +43,41 @@ function appendTokenSource(map, token = "", source = "") {
   map.set(normalizedToken, existingSources);
 }
 
+function toShortPackageId(packageId = "") {
+  const normalizedPackageId = String(packageId || "").trim();
+  if (!normalizedPackageId.startsWith(JSKIT_SCOPE_PREFIX)) {
+    return normalizedPackageId;
+  }
+  return normalizedPackageId.slice(JSKIT_SCOPE_PREFIX.length);
+}
+
+function resolveGeneratorPrimarySubcommand(packageEntry = {}) {
+  const descriptor = ensureObject(packageEntry?.descriptor);
+  const metadata = ensureObject(descriptor.metadata);
+  return String(metadata.generatorPrimarySubcommand || descriptor.generatorPrimarySubcommand || "").trim();
+}
+
+function resolveGeneratorDescription(packageEntry = {}) {
+  const descriptor = ensureObject(packageEntry?.descriptor);
+  return String(descriptor.description || "").trim();
+}
+
+function resolveGeneratorQuickStartRows(packageEntry = {}, { limit = 3 } = {}) {
+  const descriptor = ensureObject(packageEntry?.descriptor);
+  const metadata = ensureObject(descriptor.metadata);
+  const subcommands = ensureObject(metadata.generatorSubcommands || descriptor.generatorSubcommands);
+  const primarySubcommandName = resolveGeneratorPrimarySubcommand(packageEntry);
+  const primarySubcommand = ensureObject(subcommands[primarySubcommandName]);
+  const examples = ensureArray(primarySubcommand.examples);
+  return examples
+    .slice(0, Math.max(0, Number(limit) || 0))
+    .map((example) => ({
+      label: String(ensureObject(example).label || "").trim(),
+      lines: ensureArray(ensureObject(example).lines).map((value) => String(value || "").trim()).filter(Boolean)
+    }))
+    .filter((example) => example.lines.length > 0);
+}
+
 function isLinkItemToken(token = "") {
   return String(token || "").trim().toLowerCase().endsWith(LINK_ITEM_TOKEN_SUFFIX);
 }
@@ -265,6 +302,21 @@ function createListCommands(ctx = {}) {
       if (lines.length > 0) {
         lines.push("");
       }
+      const featureServerEntry = packageRegistry.get(FEATURE_SERVER_GENERATOR_PACKAGE_ID);
+      const recommendedQuickStarts = resolveGeneratorQuickStartRows(featureServerEntry, { limit: 3 });
+      if (recommendedQuickStarts.length > 0) {
+        lines.push(color.heading(`Recommended non-CRUD server starts (${recommendedQuickStarts.length}):`));
+        for (const example of recommendedQuickStarts) {
+          const label = String(example.label || "").trim();
+          if (label) {
+            lines.push(`- ${color.item(label)}`);
+          }
+          for (const commandLine of ensureArray(example.lines)) {
+            lines.push(`  ${commandLine}`);
+          }
+        }
+        lines.push("");
+      }
       lines.push(color.heading("Available generators:"));
       const packageIds = sortStrings([...packageRegistry.keys()].filter((packageId) => {
         const packageEntry = packageRegistry.get(packageId);
@@ -273,8 +325,14 @@ function createListCommands(ctx = {}) {
       for (const packageId of packageIds) {
         const packageEntry = packageRegistry.get(packageId);
         const installedLabel = installedPackages.has(packageId) ? " (installed)" : "";
+        const shortId = toShortPackageId(packageId);
+        const shortIdPrefix = shortId && shortId !== packageId ? `${color.item(shortId)} ` : "";
+        const primarySubcommand = resolveGeneratorPrimarySubcommand(packageEntry);
+        const primarySuffix = primarySubcommand ? ` ${color.dim(`[primary:${primarySubcommand}]`)}` : "";
+        const description = resolveGeneratorDescription(packageEntry);
+        const descriptionSuffix = description ? `: ${description}` : "";
         lines.push(
-          `- ${color.item(packageId)} ${color.version(`(${packageEntry.version})`)}${installedLabel ? color.installed(installedLabel) : ""}`
+          `- ${shortIdPrefix}${color.item(packageId)} ${color.version(`(${packageEntry.version})`)}${primarySuffix}${installedLabel ? color.installed(installedLabel) : ""}${descriptionSuffix}`.trim()
         );
       }
     }
@@ -328,8 +386,12 @@ function createListCommands(ctx = {}) {
             }
             return {
               packageId,
+              shortId: toShortPackageId(packageId),
               version: packageEntry.version,
-              installed: installedPackages.has(packageId)
+              installed: installedPackages.has(packageId),
+              description: resolveGeneratorDescription(packageEntry),
+              primarySubcommand: resolveGeneratorPrimarySubcommand(packageEntry),
+              quickStarts: resolveGeneratorQuickStartRows(packageEntry, { limit: 3 })
             };
           }).filter(Boolean)
           : [],

package/src/server/commandHandlers/packageCommands/discoverabilityHelp.js

@@ -10,6 +10,7 @@ import {
 } from "../../shared/outputFormatting.js";
 
 const JSKIT_SCOPE_PREFIX = "@jskit-ai/";
+const FEATURE_SERVER_GENERATOR_PACKAGE_ID = "@jskit-ai/feature-server-generator";
 const HELP_TEXT_BY_KEY = Object.freeze({
   "page-target-file":
     "Vue page file relative to src/pages/. It must resolve to a configured surface.",
@@ -223,7 +224,8 @@ function appendHelpExamples(lines = [], exampleRows = [], { color = null } = {})
   }
 
   lines.push("");
-  lines.push(color ? color.heading(`Examples (${examples.length}):`) : `Examples (${examples.length}):`);
+  const headingLabel = color ? color.heading(`Examples (${examples.length}):`) : `Examples (${examples.length}):`;
+  lines.push(headingLabel);
   appendSeparatedBlocks(
     lines,
     examples.map((example) => {
@@ -250,6 +252,31 @@ function appendHelpExamples(lines = [], exampleRows = [], { color = null } = {})
   );
 }
 
+function appendHelpExamplesWithHeading(lines = [], exampleRows = [], heading = "", { color = null } = {}) {
+  const examples = ensureArray(exampleRows);
+  const headingText = String(heading || "").trim();
+  if (examples.length < 1 || !headingText) {
+    return;
+  }
+
+  lines.push("");
+  lines.push(color ? color.heading(headingText) : headingText);
+  appendSeparatedBlocks(
+    lines,
+    examples.map((example) => {
+      const block = [];
+      const label = String(example?.label || "").trim();
+      if (label) {
+        block.push(`- ${color ? color.item(label) : label}`);
+      }
+      for (const commandLine of ensureArray(example?.lines)) {
+        block.push(`  ${commandLine}`);
+      }
+      return block;
+    }).filter((block) => block.length > 0)
+  );
+}
+
 function appendHelpNotes(lines = [], rawNotes = [], { color = null } = {}) {
   const notes = normalizeHelpNoteRows(rawNotes);
   if (notes.length < 1) {
@@ -420,6 +447,23 @@ function buildSubcommandOptionRows(optionRows = [], subcommandRow = {}) {
   return rows;
 }
 
+function resolvePrimaryGeneratorQuickStartRows(packageEntry = {}, { limit = 3 } = {}) {
+  const metadata = resolveGeneratorSubcommandMetadata(packageEntry);
+  const subcommands = ensureArray(metadata.subcommands);
+  const primarySubcommand = subcommands.find((row) => row.primary) || subcommands[0] || null;
+  if (!primarySubcommand) {
+    return [];
+  }
+
+  return ensureArray(primarySubcommand.examples)
+    .slice(0, Math.max(0, Number(limit) || 0))
+    .map((example) => Object.freeze({
+      label: String(example?.label || "").trim(),
+      lines: ensureArray(example?.lines).map((value) => String(value || "").trim()).filter(Boolean)
+    }))
+    .filter((example) => example.lines.length > 0);
+}
+
 function renderGenerateCatalogHelp({
   io,
   packageRegistry,
@@ -438,11 +482,14 @@ function renderGenerateCatalogHelp({
         description: resolvePackageSummary(entry)
       });
     });
+  const featureServerPackageEntry = packageRegistry.get(FEATURE_SERVER_GENERATOR_PACKAGE_ID);
+  const recommendedQuickStarts = resolvePrimaryGeneratorQuickStartRows(featureServerPackageEntry, { limit: 3 });
 
   if (json) {
     io.stdout.write(`${JSON.stringify({
       command: "generate",
       generators,
+      recommendedQuickStarts,
       usage: [
         "jskit generate <generatorId> help",
         "jskit generate <generatorId> [subcommand] [subcommand args...] [--<option> <value>...]",
@@ -471,6 +518,12 @@ function renderGenerateCatalogHelp({
   lines.push("- jskit generate <generatorId> help");
   lines.push("- jskit generate <generatorId> [subcommand] [subcommand args...] [--<option> <value>...]");
   lines.push("- jskit list generators");
+  appendHelpExamplesWithHeading(
+    lines,
+    recommendedQuickStarts,
+    `Recommended non-CRUD server starts (${recommendedQuickStarts.length}):`,
+    { color }
+  );
   writeWrappedLines({
     stdout: io.stdout,
     lines
@@ -619,6 +672,12 @@ function renderGeneratePackageHelp({
       const descriptionSuffix = subcommand.description ? `: ${subcommand.description}` : "";
       lines.push(`- ${color.item(subcommand.name)}${primarySuffix}${descriptionSuffix}`);
     }
+    appendHelpExamplesWithHeading(
+      lines,
+      resolvePrimaryGeneratorQuickStartRows(packageEntry, { limit: 3 }),
+      `Primary quick starts (${resolvePrimaryGeneratorQuickStartRows(packageEntry, { limit: 3 }).length}):`,
+      { color }
+    );
     lines.push("");
     lines.push("Use subcommand help for positional args, options, notes, and examples:");
     lines.push(`  ${color.item("jskit generate <generatorId> <subcommand> help")}`);

package/src/server/commandHandlers/packageCommands/generate.js

@@ -240,7 +240,7 @@ async function runPackageGenerateCommand(
     });
     if (!resolvedPackageId) {
       throw createCliError(
-        `Unknown package: ${packageIdInput}. Install it first (npm install ${packageIdInput}) if you want to run generator subcommands from node_modules.`
+        `Unknown package: ${packageIdInput}. Use jskit list generators to discover available generators. If you want to run generator subcommands from node_modules, install the generator first (npm install ${packageIdInput}). For a substantial non-CRUD server feature, start with: jskit generate feature-server-generator scaffold <feature-name>.`
       );
     }
 
@@ -255,7 +255,7 @@ async function runPackageGenerateCommand(
     }
     if (resolvePackageKind(packageEntry) !== "generator") {
       throw createCliError(
-        `Package ${resolvedPackageId} is a runtime package. Use: jskit add package ${resolvedPackageId}`
+        `Package ${resolvedPackageId} is a runtime package. Use: jskit add package ${resolvedPackageId}. For a new substantial non-CRUD server feature, start with: jskit generate feature-server-generator scaffold <feature-name>.`
       );
     }
 

package/src/server/commandHandlers/packageCommands/update.js

@@ -23,7 +23,9 @@ async function runPackageUpdateCommand(
   const installedPackages = ensureObject(lock.installedPackages);
   const resolvedTargetId = resolveInstalledPackageIdInput(targetId, installedPackages);
   if (!resolvedTargetId) {
-    throw createCliError(`Package is not installed: ${targetId}`);
+    throw createCliError(
+      `Package is not installed: ${targetId}. update package only reapplies packages already recorded in .jskit/lock.json. If you meant to install it, run: jskit add package ${targetId}`
+    );
   }
 
   return runCommandAdd({

package/src/server/commandHandlers/show/renderPackageText.js

@@ -6,6 +6,35 @@ import { createShowRenderHelpers } from "./renderHelpers.js";
 import { writePackageExportsSection } from "./renderPackageExports.js";
 import { writeCapabilitiesSections } from "./renderPackageCapabilities.js";
 
+function resolveGeneratorSubcommandRows(payload = {}) {
+  const metadata = ensureObject(payload.metadata);
+  const generatorSubcommands = ensureObject(metadata.generatorSubcommands);
+  const primarySubcommand = String(metadata.generatorPrimarySubcommand || "").trim();
+  return Object.keys(generatorSubcommands)
+    .sort((left, right) => left.localeCompare(right))
+    .map((subcommandName) => {
+      const definition = ensureObject(generatorSubcommands[subcommandName]);
+      return {
+        name: subcommandName,
+        primary: primarySubcommand === subcommandName,
+        description: String(definition.description || "").trim(),
+        examples: ensureArray(definition.examples)
+          .map((example) => {
+            const record = ensureObject(example);
+            return {
+              label: String(record.label || "").trim(),
+              lines: ensureArray(record.lines).map((value) => String(value || "").trim()).filter(Boolean)
+            };
+          })
+          .filter((example) => example.lines.length > 0)
+      };
+    });
+}
+
+function resolveOwnershipGuidance(payload = {}) {
+  return ensureObject(ensureObject(ensureObject(payload.metadata).jskit).ownershipGuidance);
+}
+
 function renderPackagePayloadText({
   payload,
   provides,
@@ -70,6 +99,8 @@ function renderPackagePayloadText({
   const bindingSections = ensureObject(payload.containerBindings);
   const serverBindings = ensureArray(bindingSections.server);
   const clientBindings = ensureArray(bindingSections.client);
+  const generatorSubcommands = resolveGeneratorSubcommandRows(payload);
+  const ownershipGuidance = resolveOwnershipGuidance(payload);
 
   stdout.write(`${color.heading("Information")}\n`);
   writeField("Package", payload.packageId, color.item);
@@ -98,6 +129,50 @@ function renderPackagePayloadText({
     }
   }
 
+  if (generatorSubcommands.length > 0) {
+    stdout.write(`${color.heading(`Generator commands (${generatorSubcommands.length}):`)}\n`);
+    for (const subcommand of generatorSubcommands) {
+      const primarySuffix = subcommand.primary ? ` ${color.installed("[primary]")}` : "";
+      const descriptionSuffix = subcommand.description ? `: ${subcommand.description}` : "";
+      stdout.write(`- ${color.item(subcommand.name)}${primarySuffix}${descriptionSuffix}\n`);
+      if (options.details && subcommand.examples.length > 0) {
+        for (const example of subcommand.examples.slice(0, 2)) {
+          const exampleLabel = String(example.label || "").trim();
+          if (exampleLabel) {
+            stdout.write(`  ${color.dim(`example: ${exampleLabel}`)}\n`);
+          }
+          for (const commandLine of ensureArray(example.lines)) {
+            stdout.write(`  ${commandLine}\n`);
+          }
+        }
+      }
+    }
+  }
+
+  if (options.details && Object.keys(ownershipGuidance).length > 0) {
+    const title = String(ownershipGuidance.title || "Ownership guidance").trim() || "Ownership guidance";
+    const summary = String(ownershipGuidance.summary || "").trim();
+    const responsibilities = ensureArray(ownershipGuidance.responsibilities)
+      .map((value) => String(value || "").trim())
+      .filter(Boolean);
+    const examples = ensureArray(ownershipGuidance.examples)
+      .map((value) => String(value || "").trim())
+      .filter(Boolean);
+    stdout.write(`${color.heading(title)}\n`);
+    if (summary) {
+      stdout.write(`- ${summary}\n`);
+    }
+    for (const responsibility of responsibilities) {
+      stdout.write(`- ${responsibility}\n`);
+    }
+    if (examples.length > 0) {
+      stdout.write(`- ${color.dim("quick starts:")}\n`);
+      for (const example of examples) {
+        stdout.write(`  ${example}\n`);
+      }
+    }
+  }
+
   if (placementOutlets.length > 0) {
     stdout.write(`${color.heading(`Placement outlets (${placementOutlets.length}):`)}\n`);
     for (const outlet of placementOutlets) {

package/src/server/core/commandCatalog.js

@@ -223,22 +223,23 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       "Short ids resolve to @jskit-ai/<id> when available.",
       "Running without args lists available generators.",
       "Running with only <generatorId> shows generator help.",
+      "For substantial non-CRUD server features, start with feature-server-generator scaffold.",
       "Use jskit generate <generatorId> <subcommand> help for subcommand-specific usage."
     ]),
     examples: Object.freeze([
       Object.freeze({
         label: "Common usage",
         lines: Object.freeze([
-          "npx jskit generate ui-generator page \\",
-          "  admin/reports/index.vue"
+          "npx jskit generate feature-server-generator scaffold \\",
+          "  booking-engine"
         ])
       }),
       Object.freeze({
         label: "More advanced usage",
         lines: Object.freeze([
-          "npx jskit generate crud-ui-generator crud \\",
-          "  admin/catalog/index/products \\",
-          "  --resource-file packages/products/src/shared/productResource.js"
+          "npx jskit generate feature-server-generator scaffold \\",
+          "  availability-engine \\",
+          "  --mode orchestrator"
         ])
       })
     ]),
@@ -265,6 +266,7 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     ]),
     defaults: Object.freeze([
       "Without mode, list prints bundles + runtime packages + generators.",
+      "Use list generators when you want the standard non-CRUD server lane command examples.",
       "placements are listed by the dedicated list-placements command.",
       "--full and --expanded only affect bundle/package listing views."
     ]),
@@ -338,6 +340,7 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     ]),
     defaults: Object.freeze([
       "Basic output is compact; --details expands capability and runtime sections.",
+      "Generator packages may include lane ownership guidance and subcommand examples under --details.",
       "--debug-exports implies --details."
     ]),
     fullUse: "jskit show <id> [--details] [--debug-exports] [--json]",
@@ -472,14 +475,15 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     defaults: Object.freeze([
       "Validates lock entries, managed files, and registry visibility.",
       "Reports issues as plain text by default.",
-      "Use --json for machine-readable diagnostics."
+      "Use --json for machine-readable diagnostics.",
+      "Use --against <base-ref> when changed-file checks should compare against a branch, tag, or commit."
     ]),
-    fullUse: "jskit doctor [--json]",
+    fullUse: "jskit doctor [--against <base-ref>] [--json]",
     showHelpOnBareInvocation: false,
     handlerName: "commandDoctor",
     allowedFlagKeys: Object.freeze(["json"]),
-    inlineOptionMode: "none",
-    allowedValueOptionNames: Object.freeze([])
+    inlineOptionMode: "enumerated",
+    allowedValueOptionNames: Object.freeze(["against"])
   }),
   "lint-descriptors": Object.freeze({
     command: "lint-descriptors",

package/src/server/core/usageHelp.js

@@ -39,6 +39,12 @@ function printTopLevelHelp(stream = process.stderr) {
   for (const entry of listOverviewCommandDescriptors()) {
     lines.push(`  ${color.item(entry.command.padEnd(16, " "))} ${entry.summary}`);
   }
+  lines.push("");
+  lines.push(color.heading("Generator quick starts:"));
+  lines.push("  substantial non-CRUD server feature:");
+  lines.push(`    ${color.item("jskit generate feature-server-generator scaffold booking-engine")}`);
+  lines.push("  non-persistent workflow/orchestrator:");
+  lines.push(`    ${color.item("jskit generate feature-server-generator scaffold availability-engine --mode orchestrator")}`);
   writeHelpLines(stream, lines);
 }
 

package/src/server/shared/uiVerification.js

@@ -61,17 +61,26 @@ function readGitPathList(appRoot = "", args = []) {
   if (result?.error || result?.status !== 0) {
     return {
       ok: false,
-      paths: []
+      paths: [],
+      error: normalizeText(result?.stderr) || normalizeText(result?.error?.message)
     };
   }
 
   return {
     ok: true,
-    paths: sortUniqueStrings(String(result.stdout || "").split(/\r?\n/u))
+    paths: sortUniqueStrings(String(result.stdout || "").split(/\r?\n/u)),
+    error: ""
   };
 }
 
-function resolveChangedUiFilesFromGit(appRoot = "") {
+function resolveChangedPathsFromGit(
+  appRoot = "",
+  {
+    against = "",
+    pathspecs = ["src", "packages"]
+  } = {}
+) {
+  const normalizedAgainst = normalizeText(against);
   const gitRepoCheck = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
     cwd: appRoot || process.cwd(),
     encoding: "utf8"
@@ -84,26 +93,72 @@ function resolveChangedUiFilesFromGit(appRoot = "") {
   ) {
     return {
       available: false,
-      paths: []
+      paths: [],
+      against: normalizedAgainst,
+      mode: normalizedAgainst ? "against-base-ref" : "dirty-worktree",
+      error: "Current directory is not inside a git work tree."
     };
   }
 
-  const changedPathSets = [
-    readGitPathList(appRoot, ["diff", "--name-only", "--relative", "--cached", "--", "src", "packages"]),
-    readGitPathList(appRoot, ["diff", "--name-only", "--relative", "--", "src", "packages"]),
-    readGitPathList(appRoot, ["ls-files", "--others", "--exclude-standard", "--", "src", "packages"])
-  ];
+  const normalizedPathspecs = sortUniqueStrings(pathspecs);
+  const pathspecArgs = normalizedPathspecs.length > 0 ? ["--", ...normalizedPathspecs] : [];
+  const changedPathSets = [];
+
+  if (normalizedAgainst) {
+    const baseDiff = readGitPathList(appRoot, [
+      "diff",
+      "--name-only",
+      "--relative",
+      `${normalizedAgainst}...HEAD`,
+      ...pathspecArgs
+    ]);
+    if (!baseDiff.ok) {
+      return {
+        available: false,
+        paths: [],
+        against: normalizedAgainst,
+        mode: "against-base-ref",
+        error:
+          baseDiff.error ||
+          `Could not resolve git diff against ${JSON.stringify(normalizedAgainst)}.`
+      };
+    }
+    changedPathSets.push(baseDiff);
+  }
+
+  changedPathSets.push(
+    readGitPathList(appRoot, ["diff", "--name-only", "--relative", "--cached", ...pathspecArgs]),
+    readGitPathList(appRoot, ["diff", "--name-only", "--relative", ...pathspecArgs]),
+    readGitPathList(appRoot, ["ls-files", "--others", "--exclude-standard", ...pathspecArgs])
+  );
 
   const changedPaths = sortUniqueStrings(
     changedPathSets
       .filter((entry) => entry.ok)
       .flatMap((entry) => entry.paths)
-      .filter((relativePath) => isUiVerificationPath(relativePath))
   );
 
   return {
     available: true,
-    paths: changedPaths
+    paths: changedPaths,
+    against: normalizedAgainst,
+    mode: normalizedAgainst ? "against-base-ref" : "dirty-worktree",
+    error: ""
+  };
+}
+
+function resolveChangedUiFilesFromGit(appRoot = "", { against = "" } = {}) {
+  const changedPathState = resolveChangedPathsFromGit(appRoot, {
+    against,
+    pathspecs: ["src", "packages"]
+  });
+  if (!changedPathState.available) {
+    return changedPathState;
+  }
+
+  return {
+    ...changedPathState,
+    paths: changedPathState.paths.filter((relativePath) => isUiVerificationPath(relativePath))
   };
 }
 
@@ -117,6 +172,7 @@ function normalizeUiVerificationReceipt(rawReceipt = {}) {
     feature: normalizeText(receipt.feature),
     command: normalizeText(receipt.command),
     authMode: normalizeText(receipt.authMode),
+    against: normalizeText(receipt.against),
     changedUiFiles: sortUniqueStrings(receipt.changedUiFiles)
   });
 }
@@ -143,6 +199,7 @@ export {
   isUiVerificationPath,
   isValidUiVerificationReceipt,
   normalizeUiVerificationReceipt,
+  resolveChangedPathsFromGit,
   resolveChangedUiFilesFromGit,
   sortUniqueStrings
 };