@synopackageland/cli 0.15.3 → 0.16.0

package/dist/standalone/compose.d.ts

@@ -23,6 +23,12 @@ export interface ComposePlan {
     mounts_blocked: boolean;
     acceptance_blockers: string[];
     services: Array<{
+        storage_init?: {
+            directories: Array<{
+                base: string;
+                path: string;
+            }>;
+        };
         service: string;
         user: string;
         container_root: boolean;
@@ -96,6 +102,8 @@ export declare function writeComposePayload(c: ComposeApp, root: string, target:
 export declare function renderComposeInstall(pkg: string): string;
 /** The same SDK entry point supplies the package-account install materializer. */
 export declare function buildComposeControl(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: import("./build.js").CommandRunner): Promise<string | undefined>;
+/** The SPK supplies this read-only binary; upstream registry images stay unchanged. */
+export declare function buildComposeStorageInit(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: import("./build.js").CommandRunner): Promise<string | undefined>;
 /** Only the build resolves registry metadata; check and inspect remain offline. */
 export declare function lockComposeImages(m: StandaloneManifest, arch: NativeArchFamily, resolveImages: boolean, imageProofs?: unknown): StandaloneManifest;
 export declare function composeInputs(root: string, file: string, envFile?: string): ComposePlan["inputs"];

package/dist/standalone/compose.js

@@ -5,7 +5,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { parse } from "yaml";
-import { CLI_VERSION } from "../cli-version.js";
+import { templateSdkVersion } from "../template-paths.js";
 import { goChildEnv } from "../runtime/go-env.js";
 import { sdkSource } from "../runtime/sdk-source.js";
 import { readDaemon } from "./daemon.js";
@@ -69,7 +69,7 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
     if (value.sdk !== undefined &&
         (typeof value.sdk !== "string" || !/^\d+\.\d+\.\d+$/.test(value.sdk)))
         return invalid("compose.sdk must name the matching SDK release.", "SDK_COMPOSE_UNSUPPORTED");
-    const sdk = typeof value.sdk === "string" ? value.sdk : (context.sdk ?? CLI_VERSION);
+    const sdk = typeof value.sdk === "string" ? value.sdk : (context.sdk ?? templateSdkVersion());
     let targets = {};
     if (value.helpers !== undefined) {
         const d = readDaemon({ exec: "_sso/gateway", targets: value.helpers }, root, arches, fail);
@@ -194,6 +194,7 @@ export function writeComposePayload(c, root, target, gateway) {
 export function renderComposeInstall(pkg) {
     return `#!/bin/sh
 set -eu
+"\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose/control" preflight || exit $?
 exec "\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose/control" prepare --project "\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose" --package '${pkg}'
 `;
 }
@@ -201,10 +202,19 @@ exec "\${SYNOPKG_PKGINST_TEMP_DIR:?}/compose/control" prepare --project "\${SYNO
 export async function buildComposeControl(m, arch, work, run) {
     if (!m.compose)
         return;
+    return buildComposeTool(m, arch, work, run, "plan");
+}
+/** The SPK supplies this read-only binary; upstream registry images stay unchanged. */
+export async function buildComposeStorageInit(m, arch, work, run) {
+    if (!m.compose?.plan.services.some((s) => s.storage_init))
+        return;
+    return buildComposeTool(m, arch, work, run, "storage-init");
+}
+async function buildComposeTool(m, arch, work, run, tool) {
     const { pinnedGoBuildEnv, pinnedGoProblem } = await import("../build-spk/go-toolchain.js");
     const { checkCgiBinary } = await import("./binary.js");
     const { StandaloneBuildError } = await import("./spk.js");
-    const out = join(work, `compose-control-${arch}`);
+    const out = join(work, `compose-${tool === "plan" ? "control" : tool}-${arch}`);
     const source = sdkSource(m.compose.sdk);
     const result = await run("go", [
         "build",
@@ -214,13 +224,13 @@ export async function buildComposeControl(m, arch, work, run) {
         "-s -w -buildid=",
         "-o",
         out,
-        "./compose/cmd/plan",
+        `./compose/cmd/${tool}`,
     ], {
         cwd: source.goDir,
         env: goChildEnv({ ...process.env, ...pinnedGoBuildEnv(arch) }),
     });
     if (result.status !== 0 || result.missing)
-        throw new StandaloneBuildError("SDK_COMPOSE_BUILD_FAILED", `Cannot build the SDK Compose control: ${result.stderr}`);
+        throw new StandaloneBuildError("SDK_COMPOSE_BUILD_FAILED", `Cannot build the SDK Compose ${tool}: ${result.stderr}`);
     const error = checkCgiBinary(work, out, arch);
     if (error)
         throw new StandaloneBuildError(error.code, error.message);
@@ -250,7 +260,7 @@ export function lockComposeImages(m, arch, resolveImages, imageProofs) {
     return { ...m, compose };
 }
 export function composeInputs(root, file, envFile) {
-    const result = spawnSync(planner(CLI_VERSION), [
+    const result = spawnSync(planner(templateSdkVersion()), [
         "sources",
         "--root",
         root,

package/dist/standalone/daemon.js

@@ -3,7 +3,7 @@ import { chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSyn
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem, } from "../build-spk/go-toolchain.js";
 import { sdkSource, appSdkVersion } from "../runtime/sdk-source.js";
-import { CLI_VERSION } from "../cli-version.js";
+import { templateSdkVersion } from "../template-paths.js";
 import { checkCgiBinary } from "./binary.js";
 import { composeDaemon, composeNetwork } from "./compose.js";
 import { gatewayDaemon } from "./identity-gateway.js";
@@ -141,7 +141,7 @@ export async function buildDaemonControl(manifest, arch, work, run) {
             (manifest.backend.kind === "go"
                 ? appSdkVersion(manifest.backend)
                 : undefined) ??
-            CLI_VERSION).goDir,
+            templateSdkVersion()).goDir,
         env: goChildEnv({ ...process.env, ...pinnedGoBuildEnv(arch) }),
     });
     if (result.missing || result.status !== 0)

package/dist/standalone/dsm-window.js

@@ -256,7 +256,7 @@ ${ns}.callOnce = function (method, params, options, requestTimeout) {
 
 // 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 (t-0529). A start ends by itself: a call repeats
+// APP_STOPPED rejects at once. A start ends by itself: a call repeats
 // 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
@@ -264,7 +264,7 @@ ${ns}.callOnce = function (method, params, options, requestTimeout) {
 // deadline; past the wait it rejects with the last refusal, and leaving the
 // page during a wait rejects request_canceled at once. The SDK's status reads
 // are not repeated: its panels show the stopped or starting package and check
-// again on their own (t-0503 R1).
+// again on their own.
 ${ns}.retryCodes = ["APP_STARTING", "EXECUTOR_STARTING"];
 ${ns}.statusReads = ["delegate.status", "authorization.status", "executor.status"];
 ${ns}.call = function (method, params, options, requestTimeout) {

package/dist/standalone/identity-gateway.js

@@ -313,6 +313,7 @@ export function identityGatewayConfig(m) {
         access: g.access ?? "dsm-users",
         ...(g.groups ? { groups: g.groups } : {}),
         ...(m.entry ? { entry: m.entry } : {}),
+        ...(m.compose ? { container_app: true } : {}),
         ...(m.compose?.plan.mounts_blocked ? { compose_blocked: true } : {}),
         ...(g.max_upload_bytes ? { max_upload_bytes: g.max_upload_bytes } : {}),
         ...(g.response_header_timeout_seconds

package/dist/standalone/inspect-spk.js

@@ -668,6 +668,17 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             throw new Error(materializer.message);
         if (payload.find((p) => p.path === "compose/control")?.mode !== "0755")
             throw new Error("Compose materializer must be executable");
+        const initializer = join(root, "compose/storage-init");
+        if (c.plan.services.some((s) => s.storage_init)) {
+            const error = checkCgiBinary(root, initializer, arch);
+            if (error)
+                throw new Error(error.message);
+            if (payload.find((p) => p.path === "compose/storage-init")?.mode !== "0755")
+                throw new Error("Compose storage initializer must be executable");
+        }
+        else if (existsSync(initializer)) {
+            throw new Error("unexpected Compose storage initializer");
+        }
         const binaries = [
             "daemon/control",
             "daemon/payload/_sso/gateway",

package/dist/standalone/lifecycle.js

@@ -21,12 +21,15 @@ export function renderStandaloneScript(name, manifest) {
             : renderStandaloneScript(name, { ...native, appScripts: undefined });
         const control = `"/var/packages/${manifest.package}/target/daemon/control"`;
         const paths = `"\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}" "\${SYNOPKG_PKGVAR:-/var/packages/${manifest.package}/var}"`;
+        const preflight = name === "start-stop-status"
+            ? `case "$1" in prestart|start|restart)\n  "\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}/compose/control" preflight || exit $? ;;\nesac\n`
+            : "";
         const remember = name === "postinst" &&
             manifest.compose.plan.ingress &&
             !manifest.compose.plan.mounts_blocked
             ? `"/var/packages/${manifest.package}/target/compose/control" remember-ingress --project "/var/packages/${manifest.package}/target/compose" --package '${manifest.package}' || exit $?\n`
             : "";
-        const ledger = remember +
+        const ledger = preflight + remember +
             (manifest.identityGateway && !manifest.compose.plan.mounts_blocked
                 ? name === "start-stop-status"
                     ? `if [ "$1" = restart ]; then\n  "$0" stop || exit $?\n  exec "$0" start\nfi\nif [ "$1" = start ]; then\n  ${control} acquire ${paths} || exit $?\nelif [ "$1" = stop ]; then\n  ${control} release ${paths} || exit $?\nfi\n`

package/dist/standalone/manifest.js

@@ -234,6 +234,10 @@ function readManifest(raw, c) {
     const daemon = arches &&
         readDaemon(raw.daemon, c.root, arches, (e) => c.fail(e.code, e.message));
     const gatewayRaw = isRecord(raw.identity_gateway) ? raw.identity_gateway : {};
+    if (raw.compose !== undefined && isRecord(raw.ctl) && raw.ctl.enabled === true)
+        c.fail("CTL_UNSUPPORTED_BACKEND", "Compose does not support automatic ctl descriptions; disable ctl.");
+    if (isRecord(raw.compose) && isRecord(raw.compose.web) && !isRecord(raw.compose.web.health))
+        c.fail("COMPOSE_HEALTH_REQUIRED", "Select compose.web.health.path and expected 2xx status for the actual App. Readiness does not follow redirects; check is static and does not probe HTTP.");
     const compose = arches &&
         readComposeApp(raw.compose, c.root, arches, (e) => c.fail(e.code, e.message), {
             package: packageId,
@@ -260,7 +264,8 @@ function readManifest(raw, c) {
         : raw.identity_gateway;
     if (compose?.web && gatewayRaw.upstream !== undefined)
         c.fail("COMPOSE_WEB_INVALID", "Compose upstream is derived from the SDK Compose ingress endpoint; remove identity_gateway.upstream.");
-    const identityGateway = readIdentityGateway(gatewayValue, daemon || (compose ? { targets: compose.targets } : undefined), (e) => c.fail(e.code, e.message), false, Boolean(compose?.plan.ingress));
+    // A failed Compose plan already explains the invalid upstream declaration.
+    const identityGateway = raw.compose !== undefined && !compose ? undefined : readIdentityGateway(gatewayValue, daemon || (compose ? { targets: compose.targets } : undefined), (e) => c.fail(e.code, e.message), false, Boolean(compose?.plan.ingress));
     if (compose && identityGateway && compose.sdk !== identityGateway.sdk)
         c.fail("STANDALONE_IDENTITY_GATEWAY_INVALID", "compose and identity_gateway must use the same SDK release.");
     if (compose &&

package/dist/standalone/portal-window.js

@@ -204,7 +204,7 @@ export const portalRuntime = (catalogs) => `function createPortalAccess(options)
     };
   }
   // The window reads the status when it opens, so a settings page shows the
-  // portal section as it is (t-0520).
+  // portal section as it is.
   status();
   return access;
 }`;

package/dist/standalone/spk.d.ts

@@ -16,6 +16,7 @@ export interface AssembleOptions {
     executor?: ExecutorArtifact;
     daemonControl?: string;
     composeControl?: string;
+    composeStorageInit?: string;
     /** The SDK identity gateway, required exactly when the manifest declares identity_gateway. */
     identityGateway?: string;
     /** The compiled background worker, required exactly when capabilities.jobs is enabled. */

package/dist/standalone/spk.js

@@ -190,6 +190,12 @@ export async function assembleStandaloneSpk(options) {
                 throw new StandaloneBuildError("SDK_COMPOSE_BUILD_FAILED", "Compose runtime artifact required.");
             copyFileSync(options.composeControl, join(target, "control"));
             chmodSync(join(target, "control"), EXEC_MODE);
+            if (manifest.compose.plan.services.some((s) => s.storage_init)) {
+                if (!options.composeStorageInit)
+                    throw new StandaloneBuildError("SDK_COMPOSE_BUILD_FAILED", "Compose storage initializer required.");
+                copyFileSync(options.composeStorageInit, join(target, "storage-init"));
+                chmodSync(join(target, "storage-init"), EXEC_MODE);
+            }
         }
         const packageTgz = join(staging, "package.tgz");
         await createReproducibleTar(join(staging, "package"), packageTgz, {

package/dist/template-paths.d.ts

@@ -3,3 +3,7 @@
  * package; SYNOPKGLAND_TEMPLATES_DIR points at a templates checkout instead.
  */
 export declare function templatesRoot(env?: NodeJS.ProcessEnv, from?: string): string;
+/** The installed templates' SDK pin also supplies CLI-owned runtime defaults.
+ * CLI-only patch releases must never turn their own version into an SDK tag.
+ */
+export declare function templateSdkVersion(env?: NodeJS.ProcessEnv): string;

package/dist/template-paths.js

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
+import { sdkRequirement } from "./runtime/sdk-source.js";
 /**
  * The scaffold templates come from the exactly pinned @synopackageland/templates
  * package; SYNOPKGLAND_TEMPLATES_DIR points at a templates checkout instead.
@@ -14,3 +15,13 @@ export function templatesRoot(env = process.env, from = import.meta.url) {
         throw new Error("[TEMPLATES_MISSING] @synopackageland/templates is not installed; reinstall @synopackageland/cli, or set SYNOPKGLAND_TEMPLATES_DIR to a templates checkout.");
     }
 }
+/** The installed templates' SDK pin also supplies CLI-owned runtime defaults.
+ * CLI-only patch releases must never turn their own version into an SDK tag.
+ */
+export function templateSdkVersion(env = process.env) {
+    const version = sdkRequirement(join(templatesRoot(env), "native-go/backend"));
+    if (!version || !/^\d+\.\d+\.\d+$/.test(version)) {
+        throw new Error("[TEMPLATES_MISSING] The installed templates have no valid SDK pin; reinstall @synopackageland/templates.");
+    }
+    return version;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc",
-    "test": "npm run build && node --import tsx --test test/*.test.ts test/ctl/*.test.ts",
+    "test": "npm run build && node --import tsx --test --test-concurrency=${SYNOPKGLAND_GATE_JOBS:-3} test/*.test.ts test/ctl/*.test.ts",
     "test:glossary": "node --test scripts/test/glossary-drift.test.mjs",
     "test:scripts": "node --test scripts/test/gate.test.mjs scripts/test/release.test.mjs scripts/test/pack-docker.test.mjs scripts/test/npm-pack.test.mjs scripts/test/executor-bump.test.mjs scripts/test/smoke-exports.test.mjs scripts/test/executor-digests.test.mjs scripts/test/parallel.test.mjs scripts/test/scaffold-matrix.test.mjs scripts/test/frontend-deps.test.mjs scripts/test/docker-gate.test.mjs scripts/test/gate-plan.test.mjs scripts/test/gates.test.mjs",
     "gates": "bash scripts/ci/gates.sh",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "0.15.2",
+    "@synopackageland/templates": "0.16.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -7,6 +7,8 @@ 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.
+
 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.
 
 Never install, uninstall, publish or modify NAS data without task authorization. Prefer check, inspect and deploy --dry-run for reviewable artifacts.
@@ -149,18 +151,10 @@ Application Portal 是獨立 opt-in：不想要別名就省略 `portal`，不生
 `defaultAlias`、Portal 面板／capability 或 Web Station alias；沒有 Portal
 不是 inspect／info／doctor 問題。明確啟用 `portal` 時才將其 alias 作為 `defaultAlias`。
 
-Docker／web service App 設定 `integration.web.launch`，內建預設是 `new-page`；
-省略開啟方式時直接開新分頁，不宣告 Application Portal。SDK 原生 App
-省略時使用 `dsm-window`；非 UI SDK 原生 App 必須明確寫 `ui.launch: new-page`。
-Web service 主選單使用
-`type: "url"` 與明確的 `url` 指向既有 DSM gateway。明確 `access: public` 才保留 Web Station
-alias；這是服務入口，不是 SDK Application Portal。DSM 會將 standalone URL 改寫成 launchApp 頁面，
-需要 AppInstance／AppWindow JS class；schema 1 web service 沒有該 class，因此使用 url。需要 DSM 視窗時明寫 `dsm-window`。
-
-Schema 2 的 `dsm-package.yaml` + `identity_gateway` + `compose` 同樣視為
-web service：省略 `ui.launch` 時預設 `new-page`，使用 standalone launcher，
-不帶 Application Portal。兩條 Compose 路線共用 `contract/app-launch.ts`
-解析開啟方式與選擇 launcher 型別；明確的 `ui.launch` 可覆寫預設。
-只有沒有 web service 的 SDK 原生 App 省略時才預設 `dsm-window`。
+Schema 2 Compose 使用 `dsm-package.yaml` 的 `compose.files`、`compose.web` 與
+`identity_gateway`；不使用 file/targets/address_env 或手寫 upstream。
+省略 `ui.launch` 時預設 `new-page`，使用 SDK standalone launcher，不帶 Application Portal。
+Headless Compose 不產生 launcher。health 必須選實際 endpoint 與 2xx status；
+readiness 不跟隨 redirect，check 不會發 HTTP。Compose 不支援 ctl。
 
 For controlling installed Apps or designing task-level AI commands, read [reference/ctl.md](reference/ctl.md). Use ctl host list, register/renew explicitly, discover all commands, and always name the host when agents may operate multiple NAS machines.

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.15.2
+  sdk: 0.16.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.15.2 with CLI 0.15.3. Use the published, matching versions together; the legacy packaging route and bridge publish mode are removed.
+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.
 
 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.
 
@@ -187,13 +187,28 @@ bridge-unverified admission blocker is replaced by `COMPOSE_READINESS_INVALID`,
 
 Compose SPKs intentionally omit `install_dep_packages=ContainerManager`: DSM can
 report that dependency not ready even while its systemd unit and Docker daemon
-are active. The official `docker-project` worker checks actual availability;
-this does not authorize starting, modifying or repairing Container Manager.
-
-For disposable environments, optional `compose.resource_prefix: t-0661-` prefixes
+are active. The SDK's package-account preflight runs before install preparation
+and before project startup. It reads fixed Container Manager package/executable
+paths and the kernel's listening Unix-socket inventory; it never opens the Docker
+socket, needs root, starts services or repairs Container Manager. Missing software
+fails with `COMPOSE_CONTAINER_MANAGER_REQUIRED`; installed but unavailable or
+unverifiable Docker fails with `COMPOSE_CONTAINER_MANAGER_NOT_READY`. Stable
+message keys carry English defaults telling the user to install/start Container
+Manager from Package Center. The install hook writes the DSM temporary error log
+when provided; start returns the same error; first-open CGI displays an i18n-ready
+503 page even when the App gateway is stopped. This is availability evidence,
+not Docker/project identity or a successful container API call. DSM wizard display
+and permission behavior still need device acceptance.
+
+Exclude NAS platforms which cannot run Container Manager through the package's
+supported `arches`/INFO arch declarations. Do not advertise an unsupported
+architecture merely because the App image has it; review model compatibility
+within the declared family too.
+
+For disposable environments, optional `compose.resource_prefix: sandbox-` prefixes
 all generated project/network/volume names while retaining the package ID as the
 namespace suffix. Keep it stable across upgrades: changing it selects new
-resources and does not migrate or delete retained data.
+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
@@ -204,7 +219,7 @@ still adds the existing outbound bridge; other App services retain their interna
 
 The subnet is a deterministic /29 candidate derived from package ID and
 `compose.network.ingress_candidate` (integer 0-255, default 0). It comes from
-private 10.128.0.0/9; this pool is not globally reserved. Before acquisition, the
+the upper half of the RFC 1918 10/8 private address block; this pool is not globally reserved. Before acquisition, the
 package-account preparer reads kernel IPv4 routes and all interface prefixes, and rejects overlap with
 `COMPOSE_SUBNET_CONFLICT`. Choose another candidate and rebuild; no silent
 renumbering occurs on upgrade. Choose a different candidate for a clean
@@ -347,3 +362,5 @@ verified loopback address setting, cannot remap ports or enforce isolated
 egress, and is not a general replacement for Header/native-cookie bridge Apps.
 Do not silently switch networking, add Docker socket access, run an App hook as
 root or delete DSM configuration to claim compatibility.
+
+Compose web health is required before check/build; init has no guessed endpoint or status. Select both `--health-path` and `--health-status`, or edit `compose.web.health`. Readiness does not follow redirects. Static check is not an HTTP or arbitrary-UID/storage preflight. For official-image upstream packaging and DSM login, read [upstream-fork.md](upstream-fork.md).

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.15.2}
-backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.15.2, node: {package: Node.js_v20}}
+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: rust, dir: app, entry: hello, methods: [hello.greet]}
 ```
 

package/skills/reference/upstream-fork.md

@@ -0,0 +1,165 @@
+# Integrating an existing open-source App
+
+Preserve the upstream fork, full history and `upstream` remote. Keep **every**
+wrapper-owned manifest, adapter, script, notice and document in `synology/`.
+Never edit upstream README, Dockerfile, source, config, workflows or ignore files.
+Do not rewrite the App or treat it as an SDK component. Use `.git/info/exclude`
+for local output when needed.
+
+## Container: official image and a matching source tag
+
+Use the upstream **official image**, pinned as `repository:tag@sha256:digest`.
+For a multi-architecture image, pin its index digest so Container Manager can
+select the NAS architecture. Container Manager downloads the pinned image at
+install. Retain the upstream source fork to match releases and support required
+source/license delivery, including Corresponding Source where applicable. A
+matching source tag alone does not prove a complete license/source inventory.
+
+```sh
+git clone <your-fork-url> app
+cd app
+git remote add upstream <upstream-url>
+synopkgland init -t compose --upstream-fork --package MyApp \
+  --upstream-image owner/app --health-path /actual-readiness --health-status 200 .
+```
+
+Replace `owner/app` with the verified official repository. `init` does not guess
+its publisher or make network requests. Configure `synology/upstream-recipe.json`:
+`repository`, the actual Compose `service`, and `imageTag: tag` (exact upstream
+tag) or `version` (strip the leading `v` only if the official image uses that
+spelling). Adjust the App's port, storage and DSM login adapter before committing.
+The initial `SELECT_UPSTREAM_TAG` marker must be replaced by a successful upgrade.
+
+```sh
+bash synology/upgrade.sh v1.2.3 2
+```
+
+The script requires a clean tree, fetches the exact upstream tag into a private
+ref, verifies ancestry and untouched upstream files, then merges. It updates the
+official image tag and calls the existing `synopkgland images pin` registry
+resolver, recording `tag@digest` in `synology/compose.image.yaml`. That wrapper
+Compose override is listed after the base file; upstream files remain unchanged.
+The resolver requests OCI index/manifest-list media types. Verify the official
+image supports every declared architecture; a single-platform manifest does not
+become multi-architecture merely because it has a digest. A failed lookup leaves
+the previous override intact and stops the upgrade.
+
+Next, the script derives `version: 1.2.3` and explicit increasing packaging build
+`0002`, records source tag/commit/build in `upstream-source.json`, then runs
+`check --json` and `build --json`. It performs no image compilation or publication.
+Stable `[v]X.Y.Z` only. Build numbers increase globally (1–9999), even when upstream
+versions change. Review/inspect the SPK and commit `synology/` before another
+upgrade. Resolve or revert a failed merge explicitly; rehearse retained-data
+upgrades separately. No Git push, Release, NAS installation or deployment occurs.
+
+For fixed-UID image data directories, currently supply a startup adapter or an
+upstream-supported writable path under the control of `synology/`. Verify the
+package UID can create first-run config/cache/data and retain it across upgrades.
+Do not use root/chown lifecycle hooks or substitute a fixed UID. Replace this
+workaround with the framework ownership mechanism once available and verified.
+
+## Native: official release binaries or a source build hook
+
+```sh
+synopkgland init -t native-go --ui plain --upstream-fork --package MyApp .
+```
+
+Native Apps can stage official release binaries pinned by **SHA-256**, or compile
+the merged tree with a source build hook. OpenList uses the official release
+binary route: select the binary for the matching upstream tag and architecture,
+verify its pinned SHA-256 before staging it, and retain the source fork for
+version/source correspondence. Do not execute an unverified download.
+
+Implement `synology/build-source.sh` as the native payload hook; it deliberately
+fails until implemented. For official release binaries, use that hook to acquire,
+verify and stage the pinned release payload. For a source build, compile the
+merged source and its frontend with pinned toolchains/dependencies. The hook
+receives `SPL_UPSTREAM_SOURCE`, `SPL_UPSTREAM_TAG`, `SPL_UPSTREAM_COMMIT`; stage
+architecture-specific `daemon.targets` below `synology/` and keep the small SDK
+CGI as a separate management shell. The upgrade command fetches/merges the tag,
+derives the version, runs the selected native payload hook, checks and builds.
+
+## Use DSM login
+
+Every integrated App must admit **DSM administrators directly**, without a separate
+App password, an OIDC/SSO server, or upstream source changes. The scaffold declares
+`entry: admin-only`; Compose also declares gateway `access: dsm-admins`. This gates
+the entry but does not itself create an upstream session. Choose these supported
+upstream mechanisms in order:
+
+1. **Trusted header / reverse-proxy authentication**: configure gateway header
+   mode and the upstream's documented proxy-auth setting. FreshRSS supports this:
+   use its supported server-side `REMOTE_USER` configuration; the `synology/`
+   adapter may map admitted DSM administrators to a fixed shared upstream admin.
+   Clear incoming competing identity headers and admit upstream traffic only
+   through the gateway's dedicated bridge. Document shared data/audit identity.
+2. **Disable native login / allow guests**: configure the supported option and
+   let the DSM administrator gateway protect the sole reachable entry.
+   Uptime Kuma's `disableAuth` is the example. First bootstrap must complete native setup,
+   enable `disableAuth` via the upstream UI/API and read the state back before
+   declaring ready. An app-specific `synology/` adapter should generate any
+   required one-time setup secret, use it only for bootstrap and clear it; do not
+   ask users to remember/type an additional App password or edit the DB. The
+   existing prototype's setup rehearsal is not a generic shipped bootstrap SDK.
+   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
+   `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**
+   file under a 0700 directory. After DSM administrator admission, the gateway
+   runs the package's token adapter and injects `Authorization` server-side,
+   replacing client credentials. Packaging never delivers the token to the
+   browser, URL, localStorage or page script. No new SDK authentication API,
+   OIDC/SSO server, upstream source change or direct database edit is required.
+   All admitted DSM administrators share one upstream admin account; this does
+   not provide per-user isolation. After OpenList **Reset Token**, restart the
+   package to refresh the cached credential; failure refuses startup/requests
+   rather than falling back to anonymous access. WebDAV retains its own native
+   credentials: API-token injection does not make WebDAV password-free. The
+   upstream admin's own token/settings APIs remain unchanged, so an admitted
+   administrator may still inspect or rotate the native token through them.
+   Recheck `admin token`, API header and frontend `/api/me` behavior on upgrades;
+   verify actual DSM admission/revocation separately. The OpenList authentication
+   adapter is implemented and tested with the existing SDK; generic provisioning
+   automation and complete device acceptance are separate work.
+
+## Health, prerequisites and prototype boundaries
+
+Choose the actual unauthenticated health endpoint and its expected 2xx status
+with both init flags, or fill `compose.web.health` before check/build. No guessed
+`/` + 200. Readiness **does not follow redirects**: a 302 to a dashboard/login is
+unhealthy even if its destination is 200. A favicon/robots probe proves HTTP
+availability only; verify database setup and full readiness separately. `check`
+is static, not an HTTP or UID/storage probe. Compose ctl is rejected at check;
+dedicated origin `/` is supported, automatic subpath rewriting is not.
+
+Public npm availability does not grant anonymous Go SDK access. Obtain authorised
+source access or an exact matching module cache with original checksums, or use
+`SYNOPKGLAND_SDK_DIR` with an authorised matching checkout. Go source distribution
+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. |
+| 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. |
+
+Historical bounded Linux/prototype proofs are not DSM acceptance. Recheck the
+selected official image, arbitrary UID, persistent data, bootstrap and login
+boundaries; preserve complete third-party notices and source correspondence.
+
+## Container Manager prerequisite
+
+Container SPKs omit `install_dep_packages=ContainerManager` because DSM dependency
+status can report not-ready while Docker is active. SDK preflight checks fixed
+Container Manager files plus a listening Docker socket in the kernel inventory,
+as the package UID without socket/API access or root. It fails before install
+preparation/project startup with stable translated-message keys and an English
+instruction to install/start Container Manager from Package Center. DSM's supplied
+installer log, start failure and first-open CGI carry that diagnosis; the CGI
+returns 503 even when the gateway is down. Availability is not identity attestation.
+Declare only Container Manager-capable `arches`/INFO platforms; exclude unsupported
+NAS architectures and review models in each family. Actual missing-package wizard
+behavior and DSM's dependency not-ready behavior remain device acceptance items.

package/skills/reference/wrap.md

@@ -3,7 +3,7 @@
 只使用 schema-2 `dsm-package.yaml`。先讀 [compose.md](compose.md) 的宣告、支援表及 DSM 阻擋條件，再讀 [identity-gateway.md](identity-gateway.md) 決定 none／header／token／OIDC。不架 SSO Server，也不需要假 backend 或 wrapper container。
 
 ```sh
-synopkgland init -t compose --from ./compose.yaml my-app
+synopkgland init -t compose --from ./compose.yaml --health-path /actual-readiness --health-status 200 my-app
 synopkgland check --json
 synopkgland build --arch x86_64
 synopkgland inspect dist/MyApp-x86_64.spk --json
@@ -14,3 +14,5 @@ synopkgland inspect dist/MyApp-x86_64.spk --json
 容器使用固定套件身分，不繼承登入者 File Station ACL。Shared Folder 需 composeMounts 明確 opt-in，安裝後由 admin 確認；官方 protected ACL／project control 未驗證前只啟動 SDK 設定頁，不 acquire 上游，不用 host root 繞過。每使用者檔案權限需 session／Broker Adapter，本次不做。
 
 交付 inspect 的 upstream／effective hashes、image digests、run-as、mount、egress 與 acceptance blockers。Linux 通過不代表 DSM 已驗收。部署請讀 [deploy.md](deploy.md)，保留資料並由專用 thread 驗 final SPK digest。
+
+For an upstream fork, use [the upstream-fork recipe](upstream-fork.md) and `--upstream-fork` to keep all wrapper files in `synology/`. Container forks require `--upstream-image <official-repository>` and use official tag+digest images; native forks stage official release binaries pinned by SHA-256 or use a source build hook. Health flags require an actual App endpoint and expected 2xx response; readiness does not follow redirects.