openyida 2026.9.20 → 2026.9.21

package/README.md

@@ -399,7 +399,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida design-plan catalog [--json]` | List available planning themes and page patterns |
 | `openyida design-plan init <requirement-brief.json> [--theme-id <id>] [--output-dir <dir>] [--json]` | Initialize a plan draft from confirmed requirements |
 | `openyida design-plan preview <build-plan.json> --part-file <module.json> [--json]` | Update plan drafts by module |
-| `openyida design-plan materialize <build-plan.json> [--from-preview \| --business-file <json> --visual-file <json>] [--output-dir <dir>] [--check] [--json]` | Generate or update plan documents and theme with consistency checks |
+| `openyida design-plan materialize <build-plan.json> [--from-preview \| --business-file <json> --visual-file <json>] [--output-dir <dir>] [--rebase-parts] [--check] [--json]` | Generate or update plan documents and theme with consistency checks |
 | `openyida design-plan patch <build-plan.json> --set <path=value> [--set <path=value> ...] [--materialize] [--output-dir <dir>] [--json]` | Patch plan fields and optionally sync documents and theme |
 | `openyida update-app <appType> [--name "..."] [--desc "..."] [--icon <name>] [--icon-color <color>] [--colour <key>] [--theme-color <color>] [--theme-file <css>] [--nav-theme light\|dark\|white\|gray] [--logo-source appIcon\|customImage] [--layout side\|top\|l_shape] [--hide-app-nav\|--show-app-nav]` | Update app info |
 | `openyida app-online <appType> [--to-ding-app-center] [--show-app-center]` | Enable a Yida app |

package/lib/app/application-style.js

@@ -13,6 +13,8 @@ const CREATIVE_TOKENS = [
   '--pod-page-footer-bg-color', '--pod-sticky-footer-box-shadow',
   '--oyd-content-width', '--oyd-content-padding', '--oyd-field-gap',
   '--oyd-heading-font', '--oyd-heading-size', '--oyd-rule-style',
+  '--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',
 ];
 
 function validateCreativeDirection(direction, tokens) {
@@ -46,7 +48,7 @@ function applyApplicationStyle(css, metadata, tokens) {
 }
 
 function exportApplicationStyle(id, outputDirectory) {
-  const theme = loadThemeIndex().themes.find(item => item.themeId === id && item.collection === 'application-styles');
+  const theme = loadThemeIndex().themes.find(item => item.themeId === id);
   if (!theme) {throw new CliError(t('design_document.invalid', id || '--style-id', 'APPLICATION_STYLE_UNKNOWN'), { code: 'APPLICATION_STYLE_UNKNOWN' });}
   const directory = path.resolve(outputDirectory);
   const assets = [['design.md', theme.templatePath], ['app_theme.css', theme.cssTemplatePath], ['form-layout.json', theme.formLayoutPath]];

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,11 +128,30 @@ 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;

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.',
         ],
       }),
@@ -1582,9 +1587,13 @@ const COMMAND_GROUPS = [
       command('copy', ['copy'], 'copy [--force]', 'help.cmd_copy', { requiresLogin: false }),
       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 application-style --style-id exports a design/CSS/native-layout authoring bundle to an output directory without overwriting files. Use design-plan catalog for presets and its separate creativeOption; free creative requires independent business decisions and explicit design tokens.',
+          '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.',
@@ -1597,10 +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: 'styleId', type: 'string', source: 'option', builder_options: ['--style-id'], description: 'For yida-design application-style: export paired design.md, app_theme.css and native form-layout.json to --output directory. Includes independent free-creative authoring.' },
+          { 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 }),
@@ -1804,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',
@@ -1894,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.',
       },
     },
   };

package/lib/core/locales/en.js

@@ -4,6 +4,13 @@
 'use strict';
 
 module.exports = {
+  design_plan: {
+    rebase_required: 'Before first materialization, repair the matching facts in business.json/visual.json and preserve the source baseline. If the source changed, add --rebase-parts to the original materialize command to reconcile against the saved baseline. Do not invent a digest, delete drafts, or run init again.',
+    baseline_missing: 'No trusted baseline matches these parts. Preserve the plan and facts; restore .build-plan-base.json from the original workspace. If unavailable, report the blocker instead of inventing a digest or rebuilding.',
+    rebase_stage_invalid: 'Rebasing is limited to drafts before first materialization. For presented or materialized plans use patch --materialize on the current build-plan.json, without merging initial parts again.',
+    rebase_conflict: 'The source and part changed the same field differently. Review conflicts and explicitly select the current or baseline value in the part before retrying; preserve other facts. No files were saved.',
+    repair_page_bindings: 'Repair pageApplications in visual.json to match customPageDetails in business.json one to one; exclude native forms. Each visualMemoryApplications must be an array; use [] when none apply. Keep the existing draft, fix the listed fields and retry the original command. Do not delete the directory or run init again.',
+  },
   design_document: {
     update_conflict: 'Cannot update {0} ({1}): the existing content differs from the last generated version. Read this section, reconcile the local edit with the plan source, and retry. No files were saved.',
     theme_css_invalid: 'Theme CSS near line {0} has an unclosed or mismatched delimiter, string, or comment. Fix it and retry.',
@@ -174,6 +181,8 @@ module.exports = {
   },
 
   cli: {
+    design_plan_entry_mode_required: 'Choose an entry mode: shared business pages (unified), separate frontend and business backend (service-management), frontend only (frontend-only), or business backend only (backend-only).',
+    design_plan_backend_only_roles: 'For backend-only, every entry must use role management.',
     design_plan_local_menu_binding: 'Local menu {0} requires a host page and viewKey: entry {1} sceneKey must match the page sceneKey, menu resource must equal the page name, and viewKey must be nonempty. This applies to every entry role.',
     design_plan_visual_object_required: '{0} must be an object, not a string or array. Preserve the structure generated by init and fill in its values. Example: {1}.',
     help: `
@@ -1152,6 +1161,7 @@ Examples:
     theme_preset_conflict: 'A preset colour cannot be combined with custom CSS or themeColor. Use --colour custom or omit --colour.',
     custom_theme_color_required: 'colour=custom requires a theme file or a valid themeColor. Pass --theme-file or --theme-color.',
     theme_not_persisted: 'App theme readback failed or did not match the saved settings. The CSS resource binding is unverified. Inspect themeVerification and retry update-app <appType> --theme-file <css>; do not refresh the app.',
+    navigation_not_persisted: 'App navigation readback failed or did not match the requested settings. Navigation changes remain unverified. Inspect the expected values, actual values and readback error in navigationVerification, then check the current app settings.',
     usage: 'openyida update-app <appType> [--name "New Name"] [--theme-file ./theme.css] [--nav-theme light|dark|white|gray] [--logo-source appIcon|customImage] [--layout side|top|l_shape]',
     example: 'openyida update-app APP_XXX --theme-file ./app-theme.css --nav-theme light --logo-source appIcon --layout side',
     options: 'Options:\n  --name, -n      App name (specify at least one update field)\n  --desc, -d      App description\n  --icon          Icon name (e.g. xian-yingyong)\n  --icon-color    Icon color (default: #0089FF)\n  --colour, --theme  podBlue | podGreen | podOrange | deepBlue | teal | black | custom ...\n  --theme-color   Update the app primary color; the CSS primary color takes precedence when a theme file is supplied\n  --theme-file    Custom app theme CSS file (up to 20 MB; must declare --color-brand1-6)\n  --nav-theme     Navigation theme: light, dark, white, or gray\n  --logo-source   Navigation logo source: appIcon or customImage\n  --layout        Modern navigation layout: side, top, or l_shape\n  --hide-app-nav  Hide app navigation in visit mode, only for custom pages with self-rendered top/side navigation\n  --show-app-nav  Restore app navigation in visit mode',
@@ -2123,3 +2133,10 @@ module.exports.connector_e2e = {
 Object.assign(module.exports.process_errors || (module.exports.process_errors = {}), {
   action_config_invalid: 'Invalid approval action configuration for node {0}: {1}',
 });
+
+module.exports.cli_argument = { invalid: 'Invalid or missing argument value: {0}. Follow the command help.' };
+
+module.exports.sample_options = {
+  'theme_help': 'app-theme: --output is a CSS file; --design-file reads a completed design. Omitting it resets CSS. Set theme values in the design.',
+  'style_help': 'application-style: --style-id is required and accepts every catalog theme; --output is a directory for three files. Existing bundle files cause an error.'
+};

package/lib/core/locales/zh.js

@@ -4,6 +4,13 @@
 'use strict';
 
 module.exports = {
+  design_plan: {
+    rebase_required: '首次物化前请修正 business.json/visual.json 中的对应 facts，保留主计划基线。如果主计划已改变，在原 materialize 命令加 --rebase-parts，CLI 会根据保存的基线核对差异；不要手填 digest、删除草稿或重新 init。',
+    baseline_missing: '未找到与片段匹配的可信原始基线。保留当前计划与 facts；从原工作区恢复 .build-plan-base.json 后重试。无法恢复时明确告知用户阻塞，不伪造摘要或自动重建。',
+    rebase_stage_invalid: '基线恢复仅用于首次物化前的草稿。已展示或已物化方案请沿用当前 build-plan.json，通过 patch --materialize 调整，不再合并初始化片段。',
+    rebase_conflict: '主计划和片段对同一字段有不同修改。按 conflicts 核对并在片段中明确采用当前值或原基线值后重试；其他 facts 保留。本次未保存文件。',
+    repair_page_bindings: '按 business.json 的 customPageDetails 逐一修复 visual.json 的 pageApplications；原生表单不加入绑定。每项 visualMemoryApplications 必须为数组，无适用项用 []。保留现有草稿，按列出的字段修复后重试原命令；不要删除目录或重新 init。',
+  },
   design_document: {
     update_conflict: '无法更新 {0}（{1}）：现有内容与上次生成结果冲突。请读取这一部分，将本地修改与计划源对齐后重试；本次未保存任何文件。',
     theme_css_invalid: '主题 CSS 第 {0} 行附近存在未闭合或不匹配的括号、字符串或注释，请修复后重试。',
@@ -174,6 +181,8 @@ module.exports = {
   },
 
   cli: {
+    design_plan_entry_mode_required: '请明确入口方式：不分前后台（unified）、分前后台（service-management）、只有访问前台（frontend-only）或只有访问后台（backend-only）。',
+    design_plan_backend_only_roles: '只有访问后台（backend-only）时，每个入口的 role 必须为 management。',
     design_plan_local_menu_binding: '本地菜单 {0} 必须关联承载页面和 viewKey：入口 {1} 的 sceneKey 对应页面 sceneKey，菜单 resource 等于页面 name，并填写非空 viewKey。此规则适用于所有入口身份。',
     design_plan_visual_object_required: '{0} 必须为对象，不能写成字符串或数组。沿用 init 生成的字段结构，只补齐值；示例：{1}。',
     help: `
@@ -1082,6 +1091,7 @@ openyida - 宜搭命令行工具
     theme_preset_conflict: '平台预置 colour 不能与自定义 CSS 或 themeColor 同传；请使用 colour=custom 或省略 --colour。',
     custom_theme_color_required: 'colour=custom 需要主题文件或有效 themeColor；请传 --theme-file 或 --theme-color。',
     theme_not_persisted: '应用主题保存后回读不一致或查询失败，CSS 资源尚未确认绑定。请查看 themeVerification，并使用 update-app <appType> --theme-file <css> 重试；不要重复创建应用。',
+    navigation_not_persisted: '应用导航保存后回读不一致或查询失败，导航设置尚未确认生效。请查看 navigationVerification 中的期望值、实际值和查询错误，核实应用当前设置。',
     usage: 'openyida update-app <appType> [--name "新名称"] [--theme-file ./theme.css] [--nav-theme light|dark|white|gray] [--logo-source appIcon|customImage] [--layout side|top|l_shape]',
     example: 'openyida update-app APP_XXX --theme-file ./app-theme.css --nav-theme light --logo-source appIcon --layout side',
     options: '选项:\n  --name, -n      应用名称（至少指定一个更新字段）\n  --desc, -d      应用描述\n  --icon          图标名称（如: xian-yingyong）\n  --icon-color    图标颜色（默认: #0089FF）\n  --colour, --theme  podBlue | podGreen | podOrange | deepBlue | teal | black | custom ...\n  --theme-color   更新应用主色；与主题文件同传时以 CSS 主色为准\n  --theme-file    自定义应用主题 CSS 文件（最大 20 MB，必须声明 --color-brand1-6）\n  --nav-theme     导航主题 light、dark、white 或 gray\n  --logo-source   导航 Logo 来源 appIcon 或 customImage\n  --layout        新版导航布局 side、top 或 l_shape\n  --hide-app-nav  隐藏访问态应用导航，仅在自定义页自绘顶部/侧边导航壳时使用\n  --show-app-nav  恢复访问态应用导航',
@@ -2077,3 +2087,10 @@ module.exports.connector_e2e = {
 Object.assign(module.exports.process_errors || (module.exports.process_errors = {}), {
   action_config_invalid: '节点 {0} 的审批动作配置无效：{1}',
 });
+
+module.exports.cli_argument = { invalid: '参数无效或缺少值：{0}。请按命令帮助填写。' };
+
+module.exports.sample_options = {
+  'theme_help': 'app-theme：--output 指向 CSS 文件；--design-file 读取已完成的设计。省略设计文件会重置 CSS，主题值通过设计填写。',
+  'style_help': 'application-style：--style-id 必填，支持目录中全部主题；--output 指向目录，输出三文件，有同名文件时报错。'
+};