openyida 2026.9.19 → 2026.9.21

package/lib/app/theme-from-design.js

@@ -5,7 +5,7 @@ const path = require('path');
 const { CliError } = require('../core/cli-error');
 const { REQUIRED_BRAND_SCALE_TOKENS, validateThemeCssContent, extractThemeColor } = require('./custom-theme');
 const { parseDesignDocument, extractDesignTokens } = require('../design/document');
-const NAVIGATION_TOKENS = [
+const NAVIGATION_COLOR_TOKENS = [
   '--pod-shell-theme-bg-color', '--pod-nav-item-text-color', '--pod-nav-item-text-hover-color',
   '--pod-nav-item-text-selected-color', '--pod-nav-menu-bg-hover-color', '--pod-nav-menu-bg-selected-color',
 ];
@@ -48,7 +48,7 @@ function resolveDesignTokens(metadata) {
 }
 
 function navigationTone(metadata, tokens) {
-  if (!NAVIGATION_TOKENS.every(name => tokens[name])) {return null;}
+  if (!NAVIGATION_COLOR_TOKENS.every(name => tokens[name])) {return null;}
   const tone = metadata.themeProfile?.navTheme;
   if (['light', 'dark'].includes(tone)) {return tone;}
   if (tone !== undefined) {throw new CliError('themeProfile.navTheme 必须是 light 或 dark', { code: 'DESIGN_THEME_NAVIGATION_INVALID' });}
@@ -91,7 +91,9 @@ function applyNavigationTokens(css, tokens, changed, tone, previousTone) {
   const source = fs.readFileSync(path.resolve(__dirname,
     '../../yida-skills/skills/yida-design/references/theme/app-custom-theme-template.css'), 'utf8');
   const defaults = Object.assign({}, ...[...source.matchAll(/^:root\s*\{([^}]+)\}/gm)].map(match => declarationValues(match[1])));
-  const navigationChanged = Object.fromEntries(NAVIGATION_TOKENS.filter(name => name in changed).map(name => [name, tokens[name]]));
+  const isNavigation = name => /^(--pod-nav-|--pod-shell-|--pod-page-header-)/.test(name);
+  const navigationNames = Object.keys(tokens).filter(isNavigation);
+  const navigationChanged = Object.fromEntries(navigationNames.filter(name => name in changed).map(name => [name, tokens[name]]));
   let output = css.replace(/(^:root\s*\{)([^}]+)(\})/gm,
     (block, start, body, close) => start + replaceDeclarations(body, navigationChanged) + close);
   for (const mode of ['light', 'dark']) {
@@ -102,19 +104,23 @@ function applyNavigationTokens(css, tokens, changed, tone, previousTone) {
     // A first application or a mode change establishes both palettes. Delta
     // updates otherwise leave unrelated, manually customized declarations alone.
     const resetMode = !previousTone || previousTone !== tone;
-    const names = resetMode ? NAVIGATION_TOKENS : (mode === tone ? Object.keys(navigationChanged) : []);
-    const values = Object.fromEntries(names.map(name => [name, mode === tone ? tokens[name] : modeDefaults[name]]));
+    // The selected marker is a mode-independent shape, not a navigation palette.
+    const names = (resetMode ? navigationNames : (mode === tone ? Object.keys(navigationChanged) : []))
+      .filter(name => name !== '--pod-nav-menu-item-selected-shadow');
+    const values = Object.fromEntries(names.map(name => [name, mode === tone ? tokens[name] : modeDefaults[name]])
+      .filter(([, value]) => value !== undefined));
     if (!Object.keys(values).length) {continue;}
+    const isForeground = name => name.startsWith('--pod-nav-') || name === '--pod-page-header-text-color';
+    const background = Object.fromEntries(Object.entries(values).filter(([name]) => !isForeground(name)));
     const shell = values['--pod-shell-theme-bg-color'];
-    if (shell) {
-      const background = {
-        '--pod-shell-theme-bg-color': shell,
-        '--pod-page-header-bg-color': mode === tone ? shell : modeDefaults['--pod-page-header-bg-color'],
-      };
+    if (shell && !tokens['--pod-page-header-bg-color']) {
+      background['--pod-page-header-bg-color'] = mode === tone ? shell : modeDefaults['--pod-page-header-bg-color'];
+    }
+    if (Object.keys(background).length) {
       output = output.replace(new RegExp(`(\\.pod-premium\\.nav-${mode}\\s*\\{)([^}]*)(\\})`, 'g'),
         (block, start, body, close) => start + replaceDeclarations(body, background, true) + close);
     }
-    const foregrounds = Object.fromEntries(Object.entries(values).filter(([name]) => name !== '--pod-shell-theme-bg-color'));
+    const foregrounds = Object.fromEntries(Object.entries(values).filter(([name]) => isForeground(name)));
     output = output.replace(new RegExp(`(\\.pod-premium\\.is-${mode}\\s*\\{)([^}]*)(\\})`, 'g'),
       (block, start, body, close) => start + replaceDeclarations(body, foregrounds, true) + close);
   }
@@ -122,18 +128,37 @@ function applyNavigationTokens(css, tokens, changed, tone, previousTone) {
 }
 
 function applyDesignTokens(template, markdown, previousMarkdown) {
-  // Reject damaged templates or existing stylesheets before the scope rewrite.
-  validateThemeCssContent(template);
   const metadata = designMetadata(markdown);
   const previousMetadata = previousMarkdown === markdown ? metadata : (previousMarkdown ? designMetadata(previousMarkdown) : null);
   const tokens = resolveDesignTokens(metadata);
+  // Bundled CSS is an authoring template. Fill only unresolved declarations from
+  // the completed design before validating and rewriting CSS scopes.
+  template = template.replace(/^([ \t]*)(--[\w-]+)(\s*:\s*)([^;\n]+);/gm,
+    (line, indent, name, separator, value) => {
+      if (!/\{\{PRIMARY_COLOR\}\}|<生成实际色值：/.test(value)) {return line;}
+      if (!tokens[name] || /\{\{|<生成实际色值：/.test(tokens[name])) {
+        throw new CliError(`design.md 缺少品牌 token：${name}`, { code: 'DESIGN_THEME_TOKENS_REQUIRED' });
+      }
+      return `${indent}${name}${separator}${tokens[name]};`;
+    });
+  // Reject damaged templates or existing stylesheets before the scope rewrite.
+  validateThemeCssContent(template);
+  // Older generated files have the selected-shadow rule only. Bring in the
+  // shared consumer once when a design opts into menu borders, retaining all
+  // existing project rules and declarations during incremental updates.
+  if (tokens['--pod-nav-menu-item-border'] && !template.includes('border: var(--pod-nav-menu-item-border,')) {
+    const source = fs.readFileSync(path.resolve(__dirname,
+      '../../yida-skills/skills/yida-design/references/theme/app-custom-theme-template.css'), 'utf8');
+    const shapeRules = source.match(/\/\* openyida-navigation-shape:start \*\/[\s\S]*?\/\* openyida-navigation-shape:end \*\//)[0];
+    template += `\n${shapeRules}\n`;
+  }
   const previous = previousMetadata === metadata ? tokens : (previousMetadata ? resolveDesignTokens(previousMetadata) : null);
   const tone = navigationTone(metadata, tokens);
   const previousTone = previous ? navigationTone(previousMetadata, previous) : null;
   const changed = Object.fromEntries(Object.entries(tokens).filter(([name, value]) => !previous || previous[name] !== value));
   if (!Object.keys(changed).length && tone === previousTone) {
     extractThemeColor(template);
-    return template;
+    return require('./application-style').applyApplicationStyle(template, metadata, tokens);
   }
   const root = /^:root\s*\{([\s\S]*?)^\}/m.exec(template);
   if (!root) {throw new Error('应用主题模板缺少 :root');}
@@ -157,6 +182,7 @@ function applyDesignTokens(template, markdown, previousMarkdown) {
   }
   let css = `${template.slice(0, root.index)}:root {${body}}${tail}`;
   if (tone) {css = applyNavigationTokens(css, tokens, changed, tone, previousTone);}
+  css = require('./application-style').applyApplicationStyle(css, metadata, tokens);
   validateThemeCssContent(css);
   extractThemeColor(css);
   return css;

package/lib/app/update-app.js

@@ -92,11 +92,18 @@ function parseArgs(args) {
     return result;
   }
   result.appType = args[0];
+  if (args.includes('--hide-app-nav') && args.includes('--show-app-nav')) {
+    throwCommandError(t('cli_argument.invalid', '--hide-app-nav / --show-app-nav'), { code: 'CLI_INVALID_ARGUMENTS' });
+  }
 
   // 解析选项参数
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     const nextArg = args[i + 1];
+    if (!['--hide-app-nav', '--show-app-nav'].includes(arg) &&
+        (!nextArg || nextArg.startsWith('--') || ['-n', '-d'].includes(nextArg))) {
+      throwCommandError(t('cli_argument.invalid', arg), { code: 'CLI_INVALID_ARGUMENTS' });
+    }
 
     switch (arg) {
       case '--name':
@@ -174,6 +181,8 @@ function parseArgs(args) {
       case '--show-app-nav':
         result.hideAppNav = 'n';
         break;
+      default:
+        throwCommandError(t('cli_argument.invalid', arg), { code: 'CLI_INVALID_ARGUMENTS' });
     }
   }
 
@@ -308,6 +317,7 @@ function buildUpdateAppPostData(params, currentApp = {}, authRef) {
   const sentryMode = pickAppField(currentApp, 'sentryMode', 'SENTRY_MODE');
   const currentNavType = currentApp.navType || (currentApp.config && currentApp.config.NAVTYPE);
   const currentLayoutDirection = currentApp.layoutDirection || (currentApp.config && currentApp.config.LAY_OUT_DIRECTION);
+  const currentNavTheme = currentApp.navTheme || (currentApp.config && currentApp.config.NAV_THEME);
   if (params.colour === 'custom' && !params.themeColor && !currentThemeColor) {
     throw new Error(t('update_app.custom_theme_color_required'));
   }
@@ -330,7 +340,6 @@ function buildUpdateAppPostData(params, currentApp = {}, authRef) {
     // updateApp 的报错文案叫 appMode，但实际接受的请求字段是 mode。
     mode: currentApp.mode || (currentApp.config && currentApp.config.APPMODE) || 'normal',
     type: currentApp.type || (currentApp.config && currentApp.config.APPTYPE) || 'single',
-    navTheme: params.navTheme || currentApp.navTheme || (currentApp.config && currentApp.config.NAV_THEME) || 'light',
     navLayout: currentApp.navLayout || (currentApp.config && currentApp.config.NAVLAYOUT) || 'auto',
     layoutDirection: params.layoutDirection
       ? normalizeLayoutDirection(params.layoutDirection)
@@ -361,6 +370,8 @@ function buildUpdateAppPostData(params, currentApp = {}, authRef) {
 
   // ThemeNavSetting 保存现有 navType；新布局由 layoutDirection 控制，不反写或补造旧字段。
   if (currentNavType) {postDataObj.navType = currentNavType;}
+  const navTheme = params.navTheme || currentNavTheme;
+  if (navTheme) {postDataObj.navTheme = navTheme;}
   if (addWaterMark !== undefined && addWaterMark !== null) {
     postDataObj.addWaterMark = addWaterMark;
   }
@@ -442,7 +453,26 @@ function themeSettingsMatch(expected, actual) {
     ['cssUrl', 'cssFileName'].every((key) => (expectedStyle[key] || '') === (actualStyle[key] || ''));
 }
 
-/** updateApp 整包保存；与基础设置页一致，读取最新配置后合并，并核验主题资源。 */
+function getRequestedNavigationSettings(params, payload) {
+  return Object.fromEntries(['navTheme', 'layoutDirection', 'hideAppNav', 'logoSource']
+    .filter((name) => params[name] !== undefined && params[name] !== null && params[name] !== '')
+    .map((name) => [name, payload[name]]));
+}
+
+function getNavigationSettings(app, fields) {
+  const configKeys = { navTheme: 'NAV_THEME', layoutDirection: 'LAY_OUT_DIRECTION', hideAppNav: 'HIDE_APP_NAV', logoSource: 'LOGO_SOURCE' };
+  return Object.fromEntries(fields.map((name) => {
+    let value = pickAppField(app, name, configKeys[name]);
+    if (name === 'layoutDirection') {
+      const navType = pickAppField(app, 'navType', 'NAVTYPE');
+      // A missing response field is not evidence that the requested default was saved.
+      value = value || navType ? normalizeStoredLayoutDirection(value, navType) : null;
+    }
+    return [name, value === undefined ? null : value];
+  }));
+}
+
+/** updateApp 整包保存；读取最新配置后合并，并核验主题资源和本次请求的导航设置。 */
 async function saveAppSettings(params, authRef) {
   const currentApp = await fetchCurrentApp(params.appType, authRef);
   const payload = buildUpdateAppPostData(params, currentApp, authRef);
@@ -454,29 +484,46 @@ async function saveAppSettings(params, authRef) {
   if (!response || !response.success) { return response; }
 
   const expected = getThemeSettings(payload);
-  if (!params.colour && !params.themeColor && !params.customThemeStyle && !expected.themeColor && !expected.customThemeStyle) {
-    return response;
-  }
+  const verifyTheme = !!(params.colour || params.themeColor || params.customThemeStyle || expected.themeColor || expected.customThemeStyle);
+  const expectedNavigation = getRequestedNavigationSettings(params, payload);
+  const navigationFields = Object.keys(expectedNavigation);
+  if (!verifyTheme && !navigationFields.length) {return response;}
   let actual;
+  let actualNavigation;
   let readbackError;
+  let themeVerified = !verifyTheme;
+  let navigationVerified = !navigationFields.length;
   // 只重试查询，避免重复上传资源或用旧快照再次覆盖设置。
   for (let attempt = 0; attempt < 3; attempt++) {
     if (attempt) { await new Promise((resolve) => setTimeout(resolve, attempt * 250)); }
     try {
-      actual = getThemeSettings(await fetchCurrentApp(params.appType, authRef));
+      const app = await fetchCurrentApp(params.appType, authRef);
+      actual = getThemeSettings(app);
+      actualNavigation = getNavigationSettings(app, navigationFields);
       readbackError = undefined;
-      if (themeSettingsMatch(expected, actual)) {
-        return { ...response, themeVerification: { verified: true, ...actual } };
+      themeVerified = !verifyTheme || themeSettingsMatch(expected, actual);
+      navigationVerified = navigationFields.every((name) => expectedNavigation[name] === actualNavigation[name]);
+      if (themeVerified && navigationVerified) {
+        return { ...response,
+          ...(verifyTheme ? { themeVerification: { verified: true, ...actual } } : {}),
+          ...(navigationFields.length ? { navigationVerification: { verified: true, ...actualNavigation } } : {}),
+        };
       }
     } catch (error) {
       readbackError = error.message;
+      themeVerified = !verifyTheme;
+      navigationVerified = !navigationFields.length;
     }
   }
   return {
     success: false,
-    errorCode: 'APP_THEME_NOT_PERSISTED',
-    errorMsg: t('update_app.theme_not_persisted'),
-    themeVerification: { verified: false, expected, actual, readbackError },
+    errorCode: themeVerified ? 'APP_NAVIGATION_NOT_PERSISTED' : 'APP_THEME_NOT_PERSISTED',
+    errorMsg: t(themeVerified ? 'update_app.navigation_not_persisted' : 'update_app.theme_not_persisted'),
+    ...(verifyTheme ? { themeVerification: themeVerified
+      ? { verified: true, ...actual } : { verified: false, expected, actual, readbackError } } : {}),
+    ...(navigationFields.length ? { navigationVerification: navigationVerified
+      ? { verified: true, ...actualNavigation }
+      : { verified: false, expected: expectedNavigation, actual: actualNavigation, readbackError } } : {}),
   };
 }
 
@@ -594,6 +641,7 @@ async function run(args) {
       success: true,
       appType: params.appType,
       themeVerification: response.themeVerification,
+      navigationVerification: response.navigationVerification,
       updatedFields: {
         name: params.name || undefined,
         desc: params.desc || undefined,
@@ -611,8 +659,10 @@ async function run(args) {
     const errorMsg = response ? response.errorMsg || t('common.unknown_error') : t('common.request_failed');
     chalkResult(false, t('update_app.failed', errorMsg));
     console.log(JSON.stringify({ success: false, appType: params.appType, error: errorMsg,
-      errorCode: response && response.errorCode, themeVerification: response && response.themeVerification }));
-    throwCommandError(errorMsg, { code: response && response.errorCode, details: response && response.themeVerification });
+      errorCode: response && response.errorCode, themeVerification: response && response.themeVerification,
+      navigationVerification: response && response.navigationVerification }));
+    throwCommandError(errorMsg, { code: response && response.errorCode,
+      details: response && (response.errorCode === 'APP_NAVIGATION_NOT_PERSISTED' ? response.navigationVerification : response.themeVerification) });
   }
 }
 

package/lib/core/command-manifest.js

@@ -3,6 +3,7 @@
 const { getMaterialSourcingGuidance } = require('../asset/ai-image');
 const { getVisualDecisionPolicy } = require('../design-plan/visual-policy');
 const { getPageNavigationContract } = require('../design-plan/navigation-policy');
+const { ENTRY_MODES } = require('../design-plan/entry-navigation');
 const { DIVIDER_TYPES, DEFAULT_DIVIDER_TYPE } = require('../app/form-field-validator');
 
 const SIDE_EFFECT_BASES = Object.freeze({
@@ -1058,12 +1059,12 @@ const COMMAND_GROUPS = [
       command('design-plan.catalog', ['design-plan', 'catalog'], 'design-plan catalog [--json]', 'help.cmd_design_plan_catalog', {
         requiresLogin: false, output: 'json',
         args: [{ name: 'json', type: 'boolean', source: 'option', builder_options: ['--json'] }],
-        notes: ['Read available theme IDs and page patterns before init when the theme mapping is unknown. Reuse this result for the current planning session.'],
+        notes: ['Read available theme IDs and page patterns before init when the theme mapping is unknown. Theme summaries describe deep/light navigation and deep/light content in natural language; they do not expose navTheme/contentTheme assignment syntax. Reuse this result for the current planning session.'],
       }),
       command('design-plan.init', ['design-plan', 'init'], 'design-plan init <requirement-brief.json> [--theme-id <id>] [--output-dir <dir>] [--json]', 'help.cmd_design_plan_init', {
         requiresLogin: false,
         output: 'text|json',
-        notes: ['Returns preserved business facts, authoring.pendingFields with file/path/message, typed examples in authoring-context.md, and materialize.command with materialize.shell (powershell on Windows, posix elsewhere). Execute the command in that shell. Complete the pending facts, review business coverage, then set ready=true. Author ordered page blocks as {name,purpose}; omitted contentPriority and contentRichness.contentLayers derive from these blocks, preserving explicit overrides. Author project-specific acceptanceCriteria; materialize merges them with resource-based checks. A string visualSelection.colorStrategy is preserved as usage text with primaryColor pending; invalid types fail before files are written. Init guidance is preliminary; materialize still validates the completed plan.'],
+        notes: ['Requires a selected theme from --theme-id or visualSelection.themeId. There is no navigation-tone argument: init reads navTheme from the selected theme template, overwrites stale navigationStyle.tone, and records toneSource=theme_derived. Free creative preserves an explicitly authored navigationStyle.tone and records toneSource=project_defined. Returns preserved business facts, authoring.pendingFields with file/path/message, typed examples in authoring-context.md, and materialize.command with materialize.shell (powershell on Windows, posix elsewhere). Execute the command in that shell. Complete the pending facts, review business coverage, then set ready=true. Author ordered page blocks as {name,purpose}; omitted contentPriority and contentRichness.contentLayers derive from these blocks, preserving explicit overrides. Author project-specific acceptanceCriteria; materialize merges them with resource-based checks. A string visualSelection.colorStrategy is preserved as usage text with primaryColor pending; invalid types fail before files are written. Init guidance is preliminary; materialize still validates the completed plan.'],
         args: [
           { name: 'requirementBrief', type: 'file', required: true, source: 'positional', position: 0, builder_options: ['--requirement-brief'] },
           { name: 'themeId', type: 'string', required: false, source: 'option', builder_options: ['--theme-id'] },
@@ -1080,13 +1081,14 @@ const COMMAND_GROUPS = [
         ],
         notes: ['Updates completed fact modules in preview/ drafts. Modules share a source base; one writer updates changed sections and preserves custom CSS. Final materialize validates the complete plan and writes PRD, design, HTML and theme together.'],
       }),
-      command('design-plan.materialize', ['design-plan', 'materialize'], 'design-plan materialize <build-plan.json> [--from-preview | --business-file <json> --visual-file <json>] [--output-dir <dir>] [--check] [--json]', 'help.cmd_design_plan_materialize', {
-        notes: ['Validates image slots before writing artifacts. JSON assetTasks lists taskKey/taskState, independent searches ordered by required/hero/design order, collection-wide concurrency, host-enforced time budgets, two-round limits, resume policy, output paths and resolve argv. After matching plan confirmation, executionContract requires checking background Agent and Bash separately, dispatching only verified nonblocking tools or doing authorized business work before synchronous asset batches; record real job IDs and continue app/form/page work; replace <appType> with the real ID for upload. Materialized PRD execution pages include navigationPolicy derived from app/page navigation: platform-shell is content-only; standalone without a planned menu renders no application menu. This command performs no search or upload. Local asset inputs resolve against the command cwd; absolute paths survive page-task directory changes.'],
+      command('design-plan.materialize', ['design-plan', 'materialize'], 'design-plan materialize <build-plan.json> [--from-preview | --business-file <json> --visual-file <json>] [--output-dir <dir>] [--rebase-parts] [--check] [--json]', 'help.cmd_design_plan_materialize', {
+        notes: ['Derives navigationStyle.tone and appConfig.navTheme from the selected theme template. Navigation appearance tokens come directly from that template plus explicit visualStyle.tokens; mode-independent tokens such as --pod-nav-menu-item-selected-shadow flow through the base token contract; materialize does not synthesize a light/dark replacement palette. Free creative uses project-authored navigation tone and tokens. Validates image slots before writing artifacts. JSON assetTasks lists taskKey/taskState, independent searches ordered by required/hero/design order, collection-wide concurrency, host-enforced time budgets, two-round limits, resume policy, output paths and resolve argv. After matching plan confirmation, executionContract requires checking background Agent and Bash separately, dispatching only verified nonblocking tools or doing authorized business work before synchronous asset batches; record real job IDs and continue app/form/page work; replace <appType> with the real ID for upload. Materialized PRD execution pages include navigationPolicy derived from app/page navigation: platform-shell is content-only; standalone without a planned menu renders no application menu. This command performs no search or upload. Local asset inputs resolve against the command cwd; absolute paths survive page-task directory changes.'],
         requiresLogin: false,
         output: 'text|json',
         args: [
           { name: 'buildPlan', type: 'file', required: true, source: 'positional', position: 0, builder_options: ['--build-plan'] },
           { name: 'fromPreview', type: 'boolean', required: false, source: 'option', builder_options: ['--from-preview'] },
+          { name: 'rebaseParts', type: 'boolean', source: 'option', builder_options: ['--rebase-parts'] },
           { name: 'businessFile', type: 'file', required: false, source: 'option', builder_options: ['--business-file'] },
           { name: 'visualFile', type: 'file', required: false, source: 'option', builder_options: ['--visual-file'] },
           { name: 'outputDir', type: 'string', required: false, source: 'option', builder_options: ['--output-dir'] },
@@ -1095,12 +1097,12 @@ const COMMAND_GROUPS = [
         ],
       }),
       command('design-plan.patch', ['design-plan', 'patch'], 'design-plan patch <build-plan.json> --set <path=value> [--set <path=value> ...] [--materialize] [--output-dir <dir>] [--json]', 'help.cmd_design_plan_patch', {
-        notes: ['Edit the existing plan with one batch of --set assignments; do not restart init or rewrite business.json/visual.json. With --materialize, update changed PRD/design/HTML sections and theme tokens, preserving unrelated local content and custom CSS. JSON updated lists artifact files actually written. The CLI maintains .build-plan-artifacts.json as the generated baseline; overlapping local edits fail before any writes. Without --materialize, validate and save source facts without rendering HTML or writing artifacts. Unpresented edits keep the draft revision; substantive edits to a presented version advance once and clear approval. Asset materialStatus/missingAssets updates preserve approval.'],
+        notes: ['Edit the existing plan with one batch of --set assignments; do not restart init or rewrite business.json/visual.json. navigationStyle.tone, navigationStyle.toneSource and execution.appConfig.navTheme are derived and cannot be patched; change the selected theme instead. For free-creative only, navigationStyle.tone is authored and can be patched. With --materialize, update changed PRD/design/HTML sections and theme tokens, preserving unrelated local content and custom CSS. JSON updated lists artifact files actually written. The CLI maintains .build-plan-artifacts.json as the generated baseline; overlapping local edits fail before any writes. Without --materialize, validate and save source facts without rendering HTML or writing artifacts. Unpresented edits keep the draft revision; substantive edits to a presented version advance once and clear approval. Asset materialStatus/missingAssets updates preserve approval.'],
         requiresLogin: false,
         output: 'text|json',
         args: [
           { name: 'buildPlan', type: 'file', required: true, source: 'positional', position: 0, builder_options: ['--build-plan'] },
-          { name: 'set', type: 'string', required: true, source: 'option', builder_options: ['--set'], repeatable: true, description: 'Field assignment path=value; repeat --set for multiple changes.' },
+          { name: 'set', type: 'string', required: true, source: 'option', builder_options: ['--set'], repeatable: true, description: 'Field assignment path=value; repeat --set for multiple changes. CSS token overrides use visualStyle.tokens.<token>=<value>.' },
           { name: 'materialize', type: 'boolean', source: 'option', builder_options: ['--materialize'] },
           { name: 'outputDir', type: 'string', source: 'option', builder_options: ['--output-dir'] },
           { name: 'json', type: 'boolean', source: 'option', builder_options: ['--json'] },
@@ -1115,15 +1117,18 @@ const COMMAND_GROUPS = [
           { name: 'iconColor', type: 'string', source: 'option', builder_options: ['--icon-color'] },
           { name: 'colour', type: 'string', source: 'option', builder_options: ['--colour', '--theme'], description: 'Platform theme key or custom; CSS colors belong in themeColor.' },
           { name: 'themeColor', type: 'string', source: 'option', builder_options: ['--theme-color', '--themeColor'], description: 'App primary color; themeFile supplies the effective color when both are provided.' },
-          { name: 'themeFile', type: 'file', source: 'option', builder_options: ['--theme-file', '--custom-theme-file'], description: 'Application theme CSS; declares --color-brand1-6 and sets colour=custom.' },
-          { name: 'navTheme', type: 'string', source: 'option', builder_options: ['--nav-theme', '--navTheme'], description: 'light, dark, white or gray.' },
+          { name: 'themeFile', type: 'file', source: 'option', builder_options: ['--theme-file', '--custom-theme-file'], description: 'Completed application theme CSS, not a placeholder authoring bundle. Reads --color-brand1-6, uploads CSS and sets colour=custom. Supports app-theme.css or app_theme.css; use the actual generated path.' },
+          { name: 'navTheme', type: 'string', source: 'option', builder_options: ['--nav-theme', '--navTheme'], description: 'Platform value: light, dark, white or gray. Generated design flows pass the selected template-derived light/dark value explicitly; this option has no implicit light default.' },
           { name: 'logoSource', type: 'string', source: 'option', builder_options: ['--logo-source', '--logoSource'], description: 'appIcon or customImage; customImage requires an existing homepageLogo.' },
           { name: 'layoutDirection', type: 'string', source: 'option', builder_options: ['--layout', '--layout-direction', '--layoutDirection'], description: 'side, top or l_shape.' },
           { name: 'hideAppNav', type: 'boolean', source: 'option', builder_options: ['--hide-app-nav'] },
           { name: 'showAppNav', type: 'boolean', source: 'option', builder_options: ['--show-app-nav'] },
         ],
         notes: [
-          'Upload application CSS with --theme-file; the primary color is read from CSS and saved with the theme resource.',
+          'Upload application CSS with --theme-file; the primary color is read from CSS and saved with the theme resource. Edit navigation radius, three border states and selected shadow in design.md, regenerate CSS, then upload; these tokens are not separate update-app flags. Unknown options, missing values and combined --hide-app-nav/--show-app-nav are rejected.',
+          'One design document and theme CSS cover navigation, application shell, native forms, custom pages and record details. tokens.application-global.appearance.navigation defines navigation surfaces, text and interaction states, logo, groups, search, popups, borders, radius and density. Platform-supported tokens are applied through the active navigation mode; page content consumes the same application theme.',
+          'navigationVerification reads back explicitly requested navTheme, layoutDirection, hideAppNav and logoSource. A mismatch returns APP_NAVIGATION_NOT_PERSISTED and a nonzero exit code; only readback is retried. themeVerification independently verifies the uploaded theme resource. Verify rendered navigation, form, custom page and record detail after both checks pass.',
+          'For generated design artifacts, pass themeProfile.navTheme from design.md to --nav-theme. Do not infer it from the business brief or omit it expecting a light default.',
           'Platform preset keys are used independently of --theme-file and --theme-color. Choose --hide-app-nav or --show-app-nav to set navigation visibility.',
         ],
       }),
@@ -1160,9 +1165,9 @@ const COMMAND_GROUPS = [
           { name: 'check', type: 'boolean', source: 'option', builder_options: ['--check'], description: 'Validate definitions and dependency groups locally.' },
           { name: 'json', type: 'boolean', source: 'option', builder_options: ['--json'] },
         ],
-        notes: ['Creates independent normal forms concurrently after dependency validation. References resolve from successful schema readbacks. Existing formUuid entries are read-only reuse. Saves IDs and status beside the plan; recoveryAction and nextAction are enum values: rerun_unchanged_plan reuses successful results and resumes known form IDs; inspect_unknown_write_then_reconcile requires checking uncertain writes before rerunning. Results expose appUrl and formUrl; url remains the compatible form entry. Navigation ordering and shared app configuration follow the batch.'],
+        notes: ['Creates independent normal forms concurrently after dependency validation. Each plan item accepts layout (single/double/card/section), theme (default/compact/comfortable), labelAlign (top/left/right), icon and locale, and forwards them to create-form create. References resolve from successful schema readbacks. Existing formUuid entries are read-only reuse. Saves IDs and status beside the plan; recoveryAction and nextAction are enum values: rerun_unchanged_plan reuses successful results and resumes known form IDs; inspect_unknown_write_then_reconcile requires checking uncertain writes before rerunning. Results expose appUrl and formUrl; url remains the compatible form entry. Navigation ordering and shared app configuration follow the batch.'],
       }),
-      command('create-form.create', ['create-form', 'create'], 'create-form create <appType> "<formTitle>" <fieldsJsonFile> [--icon auto|<iconName>] [--locale zh_CN|en_US|ja_JP] [--open|--no-open]', 'help.cmd_create_form', {
+      command('create-form.create', ['create-form', 'create'], 'create-form create <appType> "<formTitle>" <fieldsJsonFile> [--layout single|double|card|section] [--theme default|compact|comfortable] [--label-align top|left|right] [--icon auto|<iconName>] [--locale zh_CN|en_US|ja_JP] [--open|--no-open]', 'help.cmd_create_form', {
         args: [
           {
             name: 'appType',
@@ -1193,6 +1198,36 @@ const COMMAND_GROUPS = [
             inline_json_rejected_options: ['--fields'],
             description: 'Path to a local JSON file containing field definitions.',
           },
+          {
+            name: 'layout',
+            type: 'string',
+            required: false,
+            source: 'option',
+            builder_options: ['--layout'],
+            default: 'single',
+            values: ['single', 'double', 'card', 'section'],
+            description: 'Form-wide layout preset: single, double, card or section. Numeric aliases 1 and 2 remain accepted by the CLI.',
+          },
+          {
+            name: 'theme',
+            type: 'string',
+            required: false,
+            source: 'option',
+            builder_options: ['--theme'],
+            default: 'default',
+            values: ['default', 'compact', 'comfortable'],
+            description: 'Form density preset: default, compact or comfortable; this is not the application visual theme.',
+          },
+          {
+            name: 'labelAlign',
+            type: 'string',
+            required: false,
+            source: 'option',
+            builder_options: ['--label-align'],
+            default: 'top',
+            values: ['top', 'left', 'right'],
+            description: 'PC field-label alignment: top, left or right.',
+          },
           {
             name: 'icon',
             type: 'string',
@@ -1203,13 +1238,24 @@ const COMMAND_GROUPS = [
             value_catalog_command_id: 'create-form.icons',
             description: 'Form navigation icon name. Use auto for semantic selection or run create-form.icons for supported values.',
           },
+          {
+            name: 'contentLocale',
+            type: 'string',
+            required: false,
+            source: 'option',
+            builder_options: ['--locale', '--content-locale', '--lang'],
+            values: ['zh_CN', 'en_US', 'ja_JP'],
+            description: 'Content locale: zh_CN, en_US or ja_JP (normalized locale aliases are also accepted).',
+          },
+          { name: 'open', type: 'boolean', required: false, source: 'option', builder_options: ['--open'] },
+          { name: 'noOpen', type: 'boolean', required: false, source: 'option', builder_options: ['--no-open'] },
         ],
         canonical: {
           command_id: 'create-form.create',
           path: ['create-form', 'create'],
           argv_template: ['create-form', 'create', '<appType>', '<formTitle>', '<fieldsJsonFile>'],
           display: 'openyida create-form create <appType> "<formTitle>" <fieldsJsonFile>',
-          builder: 'openyida commands build create-form.create --app-type <appType> --form-title "<formTitle>" --fields-json-file <fieldsJsonFile> [--icon <iconName>] --json',
+          builder: 'openyida commands build create-form.create --app-type <appType> --form-title "<formTitle>" --fields-json-file <fieldsJsonFile> [--layout single|double|card|section] [--theme default|compact|comfortable] [--label-align top|left|right] [--icon <iconName>] [--locale zh_CN|en_US|ja_JP] [--open|--no-open] --json',
         },
         deprecatedPatterns: [
           {
@@ -1239,8 +1285,8 @@ const COMMAND_GROUPS = [
         ],
         examples: [
           'openyida create-form create APP_XXX "访客登记" .cache/openyida/visitor/fields.json',
-          'openyida create-form create APP_XXX "访客登记" .cache/openyida/visitor/fields.json --icon name-card',
-          'openyida commands build create-form.create --app-type APP_XXX --form-title "访客登记" --fields-json-file .cache/openyida/visitor/fields.json --json',
+          'openyida create-form create APP_XXX "访客登记" .cache/openyida/visitor/fields.json --layout section --theme comfortable --label-align left --icon name-card --locale zh_CN --no-open',
+          'openyida commands build create-form.create --app-type APP_XXX --form-title "访客登记" --fields-json-file .cache/openyida/visitor/fields.json --layout section --theme comfortable --label-align left --locale zh_CN --no-open --json',
         ],
         notes: ['Divider accepts the 23 visible platform styles (none is excluded) through field JSON dividerType, not a CLI flag. Omission falls back to bold-with-thin; invalid supplied styles fail. Choose per business page and keep same-level sections consistent; see summary.core_workflows.full_app_build.divider_style_contract.'],
       }),
@@ -1539,9 +1585,15 @@ const COMMAND_GROUPS = [
         output: 'text|json',
       }),
       command('copy', ['copy'], 'copy [--force]', 'help.cmd_copy', { requiresLogin: false }),
-      command('sample', ['sample'], 'sample [--list] [<skill> <name>] [--output <file>] [--var KEY=VALUE ...] [--design-file <design.md>]', 'help.cmd_sample', {
+      command('sample', ['sample'], 'sample [--list] [<skill> <name>] [--output <file-or-directory>] [--var KEY=VALUE ...] [--design-file <design.md>] [--style-id <themeId|free-creative>]', 'help.cmd_sample', {
         requiresLogin: false,
+        output: 'text|json',
         notes: [
+          'yida-design app-theme reads concrete tokens from --design-file and writes CSS plus a sibling <output>.tokens.md update snapshot. The same output path preserves project CSS and applies changed tokens. Without --design-file it resets the output to the public base template. Menu radius, normal/hover/selected borders and selected shadow apply to side, L-shaped and top navigation; older CSS gains missing menu-shape rules when the design supplies menu-border tokens.',
+          'yida-design application-style --style-id supports every catalog theme and exports a three-file design.md/app_theme.css/form-layout.json authoring bundle to an output directory without overwriting files. Brand primary and hover values remain project placeholders until app-theme --design-file generates concrete CSS. Use design-plan catalog for presets and its separate creativeOption; free creative requires independent business decisions and explicit design tokens.',
+          'Author menu radius, normal/hover/selected borders, selected shadow, item height, padding, gap and shell spacing together in design.md navigation tokens (Fast) or visualStyle.tokens (Plan). These are design values, not separate CLI flags. Preset appearance does not override the business navigation layout. Verify native data-management navigation and business pages in workbench access mode; /admin is the development configuration surface.',
+          'Native forms use a component tree with top, left, main, right and between-field regions. Platform form components include tabs, button groups, images/graphics, status areas, dividers, columns and business fields, serving navigation, actions, visual focus, feedback, hierarchy, decoration and data capture. Application-style form-layout.json provides an editable starting layout for openyida create-form: use the supported business fields, Divider and ColumnContainer, and retain other existing components when updating a form.',
+          'canvas-nav-side/top/mixed/dock consume the same menu radius, normal/hover/selected borders and selected shadow as platform navigation. Side and Dock items read menu item height/padding; top and mixed header items read top-tab height/padding/max-width. Side/top/mixed menus read menu-gap; Dock reads slide-collapsed-menu-gap. Side shell padding uses slide-aside-padding and mixed uses l-aside-padding. Re-export the fragment, integrate it into existing page source and republish to upgrade existing custom navigation. canvas-nav-tabs remains an in-page tab control.',
           'Canvas form-drawer, table-form and trend-combo samples include the maintained CanvasThemeProvider, read the current application CSS variables, and prevent loading-mask border flashes caused by late CSS resets.',
           'form-fields demonstrates field layout, not a default divider design. Choose dividerType for the current business page before creating forms; keep same-level sections consistent and vary different business pages when appropriate.',
           'openyida-page-template canvas-theme outputs the same provider as a reusable fragment; combine its imports and code with the business page in one Canvas file, keeping its scoped loading-mask style. Existing pages must update their provider and be republished; changing application theme CSS alone does not upgrade embedded provider code.',
@@ -1554,9 +1606,10 @@ const COMMAND_GROUPS = [
           { name: 'skill', type: 'string', source: 'positional', position: 0, description: 'Required when copying a sample.' },
           { name: 'name', type: 'string', source: 'positional', position: 1, description: 'Required when copying a sample; use --list for available names.' },
           { name: 'list', type: 'boolean', source: 'option', builder_options: ['--list'] },
-          { name: 'output', type: 'file', source: 'option', builder_options: ['--output'] },
-          { name: 'var', type: 'string', source: 'option', builder_options: ['--var'], repeatable: true, description: 'Template assignment KEY=VALUE; repeat --var for multiple variables.' },
-          { name: 'designFile', type: 'file', source: 'option', builder_options: ['--design-file'], description: 'Design tokens for yida-design app-theme; preserves custom CSS when updating.' },
+          { name: 'output', type: 'file', source: 'option', builder_options: ['--output'], description: 'Output file for ordinary samples/app-theme; output directory for application-style. Defaults under cwd/.cache/samples; application-style defaults to its application-style subdirectory and rejects an existing bundle file.' },
+          { name: 'var', type: 'string', source: 'option', builder_options: ['--var'], repeatable: true, description: 'Ordinary sample assignment KEY=VALUE; repeat --var for multiple variables. Not accepted by yida-design app-theme or application-style; complete design.md before generating theme CSS.' },
+          { name: 'designFile', type: 'file', source: 'option', builder_options: ['--design-file'], description: 'Only for yida-design app-theme: completed design.md with concrete tokens. Optional for a base-template reset; supply it to generate or incrementally update project CSS.' },
+          { name: 'styleId', type: 'string', source: 'option', builder_options: ['--style-id'], description: 'Required only for yida-design application-style. Accepts any themeId from design-plan catalog, including shared themes and free-creative. Exports design.md, app_theme.css and form-layout.json with brand placeholders; accepts neither --design-file nor --var.' },
         ],
       }),
       command('doctor', ['doctor'], 'doctor [--fix]', 'help.cmd_doctor', { requiresLogin: false }),
@@ -1737,7 +1790,7 @@ function summarizeLocalizedCommands(commands) {
           join_owner_skill_id: 'yida-app',
         },
         ordinary_jsx_skill_id: 'yida-custom-page',
-        form_page_policy: 'Use yida-create-form-page for form structure. Use create-form.batch to create independent normal forms concurrently, resolve dependencies from real IDs and read back fields; apply shared app configuration and navigation order afterward. Never inject CSS, JavaScript, HTML, or theme code into native forms or formDetail pages; the platform renders those pages.',
+        form_page_policy: 'Use yida-create-form-page for form structure and business actions. Use create-form.batch to create independent normal forms concurrently, resolve dependencies from real IDs and read back fields; apply shared app configuration, application theme, and navigation order afterward.',
         divider_style_contract: {
           reference: 'yida-skills/skills/yida-create-form-page/references/form-field-properties.md#divider',
           input: 'fields[].dividerType (also inside layout children); field JSON, not a CLI flag',
@@ -1760,18 +1813,21 @@ function summarizeLocalizedCommands(commands) {
         plan_command_ids: ['design-plan.catalog', 'design-plan.init', 'design-plan.preview', 'design-plan.materialize', 'design-plan.patch'],
         theme_command_ids: ['sample', 'create-app', 'update-app'],
         navigation_command_ids: { platform: ['update-app', 'nav-group'], custom: ['update-app', 'update-form-config', 'get-form-config'] },
-        navigation_policy: 'Before PRD planning in Fast and Plan, the agent determines navigation ownership and layout from business context. Follow yida-design/references/navigation-decision.md for entry and layout decisions. Preserve explicit user requirements and existing navigation for local changes; resource-only requests operate on their specified resources and settings. Use native navigation by default for the application workspace, and custom navigation only for an explicitly justified application-level branded menu or special navigation interaction. A service frontend defaults to one coding page with its own menu and all selected business views; a single-step entry can use navigation.type=none. Choose backend native or coding pages by task efficiency. Backend coding pages in platform-shell are content-only: platform menus own cross-module navigation; local Tabs cover categories or states of the current task only. Never turn the management entry menu into a second page navbar, sidebar or module Tabs. Persistent filters/state alone do not justify custom application navigation. Plan handoff pages include derived navigationPolicy; Fast records the same boundary. Do not hide platform navigation to repair duplicate page menus. Store application navigation in navigationType and standalone entry menus in pageSpecHandoff.navigation. Configure a custom frontend menu at page scope and preserve workspace navigation. Record type/source/reason/variant using ai_default for agent ownership decisions and user_selected for explicit user requirements. Include navigation in the overall Plan confirmation; Fast implements the recorded decision. Platform navigation uses update-app --layout top|side|l_shape --show-app-nav, persisting layoutDirection and hideAppNav=n. Preserve stored navType. Without --layout, normalize legacy layoutDirection and navType using the application layout compatibility rules (hoz plus top_side means l_shape; missing layout uses top_fold/top_side for top/l_shape). Apply shell top_fold/none overrides at page scope. Application-wide custom side/top/mixed/dock uses app hiding plus per-page hiding within scope; a standalone frontend in a platform-navigation app uses only page configuration. Read back layoutDirection, hideAppNav and each configured page, then verify the planned frontend and workspace links. Navigation tone is separate from layout. Custom top navigation defaults to edge-to-edge, not floating. Over a hero image, start transparent, add a surface on scroll, restore transparency at the top; expanded menus stay readable. Follow yida-design/references/page-continuity.md; floating requires an explicit design.',
-        design_mode_policy: 'Analyze requirements first with yida-requirement-analysis: read only necessary sources before the first question, offer concrete core-function candidates, clarify key usage, and preserve explicit scope and valid answers. Initial intake focuses on core functions and actual usage. Record actual user replies; proceed with dependent planning after a reply or explicit delegation. First-time builds include new apps and existing apps without business pages. After intake, reuse explicit mode choices and detailed supplied plans; if the user delegates the mode or asks for no more questions, use Fast unless Plan is explicit; otherwise, if the mode is unspecified, ask whether to prepare a PRD for confirmation (Plan, more detailed and slower) or build from the supplied requirements (Fast). Without detailed requirements, offer Fast and Plan neutrally. intake.confirmed records scope and key-usage clarification; the plan revision tracks plan approval separately. Planning preparation derives page scenes, theme mapping and navigation before design-plan init; mark AI suggestions and apply navigation_policy. Existing business apps only clarify the current change. A named resource-only request with explicitScope.allowInferredResources=false keeps planning within the specified resources. When theme mapping is missing, query design-plan catalog once and reuse its themes and pagePatterns. Init returns authoring.pendingFields and context with typed examples; complete pending facts and review coverage before setting ready=true. Reuse one complete agent-capabilities summary per unchanged environment. Standard Plan uses design-plan init parallelTasks, then executes the returned materialize.command exactly once with business-file and visual-file; preview and --from-preview are only for explicitly incremental large plans. Present the current plan without revision numbers in user-visible titles, summaries, attachments or questions. Keep revision in internal confirmation fields, validate it before building, and execute its generated artifacts.',
-        product_design_policy: 'yida-requirement-analysis owns shared facts and first-time intake. yida-prd owns business planning; yida-design owns visual design. Reuse the same confirmed brief and supplied details. Prepare business and base visuals concurrently, then bind visuals to settled page tasks. yida-app merges and checks the artifacts before creating resources. Plan authors scope, data and rules, page organization, business interactions and acceptance once. Ordered blocks {name,purpose} supply default priority and content layers; explicit designs remain authoritative. Project-specific acceptance criteria are merged with generated resource checks. Plan uses the compact authoring contract and selected theme context; the CLI reads full templates and renders all artifacts. Fast, Plan and single-page design share yida-design/templates/design-themes. Theme templates declare application-global variables from basic-tokens.json with fixed typography, spacing and Tooltip colors, plus scoped custom-page variables; component recipes consume those variables. Explicit project customization stays in visualStyle.tokens. CSS binds light and dark platform navigation to their respective brand colors and preserves white and gray modes.',
+        navigation_policy: 'Before PRD planning in Fast and Plan, the agent determines navigation ownership and layout from business context. Follow yida-design/references/navigation-decision.md for entry and layout decisions. Preserve explicit user requirements and existing navigation for local changes; resource-only requests operate on their specified resources and settings. Use native navigation by default for the application workspace, and custom navigation only for an explicitly justified application-level branded menu or special navigation interaction. A service frontend defaults to one coding page with its own menu and all selected business views; a single-step entry can use navigation.type=none. Choose backend native or coding pages by task efficiency. Backend coding pages in platform-shell are content-only: platform menus own cross-module navigation; local Tabs cover categories or states of the current task only. Never turn the management entry menu into a second page navbar, sidebar or module Tabs. Persistent filters/state alone do not justify custom application navigation. Plan handoff pages include derived navigationPolicy; Fast records the same boundary. Do not hide platform navigation to repair duplicate page menus. Store application navigation in navigationType and standalone entry menus in pageSpecHandoff.navigation. Configure a custom frontend menu at page scope and preserve workspace navigation. Record type/source/reason/variant using ai_default for agent ownership decisions and user_selected for explicit user requirements. Include navigation in the overall Plan confirmation; Fast implements the recorded decision. Platform navigation uses update-app --layout top|side|l_shape --show-app-nav, persisting layoutDirection and hideAppNav=n. Preserve stored navType. Without --layout, normalize legacy layoutDirection and navType using the application layout compatibility rules (hoz plus top_side means l_shape; missing layout uses top_fold/top_side for top/l_shape). Apply shell top_fold/none overrides at page scope. Application-wide custom side/top/mixed/dock uses app hiding plus per-page hiding within scope; a standalone frontend in a platform-navigation app uses only page configuration. Read back layoutDirection, hideAppNav and each configured page, then verify the planned frontend and workspace links. Navigation structure is separate from tone. Navigation tone is derived from the final selected theme template, never guessed from the business brief or implicitly defaulted to light; apply that explicit value with update-app --nav-theme. Custom top navigation defaults to edge-to-edge, not floating. Over a hero image, start transparent, add a surface on scroll, restore transparency at the top; expanded menus stay readable. Follow yida-design/references/page-continuity.md; floating requires an explicit design.',
+        design_mode_policy: 'Analyze requirements first with yida-requirement-analysis: read only necessary sources before the first question, offer concrete core-function candidates, clarify key usage, and preserve explicit scope and valid answers. Initial intake focuses on core functions and actual usage. Record actual user replies; proceed with dependent planning after a reply or explicit delegation. First-time builds include new apps and existing apps without business pages. After intake, reuse explicit mode choices and detailed supplied plans; if the user delegates the mode or asks for no more questions, use Fast unless Plan is explicit; otherwise, if the mode is unspecified, ask whether to prepare a PRD for confirmation (Plan, more detailed and slower) or build from the supplied requirements (Fast). Without detailed requirements, offer Fast and Plan neutrally. intake.confirmed records scope and key-usage clarification; the plan revision tracks plan approval separately. Fast and Plan share one three-direction visual generation rule. Fast compares exactly three directions internally and keeps the selected result. When Plan is explicit and the user has not supplied a complete visual direction, generate exactly three directions and use ask_human for the style choice before design-plan init; do not wait for the user to request a comparison. Planning preparation derives page scenes, selected theme mapping and navigation structure before init; mark AI suggestions and apply navigation_policy. Existing business apps only clarify the current change. A named resource-only request with explicitScope.allowInferredResources=false keeps planning within the specified resources. When theme mapping is missing, query design-plan catalog once and reuse its themes and pagePatterns. Init returns authoring.pendingFields and context with typed examples; complete pending facts and review coverage before setting ready=true. Reuse one complete agent-capabilities summary per unchanged environment. Standard Plan uses design-plan init parallelTasks, then executes the returned materialize.command exactly once with business-file and visual-file; preview and --from-preview are only for explicitly incremental large plans. Present the current plan without revision numbers in user-visible titles, summaries, attachments or questions. Keep revision in internal confirmation fields, validate it before building, and execute its generated artifacts.',
+        product_design_policy: 'yida-requirement-analysis owns shared facts and first-time intake. yida-prd owns business planning; yida-design owns visual design. Reuse the same confirmed brief and supplied details. Prepare business and base visuals concurrently, then bind visuals to settled page tasks. yida-app merges and checks the artifacts before creating resources. Plan authors scope, data and rules, page organization, business interactions and acceptance once. Ordered blocks {name,purpose} supply default priority and content layers; explicit designs remain authoritative. Project-specific acceptance criteria are merged with generated resource checks. Plan uses the compact authoring contract and selected theme context; the CLI reads full templates and renders all artifacts. Fast, Plan and single-page design share yida-design/templates/design-themes and the same three-direction generation rule. Theme templates declare application-global variables from basic-tokens.json with fixed typography, spacing and Tooltip colors, plus scoped custom-page variables; component recipes consume those variables. Each selected template is the authority for navTheme, its six navigation color tokens, and its selected-item shadow token; free-creative authors its own navigation tone and tokens. Explicit project customization stays in visualStyle.tokens. The CLI applies the selected template palette to its derived light or dark navigation mode, preserves mode-independent navigation appearance tokens, preserves inactive and white/gray platform modes, and never synthesizes a replacement navigation palette.',
         ui_guidance_policy: 'Page implementation consumes yida-prd prd.md for positioning, information architecture, page prototype, native form entry policy, material strategy, business-specific checks, resource creation order, page implementation delivery order, navigation order, and acceptance criteria; it consumes yida-design design.md for app custom theme CSS delivery, themeColor/navTheme, visual states, visualScaffold, surface material, rounded rules, density rules, components, state styling, and page-level imageNeed. When a page is imageNeed=required, or beneficial with declared image slots, yida-image-assets prepares a traceable asset manifest alongside page layout and interaction work; wait for final images only at that page\'s image binding and acceptance. imageNeed=none skips the branch. prd.md and design.md remain the only design sources of truth. Page implementation may extract page-spec.json as a derived implementation handoff from prd.md + design.md; conflicts are resolved by sending business conflicts to yida-prd and visual conflicts to yida-design before regenerating the spec. Core normal forms default to 1-3 business sample records before page implementation, followed by query readback. An explicit opt-out, configuration dictionary, sensitive data, or lack of safely constructible values requires a recorded skip reason. Screenshots, public sharing, data-source deep binding, and fine navigation grouping are optional after explicit user request or PRD acceptance criteria.',
         default_nav_order_policy: 'For application-wide custom navigation, implement each entry menu and verify app/page navigation hiding. A standalone frontend preserves platform navigation for the management workspace; frontend-only delivery skips platform ordering. After all scoped resources and page publications finish, perform exactly one navigation order operation. Use management tasks and their default destination, without creating a homepage or putting a frontend page first. When execution.entryRecommendation exists, derive navigationOrder from its management/workspace menus. Call openyida nav-group order <appType> <items...> for an explicit order; otherwise call openyida nav-group auto-order <appType> once for legacy single-workspace plans. Do not use openyida publish ... --auto-nav-order for per-page application builds. Explicit and automatic ordering are mutually exclusive; never generate per-item move loops.',
-        final_link_policy: 'Return exactly one user-visible application entry group, never one artifact or link card per form, process, report, schema, manifest, PRD, design file, or intermediate artifact. Include one verified management entry when a management or unified workspace is in scope: the app workbench URL or a planned workbench/formUuid URL with its real viewUuid. Native management does not require a display homepage; frontend-only delivery includes its verified frontend entry and developer admin URL, without inventing a business backend. Add the clean custom page URL only when PRD entryMode=standalone and get-form-config readback confirms renderNav=false (fallback to isRenderNav only when renderNav is absent). Complete application delivery defaults to 2-3 distinct entries: frontend or unified workspace, business backend when separately planned, and developer admin. agent-capabilities application_entry_policy.entries.admin=include is independent of auth runtime. Read adminUrl from create-app or app-list results; route construction does not verify recipient permissions. Explicit user exclusions take precedence; single-page tasks retain their scope. Put the business summary, verification results and remaining work in the terminal delivery artifact description; when no delivery tool is available, return the same content and entry group in the final response. Summarize business resources by capability or count, but every resource count, seed-record count, and completed/verified claim must come from that resource\'s own successful result or readback. When the user or caller explicitly requests a resource manifest, resource UUIDs/IDs, publish status, or test-data summary, include one concise verified delivery manifest in that description (or the final response when no delivery tool is available).',
+        final_link_policy: 'Return exactly one user-visible application entry group, never one artifact or link card per form, process, report, schema, manifest, PRD, design file, or intermediate artifact. Include one verified management entry when a management or unified workspace is in scope: the app workbench URL or a planned workbench/formUuid URL with its real viewUuid. Backend-only returns its verified business backend entry and developer admin URL without adding a frontend. Native management does not require a display homepage; frontend-only delivery includes its verified frontend entry and developer admin URL, without inventing a business backend. Add the clean custom page URL only when PRD entryMode=standalone and get-form-config readback confirms renderNav=false (fallback to isRenderNav only when renderNav is absent). Complete application delivery defaults to 2-3 distinct entries: frontend or unified workspace, business backend when separately planned, and developer admin. agent-capabilities application_entry_policy.entries.admin=include is independent of auth runtime. Read adminUrl from create-app or app-list results; route construction does not verify recipient permissions. Explicit user exclusions take precedence; single-page tasks retain their scope. Put the business summary, verification results and remaining work in the terminal delivery artifact description; when no delivery tool is available, return the same content and entry group in the final response. Summarize business resources by capability or count, but every resource count, seed-record count, and completed/verified claim must come from that resource\'s own successful result or readback. When the user or caller explicitly requests a resource manifest, resource UUIDs/IDs, publish status, or test-data summary, include one concise verified delivery manifest in that description (or the final response when no delivery tool is available).',
         entry_navigation_contract: {
           reference: 'yida-skills/skills/yida-app/references/entry-navigation.md',
           brief_path: 'entryRecommendation',
           plan_path: 'execution.entryRecommendation',
           input_transport: 'JSON file or design-plan patch --set execution.entryRecommendation=<json>; not a CLI flag',
-          modes: ['unified', 'service-management', 'frontend-only'],
+          modes: [...ENTRY_MODES],
+          mode_meaning: 'These modes describe how people use the application, not developer administration: unified shares business pages with role-based menus and permissions; service-management separates pages for people requesting a service and people processing it; frontend-only delivers only the requested frontend; backend-only delivers staff pages for recording, processing or maintaining business, with service requests originating elsewhere or no service entry required. For frontend-only submissions that need processing, record the existing system, staff entry or automation in reason and business flows; unresolved handling remains an open question. Backend-only entries use role management; new unified plans normally use workspace, while legacy unified plans retain their roles. Different roles alone do not require separate frontends and backends. Separate entries can share one application and its data.',
+          user_facing_explanation: 'Say whether the system has separate frontend and business-backend pages, then explain who uses each entry, what they see and what they can do. Choose from confirmed tasks; if actual usage is unclear and changes the page plan, ask a concrete business-use question.',
+          derived_summary: 'execution.entryModeSummary is generated for PRD and preview from the selected mode; do not author it in build-plan.json.',
           roles: ['service', 'management', 'workspace'],
           entry_required_fields: ['key', 'name', 'role', 'menu', 'defaultMenuKey'],
           service_page_binding: 'sceneKey of a standalone page',
@@ -1850,7 +1906,7 @@ function summarizeLocalizedCommands(commands) {
           'yida-data-source-connectors',
           'yida-dashboard',
         ],
-        completion_contract: 'Clarify core functions and actual usage first, then resolve the required resource context and settle entry navigation before PRD planning. Fast generates prd.md and design.md in parallel; Plan uses design-plan init/preview/materialize/patch and confirms the current revision. Validate both artifacts, create or reuse app and core forms/processes, seed and query-check core normal-form samples or record an allowed skip reason, then implement the primary page in PRD resource order, publish it, apply PRD navigation order or lightweight fallback navigation order for platform navigation, or verify app and per-page hiding for application-wide custom navigation. For a standalone frontend in a platform-navigation app, verify that page independently and retain workspace navigation. Return one named application entry group. Include workbench when a management or unified workspace is in scope; frontend-only delivery includes its verified frontend entry and developer admin URL, without inventing a business backend. Always include developer adminUrl for complete application delivery unless explicitly excluded by the user, regardless of auth runtime; this is separate from the optional business backend. Use create-app or app-list URL fields and state any unavailable entry instead of silently omitting it. Put the verified business summary, results and remaining work in the delivery artifact description; use the final response when no delivery tool is available.',
+        completion_contract: 'Clarify core functions and actual usage first, then resolve the required resource context and settle entry navigation before PRD planning. Fast generates prd.md and design.md in parallel; Plan uses design-plan init/preview/materialize/patch and confirms the current revision. Validate both artifacts, create or reuse app and core forms/processes, seed and query-check core normal-form samples or record an allowed skip reason, then implement the primary page in PRD resource order, publish it, apply PRD navigation order or lightweight fallback navigation order for platform navigation, or verify app and per-page hiding for application-wide custom navigation. For a standalone frontend in a platform-navigation app, verify that page independently and retain workspace navigation. Return one named application entry group. Include workbench when a management or unified workspace is in scope; backend-only delivers its business backend and developer admin URL without adding a frontend; frontend-only delivery includes its verified frontend entry and developer admin URL, without inventing a business backend. Always include developer adminUrl for complete application delivery unless explicitly excluded by the user, regardless of auth runtime; this is separate from the optional business backend. Use create-app or app-list URL fields and state any unavailable entry instead of silently omitting it. Put the verified business summary, results and remaining work in the delivery artifact description; use the final response when no delivery tool is available.',
       },
     },
   };