@synopackageland/cli 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.17.1 (unreleased)
+
+- Remove environment-specific release notes and source comments from distributed content, including generated DSM window scripts.
+- Prepare npm releases from a clean package directory without local archive references.
+- 清理發佈內容中的環境識別敘述；以乾淨套件目錄準備 npm 發佈。
+
+## 0.17.0 (2026-10-19)
+
+- Pin SDK/App 0.17.0 and templates 0.17.1, with UI 0.12.1 in Vue scaffolds; package the executor fixes for directory users and request batches.
+- Fetch SynoToken early in standalone and Portal windows so the first API request can start sooner.
+- Allow Portal without an executor from DSM 7.2-64570. Request DSM nginx reload through INFO during install, upgrade and uninstall; DSM 7.1 still needs an executor for registration.
+
+- Expose ctx.batch in generated SDK windows, sharing the existing request guards and token recovery. Keep single-call retries unchanged; never replay a batch after partial execution.
+
 ## 0.16.0 (2026-10-19)
 
 - Pin SDK/templates 0.16.0; generated Shared Folder flows use the shared SDK readback and settings components.

package/README.md

@@ -95,7 +95,7 @@ Add them with `init --with …` or later with `synopkgland add <capability…>`.
 | `login` | Sign users in with their DSM account, without the DSM desktop | Nobody; requires HTTPS for password sign-in |
 | `delegate` | Move files into a user's chosen folder while the user is offline | An administrator, once |
 | `root-ops` | Run fixed `root/*.sh` scripts for administrators | An administrator, once |
-| `portal` | Open the app from its own Application Portal alias, with a login page style (`login_style` changes the colour, wallpaper and title) | An administrator sets the alias; needs `root-ops` or `delegate` and DSM 7.1-42661+ (below 7.2-64570 the executor registers the entry) |
+| `portal` | Open the app from its own Application Portal alias, with a login page style (`login_style` changes the colour, wallpaper and title) | An administrator applies the alias; DSM 7.2-64570+ needs no executor (INFO asks DSM to reload nginx on uninstall). DSM 7.1-42661+ needs an executor to register the entry |
 
 Delegate is implemented; its default operation is `files.moveFromStaging`.
 Device lifecycle acceptance on real hardware is still pending for delegate and root operations.
@@ -311,3 +311,10 @@ Read `synopkgland skill show ctl` for the AI workflow, batch discovery approval,
 cache refresh, host removal/revocation and explicit `ctl.commands` authoring.
 API descriptions are private SPK files named `synopkgland-api.json`, served
 only by the authenticated fixed `synopkgland.describe` CGI operation.
+
+Generated SDK windows expose `ctx.batch([{method, params}, ...])` when the
+selected SDK supplies its batch factory. One to eight independent JSON reads
+share a request; results keep input order and retain per-method errors. A batch
+uses the same token recovery, request deadline and cancellation as `ctx.call`,
+and is never replayed automatically. Older SDKs and binary backends retain the
+single-call client. Rebuild the window with the current CLI/SDK to adopt it.

package/assets/init-compose.md

@@ -22,7 +22,7 @@ Application Portal. Headless Apps omit compose.web and have no launcher.
 Compose ctl is unsupported.
 
 Use supported upstream config files, environment, argv or reverse proxy for
-login/settings. For integrated upstream Apps, select supported trusted-header authentication or disable upstream login behind the DSM admin gate; or use the existing SDK 0.16.0 token adapter: OpenList uses mode: token, access: dsm-admins and entry: admin-only. Its unmodified admin token CLI supplies a package-private 0600 credential; the gateway injects Authorization server-side after DSM admission, without delivering it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own credentials. Verify each App adapter and DSM admission separately.
+login/settings. For integrated upstream Apps, select supported trusted-header authentication or disable upstream login behind the DSM admin gate; or use the existing SDK 0.17.0 token adapter: OpenList uses mode: token, access: dsm-admins and entry: admin-only. Its unmodified admin token CLI supplies a package-private 0600 credential; the gateway injects Authorization server-side after DSM admission, without delivering it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own credentials. Verify each App adapter and DSM admission separately.
 Containers use the package account and a dedicated bridge; they do not inherit
 an interactive user's NAS ACL. Do not use root/chown during any App lifecycle
 phase. Preserve licenses and dependency/source provenance. Read the CLI skill

package/dist/add.js

@@ -8,7 +8,7 @@ import { initFromTemplate, nativeCapabilitySettings } from './init.js';
 import { templatesRoot } from './template-paths.js';
 import { borrowedFiles, borrowedTarget, capabilityOverlays } from './capability-overlays.js';
 import { API_PERMISSIONS_FILE } from './standalone/api-permissions.js';
-import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM } from './build-spk/dsm-version.js';
+import { DEFAULT_MIN_DSM, isDsmAtLeast, portalByExecutor, PORTAL_EXECUTOR_MIN_DSM } from './build-spk/dsm-version.js';
 import { loadStandaloneManifest } from './standalone/manifest.js';
 import { PORTAL_REQUIRES_EXECUTOR } from './portal/alias.js';
 function files(root, dir = root) {
@@ -66,13 +66,13 @@ function addPortal(root, result) {
     writeFileSync(manifestPath, setTopLevel(readFileSync(manifestPath, 'utf8'), { ...values, portal: {} }));
     return withNotes({ ...result, added: [...result.added, 'portal'] }, notes);
 }
-/** A portal needs the executor tier, already declared or added in the same call; nothing is written otherwise. */
+/** Before DSM 7.2 a portal needs an executor, already declared or added in the same call. */
 function refuseNoPrivilegePortal(root, rest) {
     const loaded = loadStandaloneManifest(root);
     if (!loaded.ok)
         throw new Error(loaded.errors.map(e => `[${e.code}] ${e.message}`).join('\n'));
     const { rootOps, delegate, webapi } = loaded.manifest.capabilities;
-    if (!rootOps && !delegate && !webapi && !rest.some(name => name === 'root-ops' || name === 'delegate')) {
+    if (portalByExecutor(loaded.manifest.os_min_ver) && !rootOps && !delegate && !webapi && !rest.some(name => name === 'root-ops' || name === 'delegate')) {
         throw new Error(`[STANDALONE_PORTAL_REQUIRES_EXECUTOR] ${PORTAL_REQUIRES_EXECUTOR}`);
     }
 }

package/dist/build-spk/uninstall-wizard.d.ts

@@ -7,7 +7,7 @@ export type UninstallWizardKind = "native" | "container";
 interface UninstallWizardOptions {
     /** The App runs the root executor (rootOps or delegate), which purges DSM's leftovers on uninstall. */
     executor?: boolean;
-    /** The App declares a Login Portal alias (web-config app-portal); only the executor tier can. */
+    /** The App declares a Login Portal alias (web-config app-portal); DSM reloads nginx through INFO. */
     portal?: boolean;
     /** Below DSM 7.2 the executor registered the App's Application Portal entry. */
     portalEntry?: boolean;

package/dist/build-spk/uninstall-wizard.js

@@ -26,7 +26,7 @@ function renderUninstallWizard(t, locale, packageName, kind, { executor = false,
                 ...(kind === "native" ? [{ desc: t("uninstall.retained.native", vars) }] : []),
                 ...(executor ? [{ desc: t("uninstall.executor", vars) }] : []),
                 { desc: t(executor ? "uninstall.appPrivilege.auto" : "uninstall.appPrivilege", vars) },
-                ...(executor && portal ? [{ desc: t("uninstall.portal.auto", vars) }] : []),
+                ...(portal ? [{ desc: t("uninstall.portal.auto", vars) }] : []),
                 ...(executor && portalEntry ? [
                     { desc: t("uninstall.portalEntry", vars) },
                     { desc: portalEntryCleanupCommands(packageName).map((line) => `<code>${html(line)}</code>`).join("<br>") },

package/dist/build-spk/wizard-messages.js

@@ -407,15 +407,15 @@ export const WIZARD_MESSAGES = {
         it: "La disinstallazione rimuove automaticamente le regole di {package} in Pannello di controllo > Privilegi applicazione, così una successiva installazione con lo stesso nome non le applica di nuovo. Solo se questa pulizia non riesce, come segnala la voce synopkgland-executor del registro di sistema, un amministratore deve rimuovere le regole da lì.",
     },
     "uninstall.portal.auto": {
-        en: "After DSM removes the Login Portal alias of {package}, uninstall reloads the web server automatically, so the alias stops at once. Only if this reload failed, as the system log entry synopkgland-executor reports, an administrator can save an application alias in Control Panel > Login Portal > Applications, which reloads the web server, or restart the NAS.",
-        "zh-TW": "DSM 移除 {package} 的登入入口別名後，解除安裝會自動重新載入網頁伺服器，讓該別名立即失效。只有在重新載入失敗時（系統日誌 synopkgland-executor 會記錄），管理員才需要在「控制台」>「登入入口」>「應用程式」儲存任一應用程式別名（會重新載入網頁伺服器），或重新啟動 NAS。",
-        "zh-CN": "DSM 删除 {package} 的登录门户别名后，卸载会自动重新加载网页服务器，使该别名立即失效。只有在重新加载失败时（系统日志 synopkgland-executor 会记录），管理员才需要在“控制面板”>“登录门户”>“应用程序”保存任一应用程序别名（会重新加载网页服务器），或重新启动 NAS。",
-        ja: "DSM が {package} のログイン ポータルのエイリアスを削除した後、アンインストール時に Web サーバーを自動的に再読み込みするため、エイリアスはすぐに無効になります。再読み込みに失敗した場合 (システム ログの synopkgland-executor に記録されます) のみ、管理者が [コントロール パネル] > [ログイン ポータル] > [アプリケーション] でいずれかのアプリケーションのエイリアスを保存する (Web サーバーが再読み込みされます) か、NAS を再起動してください。",
-        ko: "DSM이 {package}의 로그인 포털 별칭을 삭제한 후 제거 과정에서 웹 서버를 자동으로 다시 로드하므로 별칭이 즉시 중지됩니다. 다시 로드가 실패한 경우에만(시스템 로그 synopkgland-executor에 기록됨) 관리자가 제어판 > 로그인 포털 > 응용 프로그램에서 응용 프로그램 별칭을 저장하거나(웹 서버가 다시 로드됨) NAS를 다시 시작하십시오.",
-        de: "Nachdem DSM den Anmeldeportal-Alias von {package} entfernt hat, lädt die Deinstallation den Webserver automatisch neu, sodass der Alias sofort endet. Nur wenn dieses Neuladen fehlschlägt, was der Systemprotokolleintrag synopkgland-executor meldet, muss ein Administrator unter Systemsteuerung > Anmeldeportal > Anwendungen einen Anwendungsalias speichern, wodurch der Webserver neu geladen wird, oder das NAS neu starten.",
-        fr: "Après que DSM a supprimé l’alias du Portail de connexion de {package}, la désinstallation recharge automatiquement le serveur web, si bien que l’alias cesse immédiatement. Seulement si ce rechargement échoue, ce que signale l’entrée synopkgland-executor du journal système, un administrateur doit enregistrer un alias d’application dans Panneau de configuration > Portail de connexion > Applications, ce qui recharge le serveur web, ou redémarrer le NAS.",
-        es: "Después de que DSM elimine el alias del Portal de inicio de sesión de {package}, la desinstalación recarga automáticamente el servidor web, de modo que el alias deja de funcionar al instante. Solo si esta recarga falla, como indica la entrada synopkgland-executor del registro del sistema, un administrador debe guardar un alias de aplicación en Panel de control > Portal de inicio de sesión > Aplicaciones, lo que recarga el servidor web, o reiniciar el NAS.",
-        it: "Dopo che DSM ha rimosso l’alias del Portale di accesso di {package}, la disinstallazione ricarica automaticamente il server web, così l’alias smette subito di funzionare. Solo se questo ricaricamento non riesce, come segnala la voce synopkgland-executor del registro di sistema, un amministratore deve salvare un alias di applicazione in Pannello di controllo > Portale di accesso > Applicazioni, che ricarica il server web, oppure riavviare il NAS.",
+        en: "DSM removes the Login Portal alias of {package} and reloads the web server automatically. The reload can finish after uninstall. If the alias still opens a DSM page, an administrator can save an application alias in Control Panel > Login Portal > Applications to reload the web server.",
+        "zh-TW": "DSM 會移除 {package} 的登入入口別名並自動重新載入網頁伺服器；重新載入可能在解除安裝結束後才完成。如果別名仍開啟 DSM 頁面，管理員可在「控制台」>「登入入口」>「應用程式」儲存任一應用程式別名，以重新載入網頁伺服器。",
+        "zh-CN": "DSM 会删除 {package} 的登录门户别名并自动重新加载网页服务器；重新加载可能在卸载结束后才完成。如果别名仍打开 DSM 页面，管理员可在“控制面板”>“登录门户”>“应用程序”保存任一应用程序别名，以重新加载网页服务器。",
+        ja: "DSM は {package} のログイン ポータルのエイリアスを削除し、Web サーバーを自動的に再読み込みします。再読み込みはアンインストール完了後に終了する場合があります。エイリアスで DSM ページが開く場合、管理者は [コントロール パネル] > [ログイン ポータル] > [アプリケーション] でアプリケーションのエイリアスを保存して再読み込みできます。",
+        ko: "DSM은 {package}의 로그인 포털 별칭을 삭제하고 웹 서버를 자동으로 다시 로드합니다. 다시 로드는 제거 완료 후에 끝날 수 있습니다. 별칭이 여전히 DSM 페이지를 열면 관리자는 제어판 > 로그인 포털 > 응용 프로그램에서 응용 프로그램 별칭을 저장하여 웹 서버를 다시 로드할 수 있습니다.",
+        de: "DSM entfernt den Anmeldeportal-Alias von {package} und lädt den Webserver automatisch neu. Das Neuladen kann nach der Deinstallation enden. Öffnet der Alias weiterhin eine DSM-Seite, kann ein Administrator unter Systemsteuerung > Anmeldeportal > Anwendungen einen Anwendungsalias speichern, um den Webserver neu zu laden.",
+        fr: "DSM supprime l’alias du Portail de connexion de {package} et recharge automatiquement le serveur web. Le rechargement peut se terminer après la désinstallation. Si l’alias ouvre encore une page DSM, un administrateur peut enregistrer un alias d’application dans Panneau de configuration > Portail de connexion > Applications pour recharger le serveur web.",
+        es: "DSM elimina el alias del Portal de inicio de sesión de {package} y recarga automáticamente el servidor web. La recarga puede terminar después de la desinstalación. Si el alias aún abre una página DSM, un administrador puede guardar un alias de aplicación en Panel de control > Portal de inicio de sesión > Aplicaciones para recargar el servidor web.",
+        it: "DSM rimuove l’alias del Portale di accesso di {package} e ricarica automaticamente il server web. Il ricaricamento può terminare dopo la disinstallazione. Se l’alias apre ancora una pagina DSM, un amministratore può salvare un alias di applicazione in Pannello di controllo > Portale di accesso > Applicazioni per ricaricare il server web.",
     },
     "uninstall.portalEntry": {
         en: "Uninstall asks the root executor to remove the Application Portal entry of {package}. If the executor is not running or was never approved, uninstall does not remove the entry; an administrator then runs these commands as root:",

package/dist/contract/validate.js

@@ -131,9 +131,9 @@ function validateWebPortal(parsed, contractFile) {
         return [];
     }
     const pos = getValuePosition(doc, ["integration", "web", "portal"]) ?? { line: 1, column: 1 };
-    // A Compose App has no root executor, and only its purge can stop nginx serving the alias after uninstall.
+    // The legacy Compose contract does not generate Application Portal resources.
     return [
-        makeError("CONTRACT_PORTAL_REQUIRES_EXECUTOR", contractSpan(contractFile, pos.line, pos.column, "integration.web.portal"), "A Compose App has no executor and cannot declare an Application Portal: after uninstall DSM does not reload nginx, and only root can remove the alias.", "Remove integration.web.portal; for a sign-in alias, ask an administrator to configure a reverse proxy in DSM."),
+        makeError("CONTRACT_PORTAL_REQUIRES_EXECUTOR", contractSpan(contractFile, pos.line, pos.column, "integration.web.portal"), "The legacy Compose contract does not support integration.web.portal. Use a schema-2 App with a top-level portal declaration and DSM 7.2-64570 or later.", "Migrate to schema 2 and top-level portal, or remove integration.web.portal."),
     ];
 }
 function validateDeveloperString(value, contractFile, path, pos) {

package/dist/error-registry.js

@@ -75,8 +75,8 @@ export const ERROR_REGISTRY = {
         },
         CONTRACT_PORTAL_REQUIRES_EXECUTOR: {
             code: "CONTRACT_PORTAL_REQUIRES_EXECUTOR",
-            description: "The Compose App declares integration.web.portal, but a Compose App has no executor; removing the sign-in alias after uninstall needs root so nginx stops serving it.",
-            suggestion: "Remove integration.web.portal; for a sign-in alias, ask an administrator to configure a reverse proxy in DSM instead.",
+            description: "The legacy Compose contract declares unsupported integration.web.portal.",
+            suggestion: "Use schema 2 with a top-level portal declaration and DSM 7.2-64570+, or remove integration.web.portal.",
         },
         CONTRACT_ACCESS_INVALID: {
             code: "CONTRACT_ACCESS_INVALID",
@@ -530,8 +530,8 @@ export const ERROR_REGISTRY = {
         },
         STANDALONE_PORTAL_REQUIRES_EXECUTOR: {
             code: "STANDALONE_PORTAL_REQUIRES_EXECUTOR",
-            description: "An App without an executor (capabilities.rootOps or delegate) declares portal.",
-            suggestion: "Removing the sign-in alias after uninstall needs root so nginx stops serving it, but an App without escalation uses no root at any stage. Add capabilities.rootOps or delegate (executor level), or remove portal and let an administrator configure a reverse proxy in DSM.",
+            description: "An App targeting DSM below 7.2-64570 declares portal without an executor.",
+            suggestion: "Raise os_min_ver to 7.2-64570 or later to use DSM web-config and INFO nginx reload without root. On DSM 7.1, add an executor capability to register the entry, or remove portal.",
         },
         STANDALONE_LOGIN_STYLE_INVALID: {
             code: "STANDALONE_LOGIN_STYLE_INVALID",

package/dist/host/share-permission.d.ts

@@ -10,10 +10,10 @@
  * extra_values directly, and share permission can change after install.
  *
  * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
- * before changing the predicate: on the test NAS, `fixtureadmin` has is_writable=false on
- * its own row for `pkgland-p0b` and still writes there, because the
+ * before changing the predicate: an administrator can have is_writable=false on
+ * its own row for a share and still have write access, because the
  * `administrators` group row carries the grant. A user-row-only check rejects
- * the only configuration with live proof behind it.
+ * valid group-based access.
  */
 export interface SharePermissionRow {
     name: string;

package/dist/host/share-permission.js

@@ -10,10 +10,10 @@
  * extra_values directly, and share permission can change after install.
  *
  * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
- * before changing the predicate: on the test NAS, `fixtureadmin` has is_writable=false on
- * its own row for `pkgland-p0b` and still writes there, because the
+ * before changing the predicate: an administrator can have is_writable=false on
+ * its own row for a share and still have write access, because the
  * `administrators` group row carries the grant. A user-row-only check rejects
- * the only configuration with live proof behind it.
+ * valid group-based access.
  */
 function relevantRows(input) {
     const groups = new Set(input.userGroups);

package/dist/init-upstream.js

@@ -58,7 +58,7 @@ Commit the scaffold, then run bash synology/upgrade.sh <upstream-tag> <build-num
 
 ${official ? 'Default: use the upstream official image. upgrade.sh updates its release tag and resolves an OCI index/manifest digest through synopkgland images pin, writing only synology/compose.image.yaml. Container Manager downloads that pinned official image at install. Configure upstream-recipe.json repository/service and imageTag: tag (exact upstream tag) or version (strip v only when upstream image naming requires it). Review multi-architecture support and upstream source/license correspondence. The SELECT_UPSTREAM_TAG placeholder must be replaced by a successful upgrade before check/build.' : 'Native App: implement build-source.sh as the native payload hook; it deliberately fails until implemented. Stage official release binaries pinned by SHA-256 (the OpenList route), or compile the merged source with a source build hook. Verify the release digest before staging architecture-specific daemon.targets; keep the SDK management shell separate.'}
 
-Use DSM administrator identity without an additional App password, an OIDC/SSO server or upstream source changes. Prefer supported trusted-header/proxy auth (FreshRSS), otherwise disable upstream login/enable guest behind the administrator-only gateway after a bounded first bootstrap (Uptime Kuma disableAuth). The third shipped pattern is the existing SDK 0.16.0 token adapter: mode: token, access: dsm-admins, entry: admin-only. OpenList obtains its native API token with the unmodified admin token CLI while stopped, stores it package-private 0600 under a 0700 directory, and the gateway injects Authorization server-side after DSM admission; packaging never delivers it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own native credentials. The upstream admin token/settings APIs remain unchanged. Verify actual DSM admission/revocation separately. Use supported config, environment, argv or proxy adapters. Every App lifecycle phase runs as the package UID. For upstream fixed-UID data directories, currently provide a synology/ startup adapter or writable path without root/chown; replace it with the framework ownership mechanism when available. Preserve licenses and the full source/component inventory.
+Use DSM administrator identity without an additional App password, an OIDC/SSO server or upstream source changes. Prefer supported trusted-header/proxy auth (FreshRSS), otherwise disable upstream login/enable guest behind the administrator-only gateway after a bounded first bootstrap (Uptime Kuma disableAuth). The third shipped pattern is the existing SDK 0.17.0 token adapter: mode: token, access: dsm-admins, entry: admin-only. OpenList obtains its native API token with the unmodified admin token CLI while stopped, stores it package-private 0600 under a 0700 directory, and the gateway injects Authorization server-side after DSM admission; packaging never delivers it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own native credentials. The upstream admin token/settings APIs remain unchanged. Verify actual DSM admission/revocation separately. Use supported config, environment, argv or proxy adapters. Every App lifecycle phase runs as the package UID. For upstream fixed-UID data directories, currently provide a synology/ startup adapter or writable path without root/chown; replace it with the framework ownership mechanism when available. Preserve licenses and the full source/component inventory.
 `;
     writeFileSync(join(packaging, 'AGENTS.md'), readFileSync(join(packaging, 'AGENTS.md'), 'utf8') + guidance);
 }

package/dist/portal/alias.d.ts

@@ -11,12 +11,8 @@ export declare const PORTAL_ALIAS_MAX = 64;
  * of Synology Apps, as observed on DSM 7.4-90069. DSM stays the authority.
  */
 export declare const RESERVED_PORTAL_ALIASES: readonly string[];
-/**
- * A portal needs the executor tier: DSM removes the alias files on uninstall
- * but leaves nginx serving the alias, and only the root executor purge can
- * reload it. A no-privilege App never runs anything as root.
- */
-export declare const PORTAL_REQUIRES_EXECUTOR = "portal needs the executor level (capabilities.rootOps or delegate): after uninstall DSM does not reload nginx, and a root executor must remove the sign-in alias. An App without an executor should remove portal and let an administrator configure a reverse proxy in DSM.";
+/** DSM below 7.2 refuses unsigned web-config; only an executor can register the entry there. */
+export declare const PORTAL_REQUIRES_EXECUTOR = "portal before DSM 7.2-64570 needs an executor (capabilities.rootOps, delegate or webapi) to register its entry: DSM 7.1 rejects the unsigned web-config worker. Raise os_min_ver to 7.2-64570 or later, add an executor capability, or remove portal. DSM reloads nginx through INFO; a no-privilege App never runs root code.";
 export interface PortalDeclaration {
     alias: string;
 }

package/dist/portal/alias.js

@@ -15,12 +15,8 @@ export const RESERVED_PORTAL_ALIASES = [
     "dsfile", "indexdb", "mobile", "oauth", "scripts", "sharing", "ssdp", "synosdsjslib", "synohdpack", "webapi", "webman",
     "calendar", "chatplus", "contacts", "drive", "file", "photo", "sso", "synologymeet",
 ];
-/**
- * A portal needs the executor tier: DSM removes the alias files on uninstall
- * but leaves nginx serving the alias, and only the root executor purge can
- * reload it. A no-privilege App never runs anything as root.
- */
-export const PORTAL_REQUIRES_EXECUTOR = "portal needs the executor level (capabilities.rootOps or delegate): after uninstall DSM does not reload nginx, and a root executor must remove the sign-in alias. An App without an executor should remove portal and let an administrator configure a reverse proxy in DSM.";
+/** DSM below 7.2 refuses unsigned web-config; only an executor can register the entry there. */
+export const PORTAL_REQUIRES_EXECUTOR = "portal before DSM 7.2-64570 needs an executor (capabilities.rootOps, delegate or webapi) to register its entry: DSM 7.1 rejects the unsigned web-config worker. Raise os_min_ver to 7.2-64570 or later, add an executor capability, or remove portal. DSM reloads nginx through INFO; a no-privilege App never runs root code.";
 export function isPortalAlias(value) {
     return typeof value === "string" && PORTAL_ALIAS_PATTERN.test(value) && !RESERVED_PORTAL_ALIASES.includes(value);
 }

package/dist/portal/info.d.ts

@@ -0,0 +1,4 @@
+/** DSM reloads these services after install, upgrade and uninstall; hooks stay unprivileged. */
+export declare function portalInfoFields(fields: Array<[string, string]>, portal: boolean): Array<[string, string]>;
+/** Check a resource-worker Portal. The legacy app.d registration still needs an executor. */
+export declare function inspectPortalInfo(info: Record<string, string>, hasExecutor: boolean): string[];

package/dist/portal/info.js

@@ -0,0 +1,32 @@
+import { portalByExecutor } from "../build-spk/dsm-version.js";
+const RELOAD_SERVICES = "instuninst_restart_services";
+const NGINX = "nginx.service";
+/** DSM reloads these services after install, upgrade and uninstall; hooks stay unprivileged. */
+export function portalInfoFields(fields, portal) {
+    if (!portal)
+        return fields;
+    const services = [...new Set([...fields.filter(([key]) => key === RELOAD_SERVICES)
+                .flatMap(([, value]) => value.split(/\s+/).filter(Boolean)), NGINX])].join(" ");
+    const result = [];
+    let written = false;
+    for (const [key, value] of fields) {
+        if (key !== RELOAD_SERVICES)
+            result.push([key, value]);
+        else if (!written) {
+            result.push([key, services]);
+            written = true;
+        }
+    }
+    if (!written)
+        result.push([RELOAD_SERVICES, services]);
+    return result;
+}
+/** Check a resource-worker Portal. The legacy app.d registration still needs an executor. */
+export function inspectPortalInfo(info, hasExecutor) {
+    const findings = [];
+    if (!(info[RELOAD_SERVICES] ?? "").split(/\s+/).includes(NGINX))
+        findings.push(`PORTAL_RELOAD_MISSING INFO ${RELOAD_SERVICES} must include ${NGINX} so DSM reloads nginx after uninstall`);
+    if (info.os_min_ver && portalByExecutor(info.os_min_ver) && !hasExecutor)
+        findings.push("PORTAL_REQUIRES_EXECUTOR before DSM 7.2-64570 the portal entry must be registered by an executor; raise os_min_ver or declare an executor capability");
+    return findings;
+}

package/dist/runtime/executor-digests.json

@@ -1,8 +1,8 @@
 {
-    "0.16.0": {
-        "x86_64": "4f47fb43f6e60dbad064afb0bbec96dd009fa046670e2c4b590b128a855cb404",
-        "aarch64": "c903b09ad657a838f0c62b6688e65e9094572b22b969770fca92fcc3640a5364",
-        "armv7": "8178d90de7ea720530bb9496e50ed118086b0e57382d84675aadc68f482d219f",
+    "0.17.0": {
+        "x86_64": "68f372684997258adc61312f2c353e1a286a6b5aaa556f716b4e6ba6f33893d0",
+        "aarch64": "f6950301e201a4ebc14577a4554fa1b671f90d0f354d1e8809f4d1dafb57c723",
+        "armv7": "e77c9b6ae22ecfa85d9834af3350192e445987265a7ca6c02ca9b01d88a1b4f7",
         "lifecycle": {
             "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
             "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",

package/dist/runtime/sdk-batch.d.ts

@@ -0,0 +1,2 @@
+/** The SDK's plain browser factory, embedded without imposing a TS build on Go Apps. */
+export declare function appSdkBatchRuntime(backend: object, env?: NodeJS.ProcessEnv): string;

package/dist/runtime/sdk-batch.js

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { appSdkVersion, sdkBelowFloor, sdkSource } from './sdk-source.js';
+/** The SDK's plain browser factory, embedded without imposing a TS build on Go Apps. */
+export function appSdkBatchRuntime(backend, env = process.env) {
+    if (backend.kind === 'binary')
+        return '';
+    const version = appSdkVersion(backend);
+    if (!version || sdkBelowFloor(version))
+        return '';
+    const sdk = sdkSource(version, env);
+    let source;
+    try {
+        source = readFileSync(join(sdk.goDir, 'ts/src/batch.js'), 'utf8');
+    }
+    catch (error) {
+        // Older supported SDKs retain their desktop-only carrier behavior.
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+    return source.replace(/^export function createBatch\(/m, 'function createBatch(');
+}

package/dist/runtime/uninstall-cleanup.js

@@ -16,7 +16,7 @@ export function uninstallCleanup(pkg, { executor = false, portal = false, portal
         executor
             ? { target: `SYNO.SDS.${pkg}.Instance rules in Application Privileges`, condition: AUTOMATIC_FAILED, action: 'The root executor removes these rules automatically through the Application Privileges API on uninstall. Administrator: remove surviving rules in Control Panel > Application Privileges; DSM would apply them again to a later install under the same name.' }
             : { target: `SYNO.SDS.${pkg}.Instance rules in Application Privileges`, condition: 'After uninstall, if this package will not be reinstalled.', action: 'DSM keeps these rules in /etc/synoappprivilege.db and applies them again to a later install under the same name. Administrator: remove them in Control Panel > Application Privileges.' },
-        ...(executor && portal ? [{ target: `${pkg} Login Portal alias`, condition: AUTOMATIC_FAILED, action: 'DSM removes the alias configuration without reloading its web server; the root executor then reloads the web server automatically. Administrator: if the alias still opens a DSM page, save an application alias in Control Panel > Login Portal > Applications to reload it, or restart the NAS.' }] : []),
+        ...(portal ? [{ target: `${pkg} Login Portal alias`, condition: 'Only if automatic cleanup failed and the alias still opens a DSM page after the asynchronous reload.', action: 'DSM removes the alias configuration and reloads the web server automatically through INFO instuninst_restart_services. Administrator: if the alias still opens a DSM page, save an application alias in Control Panel > Login Portal > Applications to reload it, or restart the NAS.' }] : []),
         ...(executor && portalEntry ? [{ target: `${pkg} Application Portal entry`, condition: 'After uninstall, if the executor was not running or was never approved, so it could not remove the entry.', action: `Administrator, as root: ${portalEntryCleanupCommands(pkg).join('; ')}` }] : []),
         { target: `${pkg} package account/group`, condition: 'After uninstall, only if this package will not be reinstalled and the identity is unused.', action: 'Administrator: review DSM internal account/group and associated ACLs before cleanup. Package scripts do not delete system identities.' },
     ];

package/dist/standalone/build.js

@@ -1,3 +1,4 @@
+import { PORTAL_REQUIRES_EXECUTOR } from "../portal/alias.js";
 import { buildApiDescription } from "./api-description.js";
 import { goChildEnv } from "../runtime/go-env.js";
 import { spawn } from "node:child_process";
@@ -113,6 +114,10 @@ export async function buildStandalone(options) {
         !isDsmAtLeast(manifest.os_min_ver, PORTAL_EXECUTOR_MIN_DSM)) {
         throw new StandaloneBuildError("STANDALONE_PORTAL_MIN_DSM", `[STANDALONE_PORTAL_MIN_DSM] ${portalMinDsmMessage(manifest.os_min_ver, "portal")}`);
     }
+    if (manifest.portal && portalByExecutor(manifest.os_min_ver) &&
+        !manifest.capabilities.rootOps && !manifest.capabilities.delegate && !manifest.capabilities.webapi) {
+        throw new StandaloneBuildError("STANDALONE_PORTAL_REQUIRES_EXECUTOR", PORTAL_REQUIRES_EXECUTOR);
+    }
     if (manifest.compose && !isDsmAtLeast(manifest.os_min_ver, "7.2.1-69057"))
         throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_INVALID", "compose identity_gateway requires DSM >= 7.2.1.");
     const composeProblem = manifest.compose && dsmComposeProblem(manifest.compose);

package/dist/standalone/dsm-window.js

@@ -12,6 +12,7 @@ import { packageIcons, windowIconFile, windowIconTemplate, } from "../build-spk/
 import { DEFAULT_WINDOW, FULL_PAGE_MIN_WIDTH } from "./window-size.js";
 import { requestTimeoutSeconds } from "./request-timeout.js";
 import { appSdkTimeouts } from "../runtime/sdk-timeouts.js";
+import { appSdkBatchRuntime } from "../runtime/sdk-batch.js";
 import { appSdkSessionRuntime } from "../runtime/sdk-session.js";
 /** Same path the generated wrapper POSTs to, and the payload location of the CGI. */
 export const CGI_PAYLOAD_PATH = "ui/cgi/api.cgi";
@@ -171,6 +172,7 @@ export function renderWindowScript(manifest, assetVersion, icons = packageIcons(
     const requestTimeout = requestTimeoutSeconds(manifest.backend) * 1000;
     const clientMargin = appSdkTimeouts(manifest.backend).browserMarginMs;
     const sessionRuntime = appSdkSessionRuntime(manifest.backend);
+    const batchRuntime = appSdkBatchRuntime(manifest.backend);
     if (manifest.portal && !portalText)
         throw new Error("A portal App's window needs the SDK's portal panel text.");
     return `/* Generated by synopkgland build. Edit your UI in the project's ui folder. */
@@ -186,13 +188,17 @@ ${sessionRuntime}
     fetch: function (url, options) { return fetch(url, options); }
   });
 })();
+// DSM loads this script when the App launches. A page it gave no SynoToken
+// (Portal, standalone) asks for one now, while app.js downloads, so the
+// first call does not wait a round trip for it after the App mounts.
+if (${ns}.session && !${ns}.session.token()) ${ns}.session.ready();
 `
         : ""}
 
 // The SDK's clientTimeout: past the backend's request deadline
 // (ctx.requestTimeout, from backend.timeout_seconds), so its request_timeout
 // reply arrives first. options.signal aborts the fetch, for a page the user leaves.
-${ns}.callOnce = function (method, params, options, requestTimeout) {
+${ns}.callOnce = function (method, params, options, requestTimeout, envelope) {
   var signal = options && options.signal;
   var canceled = { code: "request_canceled", message: "The request was canceled" };
   if (signal && signal.aborted) {
@@ -224,7 +230,7 @@ ${ns}.callOnce = function (method, params, options, requestTimeout) {
     method: "POST",
     credentials: "same-origin",
     headers: headers,
-    body: JSON.stringify({ method: method, params: params || {} }),
+    body: JSON.stringify(envelope || { method: method, params: params || {} }),
     signal: controller.signal
   }).then(function (response) {
     return response.json().catch(function () {
@@ -254,9 +260,21 @@ ${ns}.callOnce = function (method, params, options, requestTimeout) {
   });
 };
 
+${batchRuntime ? `
+// A batch is one request and is never replayed after a partial result.
+${ns}.batch = (function () {
+${batchRuntime}
+  return function (calls, options, requestTimeout) {
+    return createBatch(function (envelope, callOptions) {
+      return ${ns}.callOnce(null, null, callOptions, requestTimeout, envelope);
+    })(calls, options);
+  };
+})();
+` : ""}
+
 // APP_STOPPED, APP_STARTING and EXECUTOR_STARTING mean the executor op was not
 // sent. A stopped package waits for the user to start it in Package Center, so
-// APP_STOPPED rejects at once. A start ends by itself: a call repeats
+// APP_STOPPED rejects immediately. Starting states retry with bounded backoff:
 // half a second, then doubling, for 4 s of waiting in all, so a short start
 // shows the page nothing and the SDK's starting copy follows a long one within
 // its own 4 s recheck; executor.control, which the window's approval starts the
@@ -402,6 +420,7 @@ Ext.define(${JSON.stringify(`${ns}.MainWindow`)}, {
     try { if (typeof _S === "function") lang = _S("lang"); } catch (error) {}
     var ctx = { requestTimeout: ${requestTimeout} };
     var call = function (method, params, options) { return ${ns}.call(method, params, options, ctx.requestTimeout); };
+    var batch = ${batchRuntime ? `function (calls, options) { return ${ns}.batch(calls, options, ctx.requestTimeout); }` : "undefined"};
 ${root ? root.mount : ""}    ${ns}.loadApp(function (app) {
       if (me.mountToken !== mountToken) return;
       me.mountPending = false;
@@ -415,6 +434,7 @@ ${root ? root.mount : ""}    ${ns}.loadApp(function (app) {
           me.mounted = app.mount(root, Ext.apply(ctx, {
           displayName: ${ns}.createI18n(lang, ${JSON.stringify(displayNameCatalogs(manifest))}).t("app_title"),
           call: call,
+          batch: batch,
           files: {endpoint: ${JSON.stringify(cgiUrl(pkg))}, token: function () { return SYNO.SDS.Session && SYNO.SDS.Session.SynoToken; }},
           reopen: me.reopenEvents.subscribe,
           launchParams: me.launchParams,
@@ -495,6 +515,7 @@ function renderPortalAccess(ns, manifest) {
             isAdmin: function () { return ${ns}.sessionUser().isAdmin; },
             send: ${ns}.webApi(me),
             call: call,
+            batch: batch,
             launch: function (app, params) { SYNO.SDS.AppLaunch(app, params); },
             location: window.location,
             locale: ${ns}.createI18n(lang, ${JSON.stringify(Object.fromEntries(Object.keys(DSM_LANGS).map((locale) => [locale, {}])))}).locale

package/dist/standalone/inspect-spk.js

@@ -1,3 +1,4 @@
+import { inspectPortalInfo } from "../portal/info.js";
 import { isDeepStrictEqual } from "node:util";
 import { inspectApiDescription } from "./api-description-inspect.js";
 import { dsmLauncherType } from "../contract/app-launch.js";
@@ -152,7 +153,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         const sharedFolder = standalone
             ? recoverSharedFolder(readOptional(join(dir, "scripts/postinst")))
             : undefined;
-        // A Compose App has no executor, so its SPK never carries a portal.
+        // Resource-worker portals use DSM-owned INFO reload, with no executor requirement.
         const portal = standalone
             ? await recoverPortal(dir, info, `SYNO.SDS.${info.package}.Instance`, paths, payload, findings)
             : undefined;
@@ -187,8 +188,8 @@ export async function inspectSpk(spkPath, expectedKind) {
             ? await checkBridgeApp(dir, metadata.backend, info, payload, findings)
             : undefined;
         const hasExecutor = (metadata.capabilities ?? []).some((name) => name === "rootOps" || name === "delegate" || name === "webapi") || paths.has("executor/executor");
-        if (standalone && portal && !hasExecutor)
-            findings.push("PORTAL_REQUIRES_EXECUTOR portal needs the executor level (rootOps or delegate): after uninstall only a root purge can stop nginx serving the alias");
+        if (standalone && portal)
+            findings.push(...inspectPortalInfo(info, hasExecutor));
         const daemon = standalone
             ? await checkDaemon(dir, info, paths, payload, findings, hasExecutor, background, combined)
             : undefined;
@@ -205,6 +206,8 @@ export async function inspectSpk(spkPath, expectedKind) {
             executor = inspected.executor;
             if (executor)
                 findings.push(...inspectExecutorAnchor(readFileSync(join(dir, "INFO"), "utf8"), executor.executorDigest));
+            if (executor?.policy.portal && !portal)
+                findings.push(...inspectPortalInfo(info, true));
             if (executor?.policy.portal &&
                 info.os_min_ver &&
                 OS_MIN_VER.test(info.os_min_ver) &&

package/dist/standalone/manifest.js

@@ -374,7 +374,7 @@ function readManifest(raw, c) {
         ? undefined
         : (readPortalDeclaration(raw.portal, packageId) ??
             c.fail("STANDALONE_PORTAL_INVALID", "portal must be {} or { alias: <1-64 lowercase alphanumerics or -, not a DSM reserved path> }."));
-    if (portal &&
+    if (portal && osMinVer && portalByExecutor(osMinVer) &&
         !capabilities.rootOps &&
         !capabilities.delegate &&
         !capabilities.webapi) {

package/dist/standalone/native-layout.js

@@ -1,3 +1,4 @@
+import { portalInfoFields } from "../portal/info.js";
 import { validateMetadata, metadataInfoFields } from "../package-metadata.js";
 /** Existing native products: the CLI owns archives/INFO, the project owns its layout. */
 import { createHash } from 'node:crypto';
@@ -329,7 +330,7 @@ export async function buildNativeLayout(options) {
             await createReproducibleTar(target, join(stage, 'package.tgz'), { gzip: true });
             rmSync(target, { recursive: true });
             const fields = { package: m.package, version, arch: layoutInfoArch(arch), os_min_ver: m.os_min_ver, displayname: m.displayname, description: m.description, maintainer: m.maintainer, dsmuidir: 'ui', dsmappname: `SYNO.SDS.${m.package}.Instance`, startable: 'yes', thirdparty: 'yes', checksum: createHash('md5').update(readFileSync(join(stage, 'package.tgz'))).digest('hex') };
-            const info = [...Object.entries(fields), ...metadataInfoFields(m.metadata), ...anchorFields(m.layout.anchors ?? {}, files), ...portalFields(m.portal)];
+            const info = portalInfoFields([...Object.entries(fields), ...metadataInfoFields(m.metadata), ...anchorFields(m.layout.anchors ?? {}, files), ...portalFields(m.portal)], Boolean(m.portal));
             if (new Set(info.map(([k]) => k)).size !== info.length)
                 fail('INFO anchor collides with an INFO field');
             writeFileSync(join(stage, 'INFO'), info.map(([k, v]) => `${k}="${v.replace(/([\\"$`])/g, '\\$1')}"\n`).join(''));
@@ -370,8 +371,11 @@ export function inspectNativeLayout(dir, payload, info) {
             fail('package checksum mismatch');
         checkInfoAnchors(readFileSync(join(dir, 'INFO'), 'utf8'), inv.anchors === undefined ? {} : anchors(inv.anchors), actual);
         const declared = inv.portal === undefined ? undefined : portal(inv.portal, info.package);
-        if (declared)
+        if (declared) {
             checkPortal(declared, info.package, info.displayname ?? '', info.os_min_ver);
+            if (!(info.instuninst_restart_services ?? '').split(/\s+/).includes('nginx.service'))
+                fail('Portal INFO instuninst_restart_services must include nginx.service');
+        }
         checkInfoPortal(readFileSync(join(dir, 'INFO'), 'utf8'), declared);
         return [];
     }

package/dist/standalone/spk.d.ts

@@ -34,3 +34,5 @@ export interface AssembleOptions {
  * authorization remains separate and requires explicit administrator approval.
  */
 export declare function assembleStandaloneSpk(options: AssembleOptions): Promise<void>;
+/** Manifest validation already refused quotes, backslashes and newlines. */
+export declare function renderInfo(manifest: StandaloneManifest, arch: NativeArchFamily, checksum: string, executorDigest?: string): string;

package/dist/standalone/spk.js

@@ -1,3 +1,4 @@
+import { portalInfoFields } from "../portal/info.js";
 import { sdkSource } from "../runtime/sdk-source.js";
 import { resolvedSdkLaunch } from "../contract/app-launch.js";
 import { metadataInfoFields } from "../package-metadata.js";
@@ -299,7 +300,7 @@ function quote(value) {
     return `"${value.replace(/([\\"$`])/g, "\\$1")}"`;
 }
 /** Manifest validation already refused quotes, backslashes and newlines. */
-function renderInfo(manifest, arch, checksum, executorDigest) {
+export function renderInfo(manifest, arch, checksum, executorDigest) {
     const fields = [
         ["package", manifest.package],
         ["version", manifest.spkVersion],
@@ -340,7 +341,7 @@ function renderInfo(manifest, arch, checksum, executorDigest) {
         if (text?.description)
             fields.push([`description_${DSM_LANGS[locale]}`, text.description]);
     }
-    return fields.map(([key, value]) => `${key}=${quote(value)}\n`).join("");
+    return portalInfoFields(fields, Boolean(manifest.portal)).map(([key, value]) => `${key}=${quote(value)}\n`).join("");
 }
 function copyUiTree(source, target) {
     for (const entry of ["app.js", "app.css"]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "0.16.0",
+    "@synopackageland/templates": "0.17.2",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -7,7 +7,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。
 
-For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.16.0 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
+For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.0 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
 Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. For wrapping upstream OSS with DSM accounts, read [reference/identity-gateway.md](reference/identity-gateway.md) first. For all Compose work, read [reference/compose.md](reference/compose.md): schema-2 upstream files, generated override, SDK planner, fixed package identity and current DSM blockers. Containers do not inherit a signed-in user's File Station ACL. Existing Shared Folder mounts are blocked until official protected ACL/project control is verified.
 
@@ -15,7 +15,7 @@ Never install, uninstall, publish or modify NAS data without task authorization.
 
 Native projects use schema 2 capabilities and `--with files,jobs,login,root-ops,delegate`; use `add` for existing projects. Prefer `check --json`, `build --json`, `inspect <spk> --json`, `deploy --dry-run --json`, and `status --host <profile> --json` for structured results. Read the conflict policy in reference/create.md before adding overlays.
 
-Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting, and only an App with rootOps or delegate may declare one. Read reference/files.md and reference/identity.md for capability boundaries. RootOps and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate native runtimes in @synopackageland/sdk/native; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
+Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting; DSM 7.2-64570+ supports schema-2 Portal without an executor, while DSM 7.1 requires executor registration. Read reference/files.md and reference/identity.md for capability boundaries. RootOps and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate native runtimes in @synopackageland/sdk/native; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
 
 Read [reference/lifecycle.md](reference/lifecycle.md) before editing `dsm-scripts/` (preinst, postinst, preupgrade, postupgrade, preuninst, postuninst, start-stop-status): the SDK runs them inside its generated scripts as the package account; never add root work or repeat SDK steps there.
 

package/skills/reference/compose.md

@@ -23,7 +23,7 @@ compose:
   network: {egress: isolated}
   # Private package binds are rejected by DSM build; keep compatible upstream named volumes.
 identity_gateway:
-  sdk: 0.16.0
+  sdk: 0.17.0
   mode: none
   access: dsm-users
   listen: {http: 28000}
@@ -151,7 +151,7 @@ declared availability readiness, LAN isolation/egress, protected grant lifecycle
 ACLs, two-user visibility and clean install/upgrade/reboot/stop/uninstall before
 calling the package supported on a NAS. No NAS is accessed by the build gate.
 
-The unified Compose contract uses SDK/templates 0.16.0 with CLI 0.16.0. Use the published, matching versions together; the legacy packaging route and bridge publish mode are removed.
+The unified Compose contract uses SDK 0.17.0 and templates 0.17.1 with CLI 0.17.0. Use the published, matching versions together; the legacy packaging route and bridge publish mode are removed.
 
 Primary override files, and each included override set, must share a directory. Cross-directory override bases are rejected before loader I/O. Included implicit .env files are confined, inventoried and preserved; symlinks are rejected.
 
@@ -213,7 +213,7 @@ resources and does not move or delete retained data.
 Bridge web ingress uses a dedicated `sdk_ingress` internal bridge. The web service
 receives a fixed IPv4 address, and the package-account gateway connects directly
 to its declared container port. Internal bridges were reachable by package-account
-hooks in feasibility probes on an SA3200D and another test NAS. No HAProxy helper, published
+hooks in feasibility probes on DSM. No HAProxy helper, published
 container port, Docker socket or host root is required. Explicit internet egress
 still adds the existing outbound bridge; other App services retain their internal networks.
 

package/skills/reference/create.md

@@ -40,8 +40,8 @@ rootOps 與 delegate 已共用管理員 PasswordConfirm 核准的 protected exec
 backend 寫 `runtime: python|node|rust`（`runtime: go` 等同 `kind: go`）。CGI 是 SDK 的 Go runtime（`bridge/cmd/runtime`），它驗證 DSM session、entry 與 `permissions.json` 後，以套件帳號（不是 root）每個請求啟動一次 App。App 放在 ui 以外的目錄，打包成 `target/app/`，build 寫入 `bridge.json`（spec/bridge/v1）並把它與 `permissions.json` 的 sha256 編進 runtime。
 
 ```yaml
-backend: {runtime: python, dir: app, entry: main.py, sdk: 0.16.0}
-backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.16.0, node: {package: Node.js_v20}}
+backend: {runtime: python, dir: app, entry: main.py, sdk: 0.17.0}
+backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.17.0, node: {package: Node.js_v20}}
 backend: {runtime: rust, dir: app, entry: hello, methods: [hello.greet]}
 ```
 
@@ -91,8 +91,8 @@ width、minWidth 是 320–3840，height、minHeight 是 240–2160，最小值
 
 ## 兩種層級
 
-- 無升權 App（沒有 rootOps、delegate；含所有 Compose App）：安裝、執行、解除安裝都只用套件帳號，任何階段都不用 root。不能宣告 portal（native `STANDALONE_PORTAL_REQUIRES_EXECUTOR`、Compose `CONTRACT_PORTAL_REQUIRES_EXECUTOR`）；需要登入入口別名時由管理員在 DSM 手動設定反向代理。解除安裝後 DSM 保留的「控制台」>「應用程式權限」規則由管理員手動移除，精靈與 cleanup 清單會說明。
-- executor App（rootOps 或 delegate）：解除安裝時 root purge 自動刪除 `SYNO.SDS.<package>.Instance` 的應用程式權限規則，宣告 portal 時在 DSM 移除別名後 reload nginx。精靈說明自動清除；cleanup 清單只在自動清除失敗時（系統日誌 `synopkgland-executor`）才需要管理員處理。
+- 無升權 App（沒有 rootOps、delegate；含所有 Compose App）：安裝、執行、解除安裝都只用套件帳號，任何階段都不用 root。schema-2 App 的 os_min_ver 為 7.2-64570+ 時可以宣告 portal（含 unified Compose），由管理員明確套用別名，App 不會自動啟用或開啟入口；DSM 透過 INFO `instuninst_restart_services="nginx.service"` 處理解除安裝後的 nginx reload。DSM 7.1 仍需 executor 註冊入口，無升權 App 應提高最低 DSM 或省略 portal。解除安裝後 DSM 保留的「控制台」>「應用程式權限」規則由管理員手動移除，精靈與 cleanup 清單會說明。
+- executor App（rootOps 或 delegate）：解除安裝時 root purge 自動刪除 `SYNO.SDS.<package>.Instance` 的應用程式權限規則，Portal 的 nginx reload 由 DSM 依 INFO 執行，與 executor 核准分開。精靈說明自動清除；cleanup 清單只在自動清除失敗時（系統日誌 `synopkgland-executor`）才需要管理員處理。
 
 ## root 程式
 

package/skills/reference/portal.md

@@ -1,10 +1,12 @@
 # DSM Application Portal
 
-Tier: only an App with the executor (`capabilities.rootOps` or `capabilities.delegate`) may declare a portal, because after uninstall only root can make nginx stop serving the alias. A no-privilege native App fails check/build with `STANDALONE_PORTAL_REQUIRES_EXECUTOR`, `add portal` refuses it unless the same call adds `root-ops` or `delegate`, and inspect flags such an SPK with `PORTAL_REQUIRES_EXECUTOR`. A Compose App has no executor: `integration.web.portal` always fails with `CONTRACT_PORTAL_REQUIRES_EXECUTOR`. Without the executor, an administrator can set up a reverse proxy in DSM instead.
+Tier: a schema-2 App targeting DSM 7.2-64570+ may declare a Portal without an executor, including a unified Compose App. The CLI adds `instuninst_restart_services="nginx.service"` to INFO (merging service names without duplicates), so DSM reloads nginx after install, upgrade and uninstall. App hooks still run as the package account; a no-privilege App never runs root code. Declaring a Portal does not activate an alias or automatically open it: an administrator must apply the alias through DSM.
 
-Declare: native-go/binary with rootOps or delegate, `portal: {}` or `portal: {alias: my-app}` in dsm-package.yaml (`synopkgland add root-ops portal`, or `add portal` once the executor is declared). The alias defaults to the package name in lowercase. Aliases are 1–64 lowercase letters, digits or `-`, not starting or ending with `-`, and not a DSM path or Synology App alias (`webman`, `file`, …). The native-layout `backend: {kind: native}` owns its conf/scripts and its own root helper: `portal: {}` or `{alias}` there needs os_min_ver 7.1-42661+ and writes only `synopkgland_portal_alias="<alias>"` into INFO, which Package Center writes as root, so the product's root helper can trust it; the helper registers the app.d entry (application = INFO displayname) and owns its uninstall cleanup and wizard. inspect checks that INFO line against `native-layout.json`.
+On DSM 7.1 the unsigned web-config worker is unavailable, so entry registration still requires an executor (`rootOps`, `delegate` or `webapi`). `check`/`build` and `add portal` refuse a no-executor App targeting below 7.2 with `STANDALONE_PORTAL_REQUIRES_EXECUTOR`; raise `os_min_ver` to 7.2-64570+, add an executor capability, or omit Portal. `add portal` preserves a supported DSM target; it does not silently upgrade a no-privilege App's target or add root capabilities. The legacy `integration.web.portal` contract is unsupported; use the schema-2 top-level `portal` declaration.
 
-Build (os_min_ver 7.2-64570+): the SPK carries `etc/portal.json` (every field DSM's app-portal worker needs) and `etc/portal.mustache`, `conf/resource` registers them, and the install wizard adds a prefilled alias step. preinst validates the answer; postinst stores it as the package's own draft and default alias. Nothing is active until an administrator applies it. `inspect <spk> --json` reports `portal: {appId, alias}` and refuses any other portal content.
+Declare: `portal: {}` or `portal: {alias: my-app}` in dsm-package.yaml (`synopkgland add portal` with os_min_ver 7.2-64570+, or `synopkgland add root-ops portal` for the DSM 7.1 executor route). The alias defaults to the package name in lowercase. Aliases are 1–64 lowercase letters, digits or `-`, not starting or ending with `-`, and not a DSM path or Synology App alias (`webman`, `file`, …). The native-layout `backend: {kind: native}` owns its conf/scripts and its own root helper: `portal: {}` or `{alias}` there needs os_min_ver 7.1-42661+ and writes `synopkgland_portal_alias="<alias>"` and the nginx reload declaration into INFO, which Package Center writes as root, so the product's root helper can trust it; the helper registers the app.d entry (application = INFO displayname) and owns its uninstall cleanup and wizard. inspect checks that INFO line against `native-layout.json`.
+
+Build (os_min_ver 7.2-64570+): the SPK carries `etc/portal.json` (every field DSM's app-portal worker needs) and `etc/portal.mustache`, `conf/resource` registers them, and the install wizard adds a prefilled alias step. preinst validates the answer; postinst stores it as the package's own draft and default alias. Nothing is active until an administrator applies it. `inspect <spk> --json` reports `portal: {appId, alias}` and refuses any other portal content or a missing nginx reload declaration (`PORTAL_RELOAD_MISSING`).
 
 Login style: every portal build gives the launcher in `ui/config` a DSM `loginStyle`, which Control Panel > Login Portal > Applications draws as the entry's thumbnail and the alias login page uses for its wallpaper and button colour. Without it the thumbnail is blank. The CLI default is a neutral wallpaper, its thumbnail, a login-box mask and colour `#2F6BD8`; the launcher's `loginIcon` is the App icon, so the login page shows the icon beside the NAS name. Override any part in dsm-package.yaml:
 
@@ -24,15 +26,17 @@ Read: ordinary users call the Go backend's `portal.status` (`authenticated`), wh
 
 Executor mode (7.1-42661 ≤ os_min_ver < 7.2-64570): no web-config resource, no `etc/portal.*`, no alias wizard step or alias lifecycle. The executor policy carries `portal: {application: <displayname>, alias}` and the operations `portal.register` and `portal.unregister`; the executor writes `/usr/syno/etc/www/app.d/<package>.{json,mustache}`. The package name must match `^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$` (≤ 64) and displayname be 1–64 characters without control characters, or build fails with `STANDALONE_PORTAL_ENTRY_INVALID`. The native Go CGI is built with `-X main.portal=executor`; the Python/Node/Rust bridge CGI uses `-X main.portalMode=executor`: `portal.status` adds `entry` (`registered`, `unregistered`, `cleanup-required`; an unreadable executor is `unavailable`), and `portal.register` / `portal.unregister` take the administrator's DSM session and return the fresh status. `ctx.portal.register()` / `unregister()` call them; the plain panel shows text and "Enable entry" while unregistered, the alias form and "Remove entry" once registered, text and "Remove entry" when cleanup is required, and no entry buttons for non-administrators. Executor refusals keep their code (`PORTAL_FAILED`). Needs templates with the executor portal routes (after 0.9.4) and an SDK with the `portal` entry API (after 0.9.5).
 
-DSM floor: os_min_ver must be 7.1-42661 or later; below 7.2-64570 the executor registers the entry (above). DSM 7.1 marks the web-config worker Synology-only, so it refuses an unsigned SPK whose conf/resource carries web-config (Package Center error 320, "non-synology-signed package should not use internal worker"; seen on 7.1.1-42962). synopkg from DSM 7.2 on drops that mark, the only change to its worker table; the 7.2 floor comes from that source and is not yet verified on a 7.2 NAS. 7.3.2-86009 and 7.4 install it. Below 7.1 validate/build fail with `STANDALONE_PORTAL_MIN_DSM`, `--min-dsm` cannot go below 7.1, `add portal` raises a lower os_min_ver to 7.1-42661, and inspect flags an INFO os_min_ver below the floor of the SPK's mode. Fix: raise os_min_ver or remove the portal.
+DSM floor: os_min_ver must be 7.1-42661 or later; below 7.2-64570 the executor registers the entry (above). DSM 7.1 marks the web-config worker Synology-only, so it refuses an unsigned SPK whose conf/resource carries web-config (Package Center error 320, "non-synology-signed package should not use internal worker"; seen on 7.1.1-42962). synopkg from DSM 7.2 on drops that mark, the only change to its worker table; the 7.2 floor comes from that source and is not yet verified on a 7.2 NAS. 7.3.2-86009 and 7.4 install it. Below 7.1 validate/build fail with `STANDALONE_PORTAL_MIN_DSM`, `--min-dsm` cannot go below 7.1, with an executor, `add portal` raises a lower os_min_ver to 7.1-42661; a no-executor target below 7.2-64570 is refused, and inspect flags an INFO os_min_ver below the floor of the SPK's mode. Fix: raise os_min_ver or remove the portal.
 
 Capability: beyond that floor, no version gate. The panel needs SYNO.API.Info to list `SYNO.Core.AppPortal` (v2) and the app's registration to exist; otherwise administrators get only the Control Panel shortcut.
 
 UI: plain JS calls `ctx.portal && ctx.portal.mountPanel(element)` and disposes it on unmount; Vue renders `portal/PortalSettings.vue`. `ctx.portal.messages` carries the SDK text in all nine languages.
 
-Never: write `AppPortal.json`, `@appconf/<package>` or `/usr/syno/etc/www/app.d` from the App (only the executor's approved `portal.*` operations write app.d); add a backend route that changes the alias; relay QuickConnect responses or build QuickConnect links; reboot or change other packages' portal entries while testing. DSM keeps the alias across upgrades and removes the entry on uninstall, but it does not reload nginx, and it keeps the App's Application Privileges rules.
+Never: write `AppPortal.json`, `@appconf/<package>` or `/usr/syno/etc/www/app.d` from the App (only the executor's approved `portal.*` operations write app.d); add a backend route that changes the alias; relay QuickConnect responses or build QuickConnect links; reboot or change other packages' portal entries while testing. DSM keeps the alias across upgrades and removes the entry on uninstall. The INFO declaration requests nginx reload; DSM keeps the App's Application Privileges rules unless an executor removes those separately.
+
+Uninstall: DSM removes the resource-worker Portal entry and reloads nginx through INFO. Reload is asynchronous and can finish after uninstall; the App needs no executor approval for this cleanup. If the alias still serves a DSM page after reload, an administrator can save an application alias in Control Panel > Login Portal > Applications to request another reload. Application Privileges are separate: an executor removes the App's rules when available; without one, an administrator removes retained rules there if the App will not be reinstalled. The wizard and `status`/`inspect` cleanup list describe these separately.
 
-Uninstall: the root executor's purge deletes the rules of `SYNO.SDS.<package>.Instance` through the Application Privileges API and, once DSM has removed the alias files, reloads nginx (`synosystemctl reload nginx`), so the alias stops at once. Failures are only logged to the system log entry `synopkgland-executor`; then an administrator saves an alias in Control Panel > Login Portal > Applications (which reloads nginx) or restarts the NAS, and removes the rules in Control Panel > Application Privileges. The uninstall wizard and the `status`/`inspect` cleanup list say this in that order: automatic first, manual only as the fallback.
+Version evidence: Synology's [DSM 7 WordPress example](https://help.synology.com/developer-guide/examples/compile_web_package.html) declares `os_min_ver="7.0-40337"` with this INFO key; the [web-config guide](https://help.synology.com/developer-guide/resource_acquisition/web_config.html) requires it because the worker does not reload nginx itself. The key therefore adds no DSM 7.0/7.1 version floor; the remaining 7.2 floor for no-executor Portal is the unsigned worker restriction, not INFO support. Documentation confidence: high. End-to-end uninstall was verified on DSM 7.3.2 in a minimal Portal fixture; the 7.1/7.4/7.4.1 hardware matrix remains deferred. DSM 7.0 Portal registration remains unsupported.
 
 Executor mode uninstall: the purge reads the retained policy and unregisters the entry. If the executor is not running or was never approved, uninstall does not remove the entry; the wizard and cleanup list say so and give the root commands (`rm -f /usr/syno/etc/www/app.d/<package>.json /usr/syno/etc/www/app.d/<package>.mustache /usr/syno/etc/packages/<package>/AppPortal.json`, `synow3tool --disable-nginx-confd/--unreg-nginx-confd` for `dsm www alias .alias`, `--disable-nginx-sites/--unreg-nginx-sites` for `server .server` on `<c>.syno-app-portal.<package>.conf`, then `nginx -t && synow3tool --nginx=reload`).
 

package/skills/reference/ui-vue.md

@@ -61,6 +61,18 @@ Reuse the embedded theme's typography, spacing and public controls. Preserve
 loading, empty, error, disabled and permission states. Backend policies and DSM
 checks decide authority; component visibility cannot grant access.
 
+## Start fast
+
+Every api.cgi call pays DSM's session check (about 60–240 ms on a NAS), so
+the first screen waits for the startup chain, not the bundle:
+
+- Run the entry gate first, then start the reads that do not depend on each
+  other together (`Promise.all`); do not chain them.
+- Render `AppShell` as soon as the gate passes, with `:loading` while those
+  reads run: the sidebar and title show and the page body says it is loading.
+- Start polling on its schedule; do not repeat at mount a read startup just
+  made. Delay background sampling that the first screen does not need.
+
 ## Verify the actual Vue app
 
 From `frontend`, run:

package/skills/reference/upstream-fork.md

@@ -104,7 +104,7 @@ upstream mechanisms in order:
    If manual App login is still necessary, label bootstrap incomplete. Verify
    subsequent DSM entry, restart and upgrade all retain password-free access,
    while anonymous/nonadmin requests and direct upstream ports remain blocked.
-3. **Existing SDK token adapter**: SDK **0.16.0** supports `mode: token`, with
+3. **Existing SDK token adapter**: SDK **0.17.0** supports `mode: token`, with
    `access: dsm-admins` and `entry: admin-only`. OpenList uses its unmodified
    upstream `admin token` CLI while the server is stopped to obtain the native
    administrator API token. The package stores it in a package-private **0600**
@@ -142,7 +142,7 @@ is undecided. Never copy credentials into generated projects.
 
 | Prototype | Reusable lesson and remaining boundary |
 | --- | --- |
-| OpenList | Official release binary pinned by SHA-256, `/ping` and SDK 0.16.0 server-side token adapter; shared upstream admin, restart after token reset, native WebDAV credentials. Share selection does not grant package ACL/register Local storage. |
+| OpenList | Official release binary pinned by SHA-256, `/ping` and SDK 0.17.0 server-side token adapter; shared upstream admin, restart after token reset, native WebDAV credentials. Share selection does not grant package ACL/register Local storage. |
 | FreshRSS | Official image, package-UID Apache/config adapter in `synology/`, explicit health; supported proxy authentication with fixed admin mapping and header clearing. |
 | Uptime Kuma | Official image, writable-path adapter, nonredirecting health and `disableAuth` after first bootstrap; WebSocket expiry/revocation need separate tests. |