@synopackageland/cli 0.15.4 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.16.0 (2026-10-19)
+
+- Pin SDK/templates 0.16.0; generated Shared Folder flows use the shared SDK readback and settings components.
+- Add the upstream-fork recipe/init/check workflow, Container Manager preflight and architecture-matched storage initializer packaging while preserving official images.
+- Remove internal deployment details from published content and scan actual npm tarballs before release.
+
 ## 0.15.4 (2026-10-18)
 
 - Fix Compose import and undeclared SDK defaults after CLI-only patch releases. Resolve the SDK from the exactly pinned templates' Go module instead of assuming the CLI and SDK share a patch version; daemon-control defaults use the same source.
@@ -174,8 +180,8 @@ only its protocol README's wording, and nothing in the CLI depends on it.
 
 - `ctx.call` rejects `APP_STOPPED` at once: a stopped package waits for the
   user to start it in Package Center, so the SDK's stopped copy shows within a
-  page's next read instead of 30 s later (Download Hub 29.3 s, t-0527; Reclaim
-  showed its old content or loading, t-0528). `APP_STARTING` and
+  page's next read instead of 30 s later (Download Hub 29.3 s; Reclaim
+  showed its old content or loading). `APP_STARTING` and
   `EXECUTOR_STARTING` repeat for 4 s of waiting (0.5, 1, 2, 0.5 s), so a short
   start still shows the page nothing and the SDK's starting copy follows a
   longer one within its own 4 s recheck. `executor.control`, which the window's
@@ -225,7 +231,7 @@ e2e 新增 `openUntilLoaded`（`signIn` 遇 `net::ERR_ABORTED` 最多重開約 3
   the newest one it read (`lastStatus()`); a `status()` asked for while a read
   runs shares it. The SDK's `PortalSettings` starts from it, so a settings
   page no longer moves when its placeholder rows become the real section
-  (Reclaim: 100 px, t-0520).
+  (Reclaim: 100 px).
 
 ## 0.10.6 (2026-10-15)
 
@@ -244,7 +250,7 @@ digest 與 0.10.5 相同；SDK 下限維持 0.10.5。e2e 新增 `openPath`、`ha
 
 - `signIn`, `openDesktop` and `openPortal` open their page once more when
   the first navigation fails with `net::ERR_ABORTED`, which about one run in
-  ten met as DSM's desktop navigated on its own (t-0499, t-0500); any other
+  ten met as DSM's desktop navigated on its own; any other
   failure, or a second abort, still fails. The helper is exported as
   `openPath(app, path)`.
 - The DSM window's `status()` answers a pinned executor that reports
@@ -330,7 +336,7 @@ digest 與 0.10.4 相同；新增 `@synopackageland/cli/e2e`。
   `authorization.status`, `executor.status`) while the package is stopped or
   starting: they reject with the code at once, and SDK 0.10.5's panels show the
   stopped or starting package and check again on their own. A page no longer
-  shows nothing for the first seconds after an upgrade (6.7 s in t-0503). Calls
+  shows nothing for the first seconds after an upgrade (6.7 s in the regression test). Calls
   that change something, approvals and controls among them, still repeat for up
   to 30 s. `ctx.executor.status()` for a user who is not an administrator says
   the package is stopped or starting instead of `admin_required`.
@@ -362,12 +368,12 @@ before its timeout.
 - The window approval of an upgrade (outdated tasks) makes 11 scheduler calls
   instead of 12: the outdated boot task is deleted by the approval's own first
   EventScheduler get, made moments before the password, instead of a second
-  get (2.9 s on the test NAS in t-0484). The control task is still read again by id
+  get (2.9 s on the test NAS in the regression test). The control task is still read again by id
   before its delete (spec/scheduler/v1). A fresh approval stays at 8.
   繁中：升級核准的排程呼叫由 12 降為 11（boot 任務不再於刪除前重讀）。
 - A scope approval reads the executor's selection back every second at most
   (it backed off to 2 s), so the window sees the landed scope within a second
-  of `scope.confirm` (the Dialog closed 4.8 s after it in t-0482). Removing
+  of `scope.confirm` (the Dialog closed 4.8 s after it in the regression test). Removing
   the temporary selection task still lists Task Scheduler first, as
   spec/scheduler/v1 requires of a delete.
   繁中：範圍核准讀回間隔上限 2 s → 1 s，confirmed 後 1 s 內看到結果。
@@ -376,7 +382,7 @@ before its timeout.
   before any request: the pinned, running executor reads `ready`; anything
   else stays `blocked` with `admin_required`. Task Scheduler is still read only
   for administrators. A user no longer sees an approved executor as waiting
-  for approval (t-0482 F7).
+  for approval.
   繁中：非管理員的 `ctx.executor.status()` 會向 App 的 `executor.status` 詢問，已核准且
   執行中即為 `ready`，不再一律回 `admin_required`。
 

package/assets/init-compose.md

@@ -0,0 +1,33 @@
+# Compose App development
+
+Run `synopkgland skill list`, then `synopkgland skill show orchestrator`,
+`synopkgland skill show compose` and `synopkgland skill show upstream-fork`.
+Prefer `check --json`, `build --json`, `inspect <spk> --json` for reviewable results.
+
+Never write `AppPortal.json` or `@appconf` directly, or relay QuickConnect.
+Compose has no native Application Portal alias; use its supported web entry.
+
+Use dsm-package.yaml schema 2. Keep upstream Compose bytes unchanged; declare DSM
+policy in compose.files and compose.web. Never use file/targets/address_env or
+identity_gateway.upstream: the SDK planner derives ingress.
+
+## Compose health and launch
+
+Select compose.web.health.path and its actual expected 2xx status before
+check/build. Redirects are not followed; a 302 to login is unhealthy. check is
+static, not an HTTP or arbitrary-UID/storage probe. Test the selected official image as
+the package UID, including writable volumes, first setup and upgrade.
+Omitted ui.launch means new-page via the SDK standalone launcher, without
+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.
+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
+reference/compose.md and reference/upstream-fork.md for the full recipe.
+
+Public npm access does not grant anonymous Go SDK access. Obtain authorised
+source/cache access or a matching SYNOPKGLAND_SDK_DIR checkout first. Never copy
+credentials into the App. Do not install, publish or modify NAS data without task authorization.

package/assets/init-upstream/build-source.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Native App payload hook. SPL_UPSTREAM_SOURCE is the merged fork root.
+# Stage official release binaries only after verifying pinned SHA-256 values
+# (the OpenList route), or compile the merged source with a source build hook.
+# Stage daemon.targets under synology/; pin toolchains/dependencies for builds.
+# Keep upstream source unchanged.
+# Every App lifecycle phase uses the package UID. Do not add root/chown hooks.
+echo 'SOURCE_BUILD_REQUIRED: implement the native synology/build-source.sh.' >&2
+exit 2

package/assets/init-upstream/update-image.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Use the CLI's existing OCI registry resolver; never build or publish an image.
+import {mkdtempSync, readFileSync, writeFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {spawnSync} from 'node:child_process';
+const [tag] = process.argv.slice(2);
+const match = /^v?((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/.exec(tag ?? '');
+if (!match) throw new Error('Use the selected stable upstream tag.');
+const config = JSON.parse(readFileSync(new URL('./upstream-recipe.json', import.meta.url), 'utf8'));
+if (config.kind !== 'official-image' || !['tag', 'version'].includes(config.imageTag)) throw new Error('Invalid official image recipe.');
+const imageTag = config.imageTag === 'version' ? match[1] : tag;
+const reference = `${config.repository}:${imageTag}`;
+const temp = mkdtempSync(join(tmpdir(), 'synopkgland-image-pin-'));
+try {
+  // images pin edits only compose.yaml; use a bounded temporary project so the
+  // App's base Compose and upstream source remain unchanged on lookup failure.
+  writeFileSync(join(temp, 'dsm-package.yaml'), 'schema: 2\n');
+  writeFileSync(join(temp, 'compose.yaml'), JSON.stringify({services: {[config.service]: {image: reference}}}, null, 2) + '\n');
+  const result = spawnSync('synopkgland', ['--project', temp, 'images', 'pin'], {stdio: 'inherit'});
+  if (result.error || result.status !== 0) throw new Error('Official image digest lookup failed; no Compose override was changed.');
+  const pinned = JSON.parse(readFileSync(join(temp, 'compose.yaml'), 'utf8'));
+  const image = pinned.services[config.service].image;
+  if (!image.startsWith(`${reference}@sha256:`) || !/@sha256:[0-9a-f]{64}$/.test(image)) throw new Error('Registry lookup did not produce the selected tag plus digest.');
+  writeFileSync(new URL('./compose.image.yaml', import.meta.url), JSON.stringify(pinned, null, 2) + '\n');
+} finally {rmSync(temp, {recursive: true, force: true});}

package/assets/init-upstream/upgrade.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# One explicit stable tag; no latest guessing, push, image publication or NAS access.
+set -euo pipefail
+packaging=$(cd -- "$(dirname -- "$0")" && pwd)
+repo=$(cd -- "$packaging/.." && pwd)
+cd "$repo"
+[[ $# == 2 && $1 =~ ^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]] || {
+  echo 'Usage: bash synology/upgrade.sh <[v]X.Y.Z> <increasing-build-number>' >&2; exit 2;
+}
+[[ $(git rev-parse --show-toplevel) == "$repo" ]] || { echo 'Run inside a source fork.' >&2; exit 2; }
+[[ -z $(git status --porcelain --untracked-files=normal) ]] || { echo 'Commit changes before upgrading.' >&2; exit 2; }
+git remote get-url upstream >/dev/null
+node "$packaging/version.mjs" "$1" "$2" --validate
+# Fetch the named remote tag into a private ref: a local tag can never substitute for it.
+git fetch --no-tags upstream "+refs/tags/$1:refs/synopkgland/selected-upstream"
+commit=$(git rev-parse 'refs/synopkgland/selected-upstream^{commit}')
+[[ -z $(git ls-tree "$commit" -- synology) ]] || { echo 'Upstream owns synology/; choose another integration layout.' >&2; exit 2; }
+previous=$(git describe --tags --abbrev=0 --match '[0-9]*' --match 'v[0-9]*' HEAD 2>/dev/null || true)
+if [[ -f "$packaging/upstream-source.json" ]]; then
+  previous=$(node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(process.argv[1])).commit)' "$packaging/upstream-source.json")
+fi
+if [[ -n $previous ]]; then
+  git merge-base --is-ancestor "$previous" "$commit" || { echo 'Refusing upstream downgrade/divergent history.' >&2; exit 2; }
+  [[ -z $(git diff "$previous" HEAD -- . ':(exclude)synology') ]] || { echo 'Wrapper changed upstream files outside synology/.' >&2; exit 2; }
+else
+  # First adoption must already be based on the selected source tag.
+  git merge-base --is-ancestor "$commit" HEAD
+  [[ -z $(git diff "$commit" HEAD -- . ':(exclude)synology') ]] || { echo 'Initial fork must preserve upstream source.' >&2; exit 2; }
+fi
+git merge --no-ff --no-edit "$commit"
+[[ -z $(git diff "$commit" HEAD -- . ':(exclude)synology') ]] || { echo 'Upstream files differ after merge; resolve before building.' >&2; exit 2; }
+kind=$(node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(process.argv[1])).kind)' "$packaging/upstream-recipe.json")
+if [[ $kind == official-image ]]; then
+  node "$packaging/update-image.mjs" "$1"
+elif [[ $kind != native-source ]]; then
+  echo 'Unknown upstream recipe kind.' >&2; exit 2
+fi
+node "$packaging/version.mjs" "$1" "$2"
+node -e 'const fs=require("fs");fs.writeFileSync(process.argv[1],JSON.stringify({tag:process.argv[2],commit:process.argv[3],build:Number(process.argv[4])},null,2)+"\n")' "$packaging/upstream-source.json" "$1" "$commit" "$2"
+export SPL_UPSTREAM_SOURCE="$repo"
+export SPL_UPSTREAM_TAG="$1"
+export SPL_UPSTREAM_COMMIT="$commit"
+cd "$packaging"
+if [[ $kind == native-source ]]; then bash ./build-source.sh; fi
+synopkgland check --json
+synopkgland build --json
+# Review version/provenance and commit synology/ before the next upgrade.

package/assets/init-upstream/version.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Stable tag -> DSM version. Keep all wrapper-owned changes under synology/.
+import {readFileSync, writeFileSync} from 'node:fs';
+const [tag, build, mode] = process.argv.slice(2);
+const match = /^v?((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/.exec(tag ?? '');
+const file = new URL('./dsm-package.yaml', import.meta.url);
+const source = readFileSync(file, 'utf8');
+const current = /^build: (\d+)\s*$/m.exec(source);
+if (!match || !/^[1-9][0-9]{0,3}$/.test(build ?? '') || !current || Number(build) <= Number(current[1]))
+  throw new Error('Use a stable [v]X.Y.Z tag and an increasing packaging build (1–9999).');
+if (!/^version: .+$/m.test(source)) throw new Error('Missing scaffold version.');
+if (mode !== '--validate') writeFileSync(file, source.replace(/^version: .+$/m, `version: ${match[1]}`).replace(/^build: \d+\s*$/m, `build: ${Number(build)}`));

package/dist/cli.js

@@ -421,6 +421,10 @@ export async function runCli(argv) {
         .option("-t, --template <name>", `Template: ${listTemplates().join(" | ")}`)
         .option("--package <id>", "INFO.package (defaults to the directory name)")
         .option("--name <display>", "Display name")
+        .option("--upstream-image <repository>", "compose fork: official image repository; upgrade pins its matching tag and index digest")
+        .option("--upstream-fork", "Create only synology/ inside an upstream source fork (compose or native-go)")
+        .option("--health-path <path>", "compose: actual readiness endpoint; redirects are not followed")
+        .option("--health-status <status>", "compose: expected 2xx readiness status (no default)", Number)
         .option("--ui <vue|plain>", `Native UI ${JSON.parse(readFileSync(join(templatesRoot(), "native-go-vue/frontend/package.json"), "utf8")).dependencies["@synopackageland/ui"]} by default (vue); plain uses ui/app.js`)
         .option("--with <caps>", `Capabilities (comma-separated): ${CAPABILITY_NAMES.join(",")}`)
         .option("--from <compose.yaml>", "compose: import an existing Compose; omit to create an example")
@@ -430,7 +434,7 @@ export async function runCli(argv) {
         .option("--shared-folder-permission <ro|rw>", "Package account permission, defaults to rw")
         .option("--min-dsm <version>", `Minimum DSM version (native templates and binary default to ${DEFAULT_MIN_DSM}, compose to ${CONTAINER_MIN_DSM})`)
         .argument("[dir]", "Target directory", ".")
-        .addHelpText("after", "\nNative projects: native-go, native-python, native-node, native-rust and binary use dsm-package.yaml schema 2.\nCompose projects: compose uses synology-app.yaml; --from imports compose.yaml.\nQuick start: synopkgland init -t native-go --with files,jobs,login my-app\n  cd my-app && synopkgland build\n")
+        .addHelpText("after", "\nNative projects: native-go, native-python, native-node, native-rust and binary use dsm-package.yaml schema 2.\nCompose projects: compose uses dsm-package.yaml schema 2; --from imports compose.yaml.\nQuick start: synopkgland init -t native-go --with files,jobs,login my-app\n  cd my-app && synopkgland build\n")
         .action((dir, options, command) => {
         if (command.parent?.opts().project)
             throw failure("CLI_OPTION_INVALID", "--project does not apply to init.");
@@ -440,6 +444,10 @@ export async function runCli(argv) {
             throw failure("INIT_TEMPLATE_UNKNOWN", `Unknown template: ${options.template}`);
         const targetDir = resolve(dir);
         initFromTemplate(options.template, targetDir, {
+            upstreamFork: options.upstreamFork,
+            upstreamImage: options.upstreamImage,
+            healthPath: options.healthPath,
+            healthStatus: options.healthStatus,
             packageId: options.package,
             displayName: options.name,
             minDsm: options.minDsm,
@@ -457,7 +465,13 @@ export async function runCli(argv) {
                     permission: options.sharedFolderPermission,
                 },
         });
-        stdout(`Created the ${options.template} project at ${targetDir}`);
+        stdout(`Created the ${options.template} project at ${options.upstreamFork ? join(targetDir, "synology") : targetDir}`);
+        if (options.template === "compose")
+            stdout("Select actual compose.web.health path/status before check/build. Redirects are not followed; check does not probe runtime health.");
+        if (options.upstreamFork) {
+            stdout("Read synology/AGENTS.md; configure the official image recipe or the native source hook, then run bash synology/upgrade.sh <upstream-tag> <build-number>.");
+            return;
+        }
         const next = initNextSteps(options.template, dir, existsSync(join(targetDir, "frontend", "package.json")), Boolean(process.env.SYNOPKGLAND_SDK_DIR));
         if (next)
             stdout(next);

package/dist/e2e/dsm.d.ts

@@ -105,7 +105,7 @@ type SessionPage = {
 /**
  * Registers the signed-in session's cookies (id, did, _SSID) and SynoToken as
  * e2e secrets, so e2e masks them in its report and output, as a request's
- * Playwright call log carries them (t-0498). Returns how many were registered.
+ * Playwright call log carries them. Returns how many were registered.
  */
 export declare function registerDsmSecrets(page?: SessionPage, ledger?: SecretLedger): Promise<number>;
 /**
@@ -136,7 +136,7 @@ export declare function dsmSessionLive(page: Pick<SessionPage, "evaluate">): Pro
 /**
  * `app.open(path)`, once more after net::ERR_ABORTED: about one first
  * navigation in ten was aborted as DSM's desktop navigated on its own, and the
- * next one loaded (t-0499, t-0500). Any other failure, or a second abort, is
+ * next one loaded. Any other failure, or a second abort, is
  * thrown.
  */
 export declare function openPath(app: Pick<App, "open">, path: string): Promise<void>;

package/dist/e2e/dsm.js

@@ -135,7 +135,7 @@ export async function runWithTunnel(command, outer = process.env) {
 // ---- Secrets in output ----------------------------------------------------
 // e2e redacts only the secrets its config declares. A Playwright call log in a
 // run error lists a request's headers, DSM's session cookie among them, and e2e
-// writes it to the report and stdout (t-0498). A value runs to a quote, a
+// writes it to the report and stdout. A value runs to a quote, a
 // backslash or a line end, so a JSON string's escapes end it too.
 const mask = "***";
 // A Cookie or Set-Cookie header, and in it DSM's session (id, _SSID) and device (did) cookies.
@@ -324,7 +324,7 @@ async function e2eSecretLedger() {
 /**
  * Registers the signed-in session's cookies (id, did, _SSID) and SynoToken as
  * e2e secrets, so e2e masks them in its report and output, as a request's
- * Playwright call log carries them (t-0498). Returns how many were registered.
+ * Playwright call log carries them. Returns how many were registered.
  */
 export async function registerDsmSecrets(page = dsmPage(), ledger) {
     const target = ledger ?? await e2eSecretLedger();
@@ -410,7 +410,7 @@ function accountFile(user, env) {
 /**
  * `app.open(path)`, once more after net::ERR_ABORTED: about one first
  * navigation in ten was aborted as DSM's desktop navigated on its own, and the
- * next one loaded (t-0499, t-0500). Any other failure, or a second abort, is
+ * next one loaded. Any other failure, or a second abort, is
  * thrown.
  */
 export async function openPath(app, path) {

package/dist/error-registry.js

@@ -1,7 +1,11 @@
 import { COMPOSE_ERRORS } from "./standalone/compose-errors.js";
 export const ERROR_REGISTRY = {
     ...COMPOSE_ERRORS,
+    INIT_HEALTH_INVALID: { code: "INIT_HEALTH_INVALID", description: "The Compose readiness selection is invalid.", suggestion: "Supply both --health-path and --health-status with the actual endpoint and expected 2xx response; redirects are not followed." },
+    INIT_UPSTREAM_IMAGE_REQUIRED: { code: "INIT_UPSTREAM_IMAGE_REQUIRED", description: "The official upstream image repository was not selected.", suggestion: "Use init --upstream-fork --upstream-image <official-repository> for Compose." },
+    INIT_UPSTREAM_IMAGE_INVALID: { code: "INIT_UPSTREAM_IMAGE_INVALID", description: "The upstream image repository is invalid.", suggestion: "Supply the official repository without a tag or digest; upgrade.sh selects the matching release and resolves its digest." },
     CTL_TRUST_REQUIRED: { "code": "CTL_TRUST_REQUIRED", "description": "App description access requires approval.", "suggestion": "Run synopkgland ctl list with explicit host and approve the candidate batch." },
+    COMPOSE_HEALTH_REQUIRED: { code: "COMPOSE_HEALTH_REQUIRED", description: "Compose web readiness was not selected.", suggestion: "Set compose.web.health.path and expected 2xx status for the actual App; redirects are not followed." },
     CTL_UNSUPPORTED_BACKEND: { "code": "CTL_UNSUPPORTED_BACKEND", "description": "Automatic descriptions require a native SDK backend.", "suggestion": "Disable ctl for binary/Compose wrappers or implement the public contract separately." },
     CTL_DESCRIBE_REQUIRED: { "code": "CTL_DESCRIBE_REQUIRED", "description": "The Go backend has no build-only registry exporter.", "suggestion": "Update the native template and implement --describe using api.DescribeRoutes." },
     CTL_DESCRIBE_FAILED: { "code": "CTL_DESCRIBE_FAILED", "description": "The backend registry export failed.", "suggestion": "Check the backend --describe output and build diagnostics." },

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

@@ -10,7 +10,7 @@
  * 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, `newadmin` has is_writable=false on
+ * 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
  * `administrators` group row carries the grant. A user-row-only check rejects
  * the only configuration with live proof behind it.

package/dist/host/share-permission.js

@@ -10,7 +10,7 @@
  * 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, `newadmin` has is_writable=false on
+ * 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
  * `administrators` group row carries the grant. A user-row-only check rejects
  * the only configuration with live proof behind it.

package/dist/init-upstream.d.ts

@@ -0,0 +1,7 @@
+export interface ForkRecipeOptions {
+    upstreamImage?: string;
+    from?: string;
+}
+export declare function validateForkRecipe(template: 'compose' | 'native-go', options: ForkRecipeOptions): void;
+/** CLI-owned packaging recipe; upstream files and history stay untouched. */
+export declare function writeForkScaffold(packaging: string, template: 'compose' | 'native-go', options: ForkRecipeOptions): void;

package/dist/init-upstream.js

@@ -0,0 +1,64 @@
+import { cpSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+import { API_PERMISSIONS_FILE } from './standalone/api-permissions.js';
+import { parseImageReference } from './images/pin.js';
+export function validateForkRecipe(template, options) {
+    if (template === 'native-go' && options.upstreamImage)
+        throw new Error('[INIT_OPTIONS_UNSUPPORTED] Native forks stage official release binaries or use a source build hook; image options apply only to compose.');
+    if (template !== 'compose')
+        return;
+    if (!options.upstreamImage)
+        throw new Error('[INIT_UPSTREAM_IMAGE_REQUIRED] Compose forks use official images: supply --upstream-image <official-repository>.');
+    const parsed = parseImageReference(options.upstreamImage);
+    if (!parsed || parsed.explicitTag || parsed.digest || !/^[a-z0-9][a-z0-9._:/-]*$/.test(options.upstreamImage) || options.upstreamImage.includes('//'))
+        throw new Error('[INIT_UPSTREAM_IMAGE_INVALID] Supply the official image repository without a tag or digest; upgrade.sh selects the matching upstream release tag.');
+}
+/** CLI-owned packaging recipe; upstream files and history stay untouched. */
+export function writeForkScaffold(packaging, template, options) {
+    const official = template === 'compose';
+    const assets = fileURLToPath(new URL('../assets/init-upstream/', import.meta.url));
+    for (const file of ['upgrade.sh', 'version.mjs', official ? 'update-image.mjs' : 'build-source.sh'])
+        cpSync(join(assets, file), join(packaging, file));
+    const manifest = join(packaging, 'dsm-package.yaml');
+    const doc = parseDocument(readFileSync(manifest, 'utf8'));
+    const service = official ? (doc.toJS().compose.web?.service ?? 'web') : undefined;
+    const recipe = official
+        ? { kind: 'official-image', repository: options.upstreamImage, service, imageTag: 'tag' }
+        : { kind: 'native-source' };
+    writeFileSync(join(packaging, 'upstream-recipe.json'), JSON.stringify(recipe, null, 2) + '\n');
+    doc.set('entry', 'admin-only');
+    if (official) {
+        doc.setIn(['identity_gateway', 'access'], 'dsm-admins');
+        if (!options.from) {
+            const path = join(packaging, 'compose.yaml');
+            const base = parseDocument(readFileSync(path, 'utf8'));
+            base.deleteIn(['services', service, 'command']);
+            base.setIn(['services', service, 'image'], `${options.upstreamImage}:SELECT_UPSTREAM_TAG`);
+            writeFileSync(path, String(base));
+        }
+        doc.setIn(['compose', 'files'], [...doc.toJS().compose.files, 'compose.image.yaml']);
+        writeFileSync(join(packaging, 'compose.image.yaml'), JSON.stringify({ services: { [service]: { image: `${options.upstreamImage}:SELECT_UPSTREAM_TAG` } } }, null, 2) + '\n');
+    }
+    if (!official) {
+        const path = join(packaging, 'backend', API_PERMISSIONS_FILE.go);
+        const policy = JSON.parse(readFileSync(path, 'utf8'));
+        for (const method of Object.keys(policy.methods))
+            policy.methods[method] = 'administrators';
+        writeFileSync(path, JSON.stringify(policy, null, 2) + '\n');
+    }
+    writeFileSync(manifest, String(doc));
+    const guidance = `
+## Integrating an existing open-source App
+
+Keep the upstream fork/history and remote upstream. All wrapper-owned files belong in synology/; never edit upstream files or treat the App as an SDK component. Read synopkgland skill show upstream-fork.
+
+Commit the scaffold, then run bash synology/upgrade.sh <upstream-tag> <build-number>. It fetches the exact tag, verifies ancestry/untouched upstream files, merges, derives version/provenance, checks and builds. Commit synology/ before upgrading again. It does not publish or touch a NAS.
+
+${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.
+`;
+    writeFileSync(join(packaging, 'AGENTS.md'), readFileSync(join(packaging, 'AGENTS.md'), 'utf8') + guidance);
+}

package/dist/init.d.ts

@@ -16,6 +16,10 @@ export interface InitOptions {
     ui?: "plain" | "vue";
     with?: string[];
     from?: string;
+    upstreamFork?: boolean;
+    upstreamImage?: string;
+    healthPath?: string;
+    healthStatus?: number;
     /** native-go: `install.sharedFolder` (select from the NAS, or create one). key defaults to "shared", permission to "rw". */
     sharedFolder?: {
         mode: "select" | "create";

package/dist/init.js

@@ -1,3 +1,4 @@
+import { validateForkRecipe, writeForkScaffold } from "./init-upstream.js";
 import { goChildEnv } from "./runtime/go-env.js";
 import { spawnSync } from "node:child_process";
 import { parse, parseDocument } from "yaml";
@@ -112,6 +113,30 @@ function isTemplateBuildArtifact(path) {
     return (name === "node_modules" || name === "dist" || name === ".go-results.json");
 }
 export function initFromTemplate(template, targetDir, options = {}) {
+    if (options.upstreamFork) {
+        if (template !== "compose" && template !== "native-go")
+            throw new Error("[INIT_OPTIONS_UNSUPPORTED] --upstream-fork supports compose or native-go.");
+        validateForkRecipe(template, options);
+        const packaging = join(targetDir, "synology");
+        if (existsSync(packaging))
+            throw new Error("[INIT_TARGET_NOT_EMPTY] synology/ already exists.");
+        initFromTemplate(template, packaging, {
+            ...options,
+            packageId: options.packageId ?? defaultPackageId(targetDir),
+            displayName: options.displayName ?? defaultDisplayName(targetDir),
+            upstreamFork: false,
+            upstreamImage: undefined,
+        });
+        writeForkScaffold(packaging, template, options);
+        return;
+    }
+    if (options.upstreamImage)
+        throw new Error("[INIT_OPTIONS_UNSUPPORTED] Image recipe options require --upstream-fork.");
+    const hasHealth = options.healthPath !== undefined || options.healthStatus !== undefined;
+    if (hasHealth && (template !== "compose" || typeof options.healthPath !== "string" ||
+        !/^\/(?!\/)[^\s#\\]*$/.test(options.healthPath) || !Number.isInteger(options.healthStatus) ||
+        options.healthStatus < 200 || options.healthStatus > 299))
+        throw new Error("[INIT_HEALTH_INVALID] Compose health needs both --health-path /actual-endpoint and --health-status 2xx; redirects are not followed.");
     if (!isTemplateName(template))
         throw new Error(`[INIT_TEMPLATE_UNKNOWN] Unknown template: ${template}`);
     const requested = capabilityNames(options.with ?? []);
@@ -261,6 +286,18 @@ export function initFromTemplate(template, targetDir, options = {}) {
     }
     if (template === "compose" && options.from)
         importCompose(options.from, targetDir);
+    if (template === "compose") {
+        const path = join(targetDir, "dsm-package.yaml");
+        const doc = parseDocument(readFileSync(path, "utf8"));
+        if (doc.hasIn(["compose", "web"])) {
+            doc.deleteIn(["compose", "web", "health"]);
+            if (hasHealth)
+                doc.setIn(["compose", "web", "health"], { path: options.healthPath, status: options.healthStatus });
+        }
+        writeFileSync(path, String(doc));
+        const guidance = readFileSync(new URL("../assets/init-compose.md", import.meta.url), "utf8");
+        writeFileSync(join(targetDir, "AGENTS.md"), guidance);
+    }
     if (template === "binary") {
         mkdirSync(join(targetDir, "prebuilt"), { recursive: true });
         for (const [arch, goarch] of [
@@ -356,7 +393,6 @@ function importCompose(from, targetDir) {
     if (candidates.length === 1)
         doc.setIn(["compose", "web"], {
             ...candidates[0],
-            health: { path: "/", status: 200 },
         });
     else {
         doc.deleteIn(["compose", "web"]);

package/dist/runtime/dsm-version.d.ts

@@ -1,6 +1,6 @@
 /** Self-contained: the same function is embedded in the DSM window. True only
  * when DSM refused a request because this method version is unavailable, the
- * one refusal that may be retried with an older version. DSM 7.1.1 (t-0234)
+ * one refusal that may be retried with an older version. DSM 7.1.1
  * returns 104 for a version above maxVersion and 103 for a method absent at an
  * existing version. Accepts the numeric code and the window's dsm_ form. */
 export declare function versionUnsupported(code: unknown): boolean;

package/dist/runtime/dsm-version.js

@@ -1,6 +1,6 @@
 /** Self-contained: the same function is embedded in the DSM window. True only
  * when DSM refused a request because this method version is unavailable, the
- * one refusal that may be retried with an older version. DSM 7.1.1 (t-0234)
+ * one refusal that may be retried with an older version. DSM 7.1.1
  * returns 104 for a version above maxVersion and 103 for a method absent at an
  * existing version. Accepts the numeric code and the window's dsm_ form. */
 export function versionUnsupported(code) {

package/dist/runtime/executor-digests.json

@@ -1,27 +1,5 @@
 {
-    "0.15.0": {
-        "x86_64": "efe409287770f6b70e7f8465e8767eeb2413b9ab8775020cf4dffb1555d7bf1f",
-        "aarch64": "d68c9889ed2391e918b9c278679ea0a01cd04425528c11090700a3b6341fc543",
-        "armv7": "9149a05efb9f2d7d86a400707099b3d657382b1c0dbad6588be8c500e90445cc",
-        "lifecycle": {
-            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
-            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
-            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.15.1": {
-        "x86_64": "4f47fb43f6e60dbad064afb0bbec96dd009fa046670e2c4b590b128a855cb404",
-        "aarch64": "c903b09ad657a838f0c62b6688e65e9094572b22b969770fca92fcc3640a5364",
-        "armv7": "8178d90de7ea720530bb9496e50ed118086b0e57382d84675aadc68f482d219f",
-        "lifecycle": {
-            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
-            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
-            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.15.2": {
+    "0.16.0": {
         "x86_64": "4f47fb43f6e60dbad064afb0bbec96dd009fa046670e2c4b590b128a855cb404",
         "aarch64": "c903b09ad657a838f0c62b6688e65e9094572b22b969770fca92fcc3640a5364",
         "armv7": "8178d90de7ea720530bb9496e50ed118086b0e57382d84675aadc68f482d219f",

package/dist/skill.js

@@ -14,6 +14,7 @@ const SKILL_CATALOG = [
         file: "reference/compose.md",
         when: "Upstream Compose with the SDK planner, fixed identity and support boundary",
     },
+    { id: "upstream-fork", file: "reference/upstream-fork.md", when: "Package an upstream source fork without changing upstream files" },
     {
         id: "wrap",
         file: "reference/wrap.md",

package/dist/standalone/build.js

@@ -10,7 +10,7 @@ import { resolveMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM,
 import { checkCgiBinary } from "./binary.js";
 import { loadStandaloneManifest, } from "./manifest.js";
 import { assembleStandaloneSpk, StandaloneBuildError } from "./spk.js";
-import { buildComposeControl, lockComposeImages, dsmComposeProblem, } from "./compose.js";
+import { buildComposeControl, buildComposeStorageInit, lockComposeImages, dsmComposeProblem, } from "./compose.js";
 import { buildDaemonControl } from "./daemon.js";
 import { buildIdentityGateway } from "./identity-gateway.js";
 import { buildExecutor } from "../runtime/executor-build.js";
@@ -148,6 +148,7 @@ export async function buildStandalone(options) {
             const daemonControl = await buildDaemonControl(manifest, arch, archWork, run);
             const identityGateway = await buildIdentityGateway(manifest, arch, archWork, run);
             const composeControl = await buildComposeControl(manifest, arch, archWork, run);
+            const composeStorageInit = await buildComposeStorageInit(manifest, arch, archWork, run);
             // A portal needs the executor, so the executor's SDK carries the panel text.
             const portalText = manifest.portal && executor
                 ? portalCatalogs(sdkSource(executor.sdk).goDir)
@@ -160,6 +161,7 @@ export async function buildStandalone(options) {
                 daemonControl,
                 identityGateway,
                 composeControl,
+                composeStorageInit,
                 backgroundWorker,
                 executor,
                 app,

package/dist/standalone/compose-errors.js

@@ -1,5 +1,20 @@
 /** SDK planner errors accepted at this versioned tool boundary. */
 export const COMPOSE_ERRORS = {
+    COMPOSE_STORAGE_INIT_INVALID: {
+        code: "COMPOSE_STORAGE_INIT_INVALID",
+        description: "The container storage initialization declaration is invalid.",
+        suggestion: "Declare private subdirectories on writable mounts and explicit upstream entrypoint/command argv; keep the service nonroot. The SDK initializer is supplied by the SPK.",
+    },
+    COMPOSE_STORAGE_NOT_WRITABLE: {
+        code: "COMPOSE_STORAGE_NOT_WRITABLE",
+        description: "The package UID cannot initialize or write its private container data.",
+        suggestion: "Use a writable mount base with a package-owned private subtree; inspect ownership, permissions, read-only storage, quota and free space. Do not add root or chown hooks.",
+    },
+    COMPOSE_STORAGE_COMMAND_INVALID: {
+        code: "COMPOSE_STORAGE_COMMAND_INVALID",
+        description: "The application command after storage preflight cannot be executed.",
+        suggestion: "Declare the actual upstream executable and arguments. Keep the upstream official image unchanged; the SPK supplies the SDK initializer.",
+    },
     COMPOSE_SUBNET_STATE_INVALID: {
         code: "COMPOSE_SUBNET_STATE_INVALID",
         description: "The private ingress history is invalid or has foreign ownership.",

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

@@ -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);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.15.4",
+  "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.4. 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.