openyida 2026.9.23-beta.2 → 2026.9.23

package/README.md

@@ -118,6 +118,7 @@ The agent can then call OpenYida commands to create the application, generate so
 | [Codex](https://openai.com/codex/) | Full support |
 | [Claude Code](https://claude.ai/code) | Full support |
 | [MuleRun](https://mulerun.com) | Full support |
+| [OpenCode](https://opencode.ai) | Full support |
 | [Cursor](https://cursor.com/) | Full support |
 | [Visual Studio Code](https://code.visualstudio.com/) | Full support |
 | QwenWork（千问办公） | Full support |
@@ -182,7 +183,7 @@ openyida get-schema APP_XXX FORM_XXX --compact --resolve-fields "Customer Name,S
 openyida get-schema APP_XXX --all --output-dir .cache/schemas
 ```
 
-Form definitions support 19 business field types plus verified presentation/layout components. Prefer `Divider` for section titles and `ColumnContainer` (mapped to `ColumnsLayout` + `Column`) for multi-column layout; use `GroupContainer` / `PageSection` only when an actual grouping container is needed.
+Native forms use a component tree: business fields capture data, tabs switch content, action groups trigger business actions, images establish visual focus, status areas provide feedback, and `Divider` plus `ColumnContainer` organize hierarchy and columns. `create-form` field definitions create 19 business field types plus `Divider` and `ColumnContainer` (mapped to `ColumnsLayout` + `Column`), while updates retain other existing components.
 
 ### Custom Page Development
 
@@ -392,13 +393,15 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 | Command | Description |
 |---------|-------------|
+| `openyida app-entry get <appType> [--json]` | Read frontend and management runtime entries |
+| `openyida app-entry set <appType> [--frontend <url>\|--frontend-page <formUuid>] [--management <url>\|--management-page <formUuid>] [--clear-frontend] [--clear-management] [--json]` | Register application entries with partial update and readback |
 | `openyida app-list [--type managed\|created] [--page N] [--size N]` | Page through apps I manage or created |
 | `openyida corp-efficiency [overview\|details\|detail\|groups\|notify] [options] [--open\|--no-open]` | Query enterprise efficiency overview and detail reports |
 | `openyida create-app "<name>"\|--name <name> [options] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a Yida app |
 | `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 |
@@ -414,7 +417,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | Command | Description |
 |---------|-------------|
 | `openyida create-form batch <appType> <plan.json> [--concurrency 1..4] [--check] [--json]` | Create forms concurrently by dependency |
-| `openyida create-form create <appType> "<formTitle>" <fieldsJsonFile> [--icon auto\|<iconName>] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
+| `openyida 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]` | Create a form page |
 | `openyida create-form icons [--json]` | List available form navigation icons |
 | `openyida create-form validate-fields <fieldsJsonOrFile> [--json]` | Validate form field JSON locally |
 | `openyida create-form update <appType> <formUuid> (<changesJsonOrFile> \| --data-file <changesJsonOrFile>) [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Update a form page |
@@ -434,8 +437,8 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida create-page <appType> "<name>" [--mode dashboard] [--hide-nav] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a custom display page |
 | `openyida build-page <sourceFile> [--output file\|--write]` | Build Yida-compatible page source |
 | `openyida check-page <src> [--compat] [--json]` | Check custom page standards |
-| `openyida compile <src> [--canvas] [--compat] [--skip-lint] [--json]` | Compile custom page locally |
-| `openyida publish <src> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--auto-nav-order] [--open\|--no-open] [--json]` | Compile and publish custom page |
+| `openyida compile <src> [--canvas] [--compat] [--skip-lint] [--strict-theme\|--allow-fixed-brand] [--json]` | Compile custom page locally |
+| `openyida publish <src> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--fix-theme] [--strict-theme] [--allow-fixed-brand] [--auto-nav-order] [--open\|--no-open] [--json]` | Compile and publish custom page |
 | `openyida update-form-config <appType> <formUuid> <true\|false\|keep> "<title>" [--locale zh_CN\|en_US\|ja_JP]` | Update form configuration |
 | `openyida get-form-config <appType> <formUuid> [--json]` | Query form configuration |
 
@@ -519,11 +522,10 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 |---------|-------------|
 | `openyida commands [--json]` | Output machine-readable command manifest |
 | `openyida agent-capabilities [--json] [--summary-json\|--compact]` | Output one-shot agent capability snapshot |
-| `openyida agent <doctor\|diagnose\|status\|connect\|run\|disconnect\|logout> [options]` | Connect a local Agent (Go runtime, development preview) |
 | `openyida a2a <serve\|agent-card> [options]` | Start local read-only A2A adapter or print Agent Card |
 | `openyida bridge start [--token <pair-token>] [--port 6736] [--origin https://demo.aliwork.com] [--open\|--no-open]` | Start OpenYida local web bridge service |
 | `openyida copy [--force]` | Copy project working directory |
-| `openyida sample [--list] [<skill> <name>] [--output <file>] [--var KEY=VALUE ...] [--design-file <design.md>]` | Output code samples/templates |
+| `openyida sample [--list] [<skill> <name>] [--output <file-or-directory>] [--var KEY=VALUE ...] [--design-file <design.md>] [--style-id <themeId\|free-creative>]` | Output code samples/templates |
 | `openyida doctor [--fix]` | Environment diagnostics & auto-fix |
 | `openyida db-seq-fix [--fix]` | Detect and repair PostgreSQL sequence drift |
 | `openyida formula evaluate <formula\|file> [--schema file]` | Static-check Yida formula syntax and field refs |
@@ -588,31 +590,6 @@ Form field definitions can include `alias` or `componentAlias` to populate Yida
 
 `openyida integration create` supports form events (`insert`, `update`, `delete`, `comment`) and approval events (`processFinish`, `activityTask`; aliases: `approval`, `approvalNode`). Approval events require `--approval-actions agree,disagree,terminated`; `activityTask` also requires `--approval-node-ids <nodeId,...>`. Passing `--process-code` selects a full graph replacement and now requires explicit `--replace`; it is not a safe update. `integration update` currently performs capability detection only: because full platform `processJson` + `viewJson` readback is unproven, it writes a redacted local probe artifact and returns `PLATFORM_PROBE_REQUIRED` before authentication, spec reading, or remote writes. It does not edit a flow.
 
-### Local Agent development preview
-
-`openyida agent` is a thin Node launcher for a separately supplied Go runtime. Node does not connect to the agent service or manage provider sessions. Platform runtime packages are **not published** in this preview; no Go executable is discovered on `PATH` and no provider is installed or invoked by Node.
-
-The Local Agent Beta production allowlist contains macOS and Windows only. Linux remains supported by the ordinary OpenYida CLI and by the explicit development-runtime workflow below, but Linux Local Agent packages are not published and production `connect`/`run` are rejected until native acceptance is complete.
-
-```bash
-openyida agent doctor --json
-openyida agent doctor --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json
-openyida agent connect --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json --endpoint https://agent.example.test --endpoint-id configured-platform-id
-openyida agent run --development-runtime --runtime-path /absolute/path/openyida-runtime --runtime-manifest /absolute/path/runtime-manifest.json --endpoint https://agent.example.test --endpoint-id configured-platform-id --provider qoder --provider-path /absolute/path/qodercli
-```
-
-Development manifest v1 specifies runtime version, protocol `1`, Node-style OS/architecture names, and `binary: {file, sha256}`; it requires the explicit `--development-runtime` flag. This is an integrity check, **not a publisher signature**. The production loader requires a strictly validated v2 manifest, exact approved platform-package version/digest, and an Ed25519 signature over the original manifest bytes using trust roots bundled in the Node host. The release catalog is currently empty: no production signing key or package is implied to exist. See the [launcher contract](lib/agent/PROTOCOL.md).
-
-`connect` supports two equivalent enrollment entries. CLI-first opens the Yida browser approval page and returns through a state/PKCE-protected loopback callback. Web-first copies one five-minute command containing `--enroll`; the token is single-use and carries no business authority. Neither path reads or uploads an ordinary OpenYida login profile.
-
-One installation may connect to multiple organizations. Node keeps only a shared Installation ID at the installation root; each organization authorization gets an isolated private Connection state directory, device credentials, journals, control socket, and frozen bundle. `agent connect` keeps the new Connection online in the foreground, while `agent run`, `status`, `disconnect`, and `logout` enumerate every valid Connection. Each Connection registers all locally discovered Qoder and Codex Runtimes, and the web UI selects computer, CLI, and model.
-
-For each attempt, Go injects `OPENYIDA_MANAGED_RUN=1`, the cloud user/corp/app/run/attempt context, and a fixed-value Tianshu task grant with an initial 60-minute lease. The CLI uses that grant instead of local auth and sends scope-correlation headers. While the authenticated device connection and server-side Run remain active, yida-agent can renew the same bearer server-to-server; the CLI cannot renew it and never receives a task refresh token. Tianshu independently checks the grant against the requested app and rejects application creation, identity/environment changes, arbitrary batches, and cross-application requests. `formUuid` remains optional per-turn page-focus context, so one app-bound session can work across pages in that application. Without `OPENYIDA_MANAGED_RUN`, existing login, token refresh, and command behavior are unchanged.
-
-Before `connect` or `run`, Node now freezes the verified runtime bytes, CLI, full production dependency closure, and packaged Skills into a private content-addressed bundle. Source changes during copying fail closed. Existing bundles are verified, never silently repaired or garbage-collected by Node, and survive replacement/removal of the original npm directory. Go owns active/session references and version activation; the external Node executable and provider installations are not copied or managed by npm. A separate parent-watch pipe and a 15-second stop grace prevent normal config EOF from being mistaken for parent death; an unconfirmed forced stop remains unknown.
-
-This is not an OS sandbox or an authorization boundary against arbitrary shell code. Production signing/release infrastructure, full Go/provider recovery and upgrade acceptance, and OS/architecture-specific provider E2E are not claimed by these fake-process tests. Auto-update is disabled for `agent` and managed invocations; ordinary CLI commands neither spawn nor download the runtime.
-
 ## Agent Skills
 
 The `yida-skills/` directory is the source skill library used by OpenYida during development and distributed with the npm package.

package/bin/yida.js

@@ -24,8 +24,6 @@ const { COMMAND_GROUPS, buildCommandManifest, findCommandSuggestion } = require(
 const command = process.argv[2];
 const args = process.argv.slice(3);
 const rawArgs = process.argv.slice(3);
-const { beginCommandReceipt } = require('../lib/agent/command-receipt');
-let commandReceipt;
 
 function shouldUseEnvManagement(argsList) {
   const subCommand = argsList[0];
@@ -573,26 +571,6 @@ function assertNoUnsupportedLegacyLoginFlags(...argLists) {
 }
 
 async function main() {
-  const { assertManagedInvocation, resolveManagedHelp } = require('../lib/agent/managed-run');
-  const { readManagedContext } = require('../lib/agent/managed-context');
-  if (readManagedContext() && [command, ...rawArgs].some(arg => arg === '--help' || arg === '-h')) {
-    assertManagedInvocation(command, rawArgs);
-    const entries = resolveManagedHelp(command, rawArgs, { t, version: currentVersion });
-    // Managed help is static and local: no Receipt, auth, update, first-run
-    // guide or business command module may run on this path.
-    commandReceipt = { finish() {} };
-    if (rawArgs.includes('--json')) {
-      console.log(JSON.stringify({ name: 'openyida', version: currentVersion, commands: entries }, null, 2));
-    } else {
-      printCommandUsage(...entries.flatMap(entry => [entry.usage, entry.description, ...(entry.examples || [])]));
-    }
-    return;
-  }
-  commandReceipt = beginCommandReceipt({ command, args: rawArgs });
-  process.once('exit', code => {
-    try {commandReceipt.finish(code);} catch {process.exitCode = 1;}
-  });
-  assertManagedInvocation(command, rawArgs);
   applyQuietFlag();
   applyGlobalEnvironmentFlags();
 
@@ -641,12 +619,6 @@ async function main() {
       break;
     }
 
-    case 'agent': {
-      const { run } = require('../lib/agent/cmd');
-      await run(args);
-      break;
-    }
-
     case 'mcp': {
       const { runStdioServer } = require('../lib/mcp/server');
       runStdioServer();
@@ -761,6 +733,12 @@ async function main() {
       break;
     }
 
+    case 'app-entry': {
+      const { run } = require('../lib/app/app-entry');
+      await run(args);
+      break;
+    }
+
     case 'app-list': {
       const { run } = require('../lib/app/app-list');
       await run(args);
@@ -916,8 +894,8 @@ async function main() {
       if (args.length < 4) {
         throwCliUsage(t('cli.form_config_usage'), t('cli.form_config_example'));
       }
-      const { run: runUpdateFormConfig } = require('../lib/app/update-form-config');
-      await runUpdateFormConfig(args);
+      process.argv = [process.argv[0], process.argv[1], ...args];
+      require('../lib/app/update-form-config');
       break;
     }
 
@@ -1303,9 +1281,7 @@ async function main() {
 }
 
 main()
-  .then(() => { commandReceipt.finish(process.exitCode || 0); })
   .catch((err) => {
-    try {commandReceipt?.finish(err && err.exitCode ? err.exitCode : 1);} catch { /* Intent remains recoverable. */ }
     if (shouldUseStructuredErrorOutput(err, args)) {
       console.error(JSON.stringify(toErrorPayload(err), null, 2));
     } else if (isCliError(err)) {
@@ -1316,5 +1292,7 @@ main()
     } else {
       warn(t('cli.exec_failed', err.message));
     }
-    process.exit(err && err.exitCode ? err.exitCode : 1);
+    // Let pending stdout/stderr writes drain, especially large JSON diagnostics
+    // sent through pipes on macOS/Linux. process.exit() can truncate them.
+    process.exitCode = err && err.exitCode ? err.exitCode : 1;
   });

package/lib/app/app-entry.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const { createAuthRef, createYidaClient, unwrapYidaResponse } = require('../core/yida-client');
+const { t } = require('../core/i18n');
+const { throwUsage } = require('../core/command-errors');
+const { fetchFormPageList } = require('./form-navigation');
+
+/** Keep complete runtime URLs; the server verifies tenant and resource ownership. */
+function normalizeUrl(value, appType) {
+  const input = String(value || '').trim();
+  if (!input) { throw new Error(t('app_entry.invalid_url')); }
+  // eslint-disable-next-line no-control-regex -- reject control characters in persisted URLs
+  if (input.length > 2048 || /[\\\s\x00-\x1f\x7f]/.test(input)) {
+    throw new Error(t('app_entry.invalid_url'));
+  }
+  const match = /^https?:\/\/[^/?#]+(\/[^?#]*)(?:\?([^#]*))?(?:#(.*))?$/i.exec(input);
+  if (!match) { throw new Error(t('app_entry.invalid_url')); }
+  const url = new URL(input);
+  const route = match[1];
+  const prefix = `/${appType}/`;
+  const parts = route.startsWith(prefix) ? route.slice(prefix.length).split('/') : [];
+  const short = /^\/(?:s\/[A-Za-z0-9_-]+|o\/[A-Za-z0-9_-]+(?:\/FORM-[A-Za-z0-9_-]+)?)$/.test(route);
+  const runtime = ['custom', 'workbench', 'submission', 'manage'].includes(parts[0]) &&
+    ((parts.length === 1 && parts[0] === 'workbench') ||
+      (parts.length === 2 && /^[A-Za-z0-9_-]+$/.test(parts[1])));
+  if (url.username || url.password || url.pathname !== route || (!short && !runtime)) {
+    throw new Error(t('app_entry.invalid_url'));
+  }
+  if (match[2] !== undefined) {
+    const seen = new Set();
+    for (const parameter of match[2].split('&')) {
+      const pair = /^(corpid|locale|viewUuid|processCode|hideLeftNav|noShowTopBottom)=([A-Za-z0-9_-]+)$/.exec(parameter);
+      if (!pair || seen.has(pair[1]) ||
+        (['hideLeftNav', 'noShowTopBottom'].includes(pair[1]) && !/^(true|false|y|n|0|1)$/.test(pair[2]))) {
+        throw new Error(t('app_entry.invalid_url'));
+      }
+      seen.add(pair[1]);
+    }
+  }
+  if (match[3] !== undefined && !/^[A-Za-z0-9_/-]+$/.test(match[3])) {
+    throw new Error(t('app_entry.invalid_url'));
+  }
+  return input;
+}
+
+/** Resolve a page identifier into the canonical entry URL the platform expects. */
+async function resolveEntryUrl(authRef, appType, key, formUuid) {
+  if (!/^[A-Za-z0-9_-]+$/.test(String(formUuid || ''))) {
+    throw new Error(t('app_entry.invalid_url'));
+  }
+  const forms = await fetchFormPageList(appType, authRef);
+  const form = Array.isArray(forms) ? forms.find((item) => item.formUuid === formUuid) : null;
+  if (!form) { throw new Error(t('app_entry.page_not_in_app', formUuid)); }
+  if (key === 'frontend') {
+    if (String(form.formType).toLowerCase() !== 'display') { throw new Error(t('app_entry.frontend_display_required', formUuid)); }
+    if (!form.pathName) { throw new Error(t('app_entry.page_offline', formUuid)); }
+    return normalizeUrl(`${authRef.baseUrl}/${appType}/custom/${formUuid}`, appType);
+  }
+  return normalizeUrl(`${authRef.baseUrl}/${appType}/workbench/${formUuid}`, appType);
+}
+
+/** Reject duplicate or ambiguous flags; omissions never clear stored entries. */
+function parseArgs(args) {
+  const [action, appType, ...flags] = args;
+  if (!['get', 'set'].includes(action) || !/^[A-Za-z0-9_-]+$/.test(appType || '')) {
+    throwUsage(t('app_entry.usage'));
+  }
+  const values = {};
+  for (let index = 0; index < flags.length; index++) {
+    const flag = flags[index];
+    if (flag === '--json') {
+      continue;
+    }
+    const match = /^--(clear-)?(frontend|management)(-page)?$/.exec(flag);
+    if (action !== 'set' || !match || (match[1] && match[3]) ||
+      Object.prototype.hasOwnProperty.call(values, match[2])) {
+      throwUsage(t('app_entry.usage'));
+    }
+    const kind = match[1] ? 'clear' : (match[3] ? 'page' : 'url');
+    const value = kind === 'clear' ? null : flags[++index];
+    if (kind !== 'clear' && (!value || value.startsWith('--'))) {
+      throwUsage(t('app_entry.usage'));
+    }
+    values[match[2]] = { kind, value };
+  }
+  if (action === 'set' && !Object.keys(values).length) {
+    throwUsage(t('app_entry.usage'));
+  }
+  return { action, appType, values };
+}
+
+/** Read the revision used for a conditional partial write. */
+async function readEntries(client, appType) {
+  const result = unwrapYidaResponse(await client.get(`/${appType}/query/app/getAccessEntries.json`));
+  if (!result || typeof result.revision !== 'string' || !result.revision ||
+      !result.accessEntries || typeof result.accessEntries !== 'object' || Array.isArray(result.accessEntries)) {
+    throw new Error(t('app_entry.invalid_response'));
+  }
+  return result;
+}
+
+/** Persist only supplied entries and verify them through a separate read. */
+async function run(args = []) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(t('app_entry.usage'));
+    return;
+  }
+  const { action, appType, values } = parseArgs(args);
+  const authRef = createAuthRef();
+  const client = createYidaClient({ authRef });
+  const patch = {};
+  for (const [key, spec] of Object.entries(values)) {
+    if (spec.kind === 'clear') {
+      patch[key] = null;
+    } else if (spec.kind === 'page') {
+      patch[key] = { url: await resolveEntryUrl(authRef, appType, key, spec.value) };
+    } else {
+      const url = normalizeUrl(spec.value, appType);
+      patch[key] = { url };
+    }
+  }
+  let result = await readEntries(client, appType);
+  if (action === 'set') {
+    unwrapYidaResponse(await client.postForm(`/${appType}/query/app/saveAccessEntries.json`, {
+      accessEntries: JSON.stringify(patch), revision: result.revision,
+    }));
+    result = await readEntries(client, appType);
+    for (const [key, entry] of Object.entries(patch)) {
+      if ((result.accessEntries[key]?.url || '') !== (entry?.url || '')) {
+        throw new Error(t('app_entry.readback_failed'));
+      }
+    }
+  }
+  const urls = {};
+  for (const key of ['frontend', 'management']) {
+    if (result.accessEntries[key]?.url) {
+      urls[key] = normalizeUrl(result.accessEntries[key].url, appType);
+    }
+  }
+  console.log(JSON.stringify({ appType, ...result, urls }, null, 2));
+  return result;
+}
+
+module.exports = { run, parseArgs, normalizeUrl, resolveEntryUrl };

package/lib/app/app-list.js

@@ -84,6 +84,7 @@ function formatApp(app, baseUrl) {
     appName: (app.appName && app.appName.zh_CN) || '',
     appType: app.appType || '',
     systemLink: app.systemLink || '',
+    ...(app.accessEntries ? { accessEntries: app.accessEntries } : {}),
     ...buildApplicationEntryUrls({ appType: app.appType, systemLink: app.systemLink, baseUrl }),
   };
 }

package/lib/app/application-style.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CliError } = require('../core/cli-error');
+const { t } = require('../core/i18n');
+const { DESIGN_SKILL_ROOT, loadThemeIndex } = require('../design-plan/themes');
+const START = '/* OPENYIDA APPLICATION STYLE RECIPES START';
+const END = '/* OPENYIDA APPLICATION STYLE RECIPES END */';
+const CREATIVE_TOKENS = [
+  '--pod-page-bg-color', '--pod-card-bg-color', '--color-text1-4',
+  '--form-element-medium-corner', '--form-element-medium-height',
+  '--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',
+];
+
+function validateCreativeDirection(direction, tokens) {
+  const missing = ['businessRationale', 'composition', 'typography', 'material', 'formLayout']
+    .filter(key => typeof direction?.[key] !== 'string' || !direction[key].trim());
+  missing.push(...CREATIVE_TOKENS.filter(key => typeof tokens?.[key] !== 'string' || !tokens[key].trim()));
+  if (missing.length) {
+    throw new CliError(t('design_document.invalid', 'creativeDirection', missing.join(', ')), {
+      code: 'APPLICATION_STYLE_CREATIVE_INCOMPLETE', details: { missing },
+    });
+  }
+}
+
+function applyApplicationStyle(css, metadata, tokens) {
+  const style = metadata.applicationStyle;
+  if (style && (style.recipe !== 'application-style-v1' || !['template', 'creative'].includes(style.mode))) {
+    throw new CliError(t('design_document.invalid', 'applicationStyle', 'APPLICATION_STYLE_INVALID'), { code: 'APPLICATION_STYLE_INVALID' });
+  }
+  if (style?.mode === 'creative') {validateCreativeDirection(metadata.creativeDirection, tokens);}
+  const first = css.indexOf(START);
+  const last = css.indexOf(END);
+  if (first >= 0 && last < first) {
+    throw new CliError(t('design_document.invalid', 'app_theme.css', 'APPLICATION_STYLE_CSS_INVALID'), { code: 'APPLICATION_STYLE_CSS_INVALID' });
+  }
+  const recipe = style
+    ? fs.readFileSync(path.join(DESIGN_SKILL_ROOT, 'references/theme/application-style-recipes.css'), 'utf8').trim()
+    : '';
+  // Only the managed recipe block is replaced. User-authored rules stay intact.
+  if (first >= 0) {return css.slice(0, first) + recipe + css.slice(last + END.length);}
+  return recipe ? `${css.trimEnd()}\n\n${recipe}\n` : css;
+}
+
+function exportApplicationStyle(id, outputDirectory) {
+  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]];
+  const outputs = assets.map(([name, relative]) => {
+    const source = path.resolve(DESIGN_SKILL_ROOT, relative);
+    const target = path.join(directory, name);
+    const root = path.resolve(DESIGN_SKILL_ROOT, 'templates/design-themes') + path.sep;
+    if (!source.startsWith(root) || fs.existsSync(target)) {
+      throw new CliError(t('design_document.invalid', target, 'APPLICATION_STYLE_OUTPUT_CONFLICT'), { code: 'APPLICATION_STYLE_OUTPUT_CONFLICT' });
+    }
+    return { source, target, content: fs.readFileSync(source, 'utf8') };
+  });
+  fs.mkdirSync(directory, { recursive: true });
+  for (const item of outputs) {fs.writeFileSync(item.target, item.content, { flag: 'wx' });}
+  return { success: true, mode: theme.mode, themeId: id, authoringRequired: true, outputs: outputs.map(item => item.target) };
+}
+
+module.exports = { applyApplicationStyle, validateCreativeDirection, CREATIVE_TOKENS, exportApplicationStyle };

package/lib/app/canvas-compile.js

@@ -976,7 +976,12 @@ function compileCanvasLocal(source, options = {}) {
   assertCanvasNavigationStructure(source, options);
   assertCanvasNavigationPaths(source, options);
   assertInlineCssStructure(source, options);
-  assertCanvasThemeStructure(source, options);
+  const warnings = [];
+  assertCanvasThemeStructure(source, { ...options, onThemeWarning(message, details) {
+    warnings.push({ ...details, message });
+    if (options.onThemeWarning) { options.onThemeWarning(message, details); }
+    else { require('../core/chalk').warn(message); }
+  } });
 
   const importedModules = extractImportedModules(source);
 
@@ -1036,6 +1041,7 @@ function compileCanvasLocal(source, options = {}) {
   return {
     runtimeCode,
     importedModules: JSON.stringify(importedModules),
+    warnings,
   };
 }
 

package/lib/app/canvas-theme-guard.js

@@ -2,8 +2,32 @@
 
 const Babel = require('@babel/standalone');
 const { CliError } = require('../core/cli-error');
+const { warn } = require('../core/chalk');
 const { t } = require('../core/i18n');
 
+// Whether provably fixed brand overrides should be downgraded from a hard
+// failure to a warning while preserving the source override.
+function isTruthy(value) {
+  return ['1', 'true', 'yes', 'on'].includes(String(value || '').trim().toLowerCase());
+}
+
+function allowFixedBrand(options = {}, env = process.env) {
+  return options.allowFixedBrand === true || isTruthy(env.OPENYIDA_CANVAS_ALLOW_FIXED_BRAND);
+}
+
+// Whether fixed brand overrides should hard-block publishing. Off by default so
+// the guard warns and retains fixed overrides. Teams
+// that want CI enforcement opt in via --strict-theme / OPENYIDA_CANVAS_STRICT_THEME.
+function strictFixedBrand(options = {}, env = process.env) {
+  return options.strictBrand === true || isTruthy(env.OPENYIDA_CANVAS_STRICT_THEME);
+}
+
+function emitThemeWarning(options, message, details) {
+  if (typeof options.onThemeWarning === 'function') { options.onThemeWarning(message, details); return; }
+  warn(message);
+}
+
+
 // Check the maintained theme contract without executing business code.
 // Dynamic component factories and runtime branches still need browser verification.
 function assertCanvasThemeStructure(source, options = {}) {
@@ -23,6 +47,10 @@ function assertCanvasThemeStructure(source, options = {}) {
   const traverse = Babel.packages.traverse.default || Babel.packages.traverse;
   assertBrandOverrides(ast, traverse, options);
   const functions = new Map();
+  const migrationSites = [];
+  const migrationEdges = [];
+  const migrationUses = options.requireThemeProvider
+    ? new Set(collectBrandOverrides(ast, traverse).map(item => item.usageStart)) : null;
   let program;
   let defaultExport;
   const fail = (kind, node) => {
@@ -64,6 +92,17 @@ function assertCanvasThemeStructure(source, options = {}) {
     return null;
   }
 
+  function insideProvider(p) {
+    let parent = p.isJSXOpeningElement() ? p.parentPath.parentPath : p.parentPath;
+    for (; parent && !parent.isFunction(); parent = parent.parentPath) {
+      if (parent.isJSXElement()) {
+        const component = resolveFunction(parent.get('openingElement.name'));
+        if (functions.get(component)?.name === 'CanvasThemeProvider') { return true; }
+      }
+    }
+    return false;
+  }
+
   traverse(ast, {
     CallExpression(p) {
       const owner = functions.get(p.getFunctionParent()?.node);
@@ -75,6 +114,9 @@ function assertCanvasThemeStructure(source, options = {}) {
       }
       if (!owner) { return; }
       if (target) { owner.calls.push(target); }
+      if (migrationUses && target) {
+        migrationEdges.push({ from: p.getFunctionParent().node, to: target, covered: insideProvider(p) });
+      }
       const callee = p.node.callee;
       if (callee.type === 'MemberExpression' && callee.object.name === 'React' && callee.property.name === 'createElement') {
         const component = resolveFunction(p.get('arguments.0'));
@@ -85,11 +127,19 @@ function assertCanvasThemeStructure(source, options = {}) {
       const owner = functions.get(p.getFunctionParent()?.node);
       const component = resolveFunction(p.get('name'));
       if (owner && component) { owner.renders.push(component); }
+      if (migrationUses) {
+        const from = p.getFunctionParent()?.node;
+        if (component && from) { migrationEdges.push({ from, to: component, covered: insideProvider(p) }); }
+        if (migrationUses.has(p.node.start)) { migrationSites.push({ owner: from, covered: insideProvider(p), node: p.node }); }
+      }
     },
   });
 
   const entry = resolveFunction(program.scope.getBinding('YidaComp')?.path) || resolveFunction(defaultExport);
-  if (!entry) { return; }
+  if (!entry) {
+    if (options.requireThemeProvider) { fail('provider_missing', defaultExport?.node); }
+    return;
+  }
 
   // Calling a hook before returning a Provider cannot read that Provider.
   const directSeen = new Set();
@@ -118,14 +168,36 @@ function assertCanvasThemeStructure(source, options = {}) {
   }
   visit(entry);
   const hasProvider = [...functions.values()].some(info => info.name === 'CanvasThemeProvider');
-  if (!providerMounted && (hasProvider || firstHook)) {
+  if (!providerMounted && (options.requireThemeProvider || hasProvider || firstHook)) {
     fail('provider_missing', firstHook || entry);
   }
+  if (migrationUses) {
+    // A sibling provider does not supply context to the migrated controls.
+    // Unknown/dynamic render paths are left for manual migration.
+    const checked = new Map();
+    const checkScope = (node, covered) => {
+      const states = checked.get(node) || new Set();
+      if (states.has(covered)) { return; }
+      states.add(covered); checked.set(node, states);
+      for (const site of migrationSites.filter(site => site.owner === node)) {
+        if (!covered && !site.covered) { fail('provider_missing', site.node); }
+      }
+      migrationEdges.filter(edge => edge.from === node).forEach(edge => checkScope(edge.to, covered || edge.covered));
+    };
+    checkScope(entry, false);
+    for (const site of migrationSites) {
+      if (!checked.has(site.owner)) { fail('provider_missing', site.node); }
+    }
+  }
 }
 
-// Only reject provably fixed brand colors passed to antd's ConfigProvider.
-// Semantic colors, layout tokens and dynamic theme resolvers remain supported.
-function assertBrandOverrides(ast, traverse, options) {
+// Collect every provably fixed brand color passed to antd's ConfigProvider.
+// Semantic colors, layout tokens and dynamic theme resolvers are ignored.
+// Each entry keeps the offending property's char offsets so the theme codemod
+// can surgically remove it while the guard reuses the same detection to fail.
+function collectBrandOverrides(ast, traverse) {
+  const violations = [];
+  let usageStart;
   const resolve = (p, seen = new Set()) => {
     if (!p?.node || seen.has(p.node)) { return null; }
     seen.add(p.node);
@@ -147,10 +219,12 @@ function assertBrandOverrides(ast, traverse, options) {
     const color = val.isStringLiteral() ? val.node.value : val.node.quasis[0].value.cooked;
     if (!color) { return; }
     const line = val.node.loc?.start.line || 1;
-    throw new CliError(t('publish.canvas_theme_fixed_brand', line), {
-      code: 'OPENYIDA_CANVAS_THEME_FIXED_BRAND',
-      details: { stage: 'canvas_compile', sourcePath: options.sourcePath || '', line, field, value: color,
-        sample: 'openyida sample openyida-page-template canvas-theme' },
+    // Remove the override at its ConfigProvider usage site, not the resolved literal.
+    const property = p?.parentPath?.isObjectProperty() ? p.parentPath.node : null;
+    violations.push({
+      field, color, line, usageStart,
+      start: property ? property.start : val.node.start,
+      end: property ? property.end : val.node.end,
     });
   };
   const tokens = p => properties(p).forEach(item => {
@@ -167,6 +241,7 @@ function assertBrandOverrides(ast, traverse, options) {
       if (!(imported.isImportSpecifier() && imported.node.imported.name === 'ConfigProvider')
         && !(imported.isImportNamespaceSpecifier() && name.node.property?.name === 'ConfigProvider')) { return; }
       const attribute = p.get('attributes').find(attr => attr.isJSXAttribute() && attr.node.name.name === 'theme');
+      usageStart = p.node.start;
       const theme = attribute?.get('value.expression');
       tokens(prop(theme, 'token'));
       const components = prop(theme, 'components');
@@ -179,6 +254,48 @@ function assertBrandOverrides(ast, traverse, options) {
       }
     },
   });
+  return violations;
+}
+
+// Fixed brand colors passed to antd's ConfigProvider are relaxed by default:
+// Warn and preserve the literal override; this does not install an app theme.
+// Strict mode blocks these overrides; allow-fixed-brand explicitly preserves them.
+function assertBrandOverrides(ast, traverse, options) {
+  const explicitlyAllowed = allowFixedBrand(options);
+  const strict = strictFixedBrand(options);
+  for (const { field, color, line } of collectBrandOverrides(ast, traverse)) {
+    const details = { code: 'OPENYIDA_CANVAS_THEME_FIXED_BRAND', sourcePath: options.sourcePath || '',
+      line, field, value: color, themeConsistency: 'fixed_override',
+      nextAction: { type: 'review_theme_override', sample: 'openyida sample openyida-page-template canvas-theme' } };
+    if (explicitlyAllowed) {
+      emitThemeWarning(options, t('publish.canvas_theme_fixed_brand_allowed', line, field), details);
+      continue;
+    }
+    if (!strict) {
+      emitThemeWarning(options, t('publish.canvas_theme_fixed_brand_relaxed', line, field), details);
+      continue;
+    }
+    throw new CliError(t('publish.canvas_theme_fixed_brand', line), {
+      code: 'OPENYIDA_CANVAS_THEME_FIXED_BRAND',
+      details: { stage: 'canvas_compile', sourcePath: options.sourcePath || '', line, field, value: color,
+        retryable: false, retrySafe: true, sideEffectState: 'none',
+        nextAction: { type: 'edit_source_then_recheck' },
+        sample: 'openyida sample openyida-page-template canvas-theme' },
+    });
+  }
+}
+
+// Parse a canvas source and return removable fixed-brand overrides (with char
+// offsets). Returns [] when the source has no theme markers or fails to parse,
+// mirroring the guard's own gate so the codemod never acts on unrelated code.
+function collectFixedBrandViolations(source) {
+  if (!/CanvasThemeProvider|useCanvasThemeContext|CanvasThemeContext|@canvas-theme-provider|antd/.test(source)) { return []; }
+  let ast;
+  try {
+    ast = Babel.packages.parser.parse(source, { sourceType: 'module', plugins: ['jsx', 'typescript'] });
+  } catch { return []; }
+  const traverse = Babel.packages.traverse.default || Babel.packages.traverse;
+  return collectBrandOverrides(ast, traverse);
 }
 
-module.exports = { assertCanvasThemeStructure };
+module.exports = { assertCanvasThemeStructure, collectFixedBrandViolations };