@synopackageland/cli 0.17.7 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.18.0 (2026-10-20)
+
+- Support the SDK 0.18.x minor line and pin templates 0.18.0 with SDK/App 0.18.0 and UI 0.12.5.
+- Record SDK 0.18.0 executor and lifecycle digests and refresh executor setup fixtures.
+- Add the native OIDC browser bridge and App launch resume flow.
+- Default upstream forks to no ctl integration and document the fixed ctl coverage checklist.
+- Declare optional native-client passthrough capabilities.
+
+## 0.17.8 (2026-10-20)
+
+- Update SDK 0.17.7 executor and lifecycle digests for the administrator-role fix.
+
 ## 0.17.7 (2026-10-20)
 
 - Inspect Compose Apps with custom icons and localized titles using their archived build inputs, preserving every icon size and strict launcher validation. Preserve declared daemon uninstall hooks when checking fixed lifecycle scripts.

package/dist/init-upstream.js

@@ -29,6 +29,7 @@ export function writeForkScaffold(packaging, template, options) {
         : { kind: 'native-source' };
     writeFileSync(join(packaging, 'upstream-recipe.json'), JSON.stringify(recipe, null, 2) + '\n');
     doc.set('entry', 'admin-only');
+    doc.delete('ctl');
     if (official) {
         doc.setIn(['identity_gateway', 'access'], 'dsm-admins');
         if (!options.from) {
@@ -54,6 +55,8 @@ export function writeForkScaffold(packaging, template, options) {
 
 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.
 
+Leave ctl absent from the manifest by default. Ask whether the user wants AI control; add ctl only when explicitly requested. If requested, read synopkgland skill show ctl and produce ctl-plan covering existing UI actions and public API endpoints, including common reads and writes. Status-only commands do not meet completion. Wrap existing native APIs without changing upstream code or inventing features. Long operations must return through existing asynchronous APIs without waiting for completion; report synchronous-only long APIs as blockers for discussion.
+
 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.'}

package/dist/runtime/executor-digests.json

@@ -1,56 +1,12 @@
 {
-    "0.17.0": {
-        "x86_64": "68f372684997258adc61312f2c353e1a286a6b5aaa556f716b4e6ba6f33893d0",
-        "aarch64": "f6950301e201a4ebc14577a4554fa1b671f90d0f354d1e8809f4d1dafb57c723",
-        "armv7": "e77c9b6ae22ecfa85d9834af3350192e445987265a7ca6c02ca9b01d88a1b4f7",
-        "lifecycle": {
-            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
-            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
-            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.17.1": {
-        "x86_64": "68f372684997258adc61312f2c353e1a286a6b5aaa556f716b4e6ba6f33893d0",
-        "aarch64": "f6950301e201a4ebc14577a4554fa1b671f90d0f354d1e8809f4d1dafb57c723",
-        "armv7": "e77c9b6ae22ecfa85d9834af3350192e445987265a7ca6c02ca9b01d88a1b4f7",
-        "lifecycle": {
-            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
-            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
-            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.17.3": {
-        "x86_64": "68f372684997258adc61312f2c353e1a286a6b5aaa556f716b4e6ba6f33893d0",
-        "aarch64": "f6950301e201a4ebc14577a4554fa1b671f90d0f354d1e8809f4d1dafb57c723",
-        "armv7": "e77c9b6ae22ecfa85d9834af3350192e445987265a7ca6c02ca9b01d88a1b4f7",
-        "lifecycle": {
-            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
-            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
-            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.17.4": {
-        "x86_64": "68f372684997258adc61312f2c353e1a286a6b5aaa556f716b4e6ba6f33893d0",
-        "aarch64": "f6950301e201a4ebc14577a4554fa1b671f90d0f354d1e8809f4d1dafb57c723",
-        "armv7": "e77c9b6ae22ecfa85d9834af3350192e445987265a7ca6c02ca9b01d88a1b4f7",
-        "lifecycle": {
-            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
-            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
-            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.17.5": {
-        "x86_64": "af37ecd6bb5ab3e954b5f5bb3db2499b3cf86f0502afdcea18e8dc0614a46e5d",
-        "aarch64": "87436df3f591e0126d88866922b032968d0dbd01a109de53ab751ef779257baf",
-        "armv7": "de354d6e582ad1fe3124c3f30eb7f3ce8af456b0fcfad8f23c10421d3a3f3d42",
-        "lifecycle": {
-            "x86_64": "f3b368c86677741b48b059699a86c935157ea797634a6116131678e8bbaf33ed",
-            "aarch64": "b6ccd1365844e6eee9db4ce5833b655f4f1e138bf34317cdbd0e2342d3342a9e",
-            "armv7": "57b6350c2812783cb536384f8b363c26d894af6589b5f19464d71d8d0a8035d5"
+    "0.18.0": {
+        "x86_64": "6d9d5a12ac4c990639b31c555560a1b6e49cbe1c267c626a23b91833dcc4452e",
+        "aarch64": "efbed582ce1249fed09de72b7bbe553510a55553e44ccf76fa93c684864e8bb8",
+        "armv7": "670f83c3349497263c96b0244ec142153c094d5e223dae091c9c8614c0ea04b6",
+        "lifecycle": {
+            "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972",
+            "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb",
+            "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
         },
         "goToolchain": "go1.26.9"
     }

package/dist/standalone/dsm-window.js

@@ -1,3 +1,4 @@
+import { oidcResumeRuntime } from "./oidc-resume.js";
 import { gatewayEntryPath } from './native-gateway.js';
 import { resolvedSdkLaunch, dsmLauncherType } from "../contract/app-launch.js";
 import { REOPEN_EVENTS_RUNTIME } from "./reopen-events.js";
@@ -378,6 +379,8 @@ ${ns}.prepareFullPage = function (title) {
   favicon.href = ${ns}.appIcon;
 };
 
+${manifest.identityGateway?.oidc?.browser ? `${ns}.resumeOIDC = ${oidcResumeRuntime(pkg, Object.values(manifest.identityGateway.listen).filter((p) => typeof p === "number"))};` : ""}
+
 // DSM reopens a window at the size it was last left at, even one saved on a
 // larger screen, and only moves a window that does not fit: keep it inside.
 ${ns}.fitDesktop = function (size) {
@@ -405,6 +408,7 @@ Ext.define(${JSON.stringify(`${ns}.MainWindow`)}, {
   },
   onOpen: function (param) {
     this.callParent(arguments);
+    ${manifest.identityGateway?.oidc?.browser ? `if (${ns}.resumeOIDC(param)) return;` : ""}
     var me = this;
     if (me.mounted) {
       me.reopenEvents.emit();
@@ -467,6 +471,7 @@ ${root ? root.mount : ""}    ${ns}.loadApp(function (app) {
   // with that launch's param. Before the App mounts, it mounts with the latest.
   onRequest: function (param) {
     this.callParent(arguments);
+    ${manifest.identityGateway?.oidc?.browser ? `if (${ns}.resumeOIDC(param)) return;` : ""}
     var params = ${ns}.launchParams(param);
     if (!this.mounted) {
       if (this.mountPending && Object.keys(params).length) this.launchParams = params;

package/dist/standalone/identity-gateway.d.ts

@@ -24,6 +24,12 @@ export interface GatewayClient {
     require_pkce: boolean;
     roles?: GatewayRoles;
 }
+export interface GatewayBrowser {
+    start: string;
+    login_paths: string[];
+    callback_paths: string[];
+    completion_query?: string;
+}
 /** `identity_gateway`: signs DSM users in to the App's own web UI. */
 export interface IdentityGateway {
     /** The SDK release the gateway is built from. */
@@ -40,6 +46,9 @@ export interface IdentityGateway {
         https?: number;
     };
     passthrough: string[];
+    optional_passthrough?: Record<string, {
+        prefixes: string[];
+    }>;
     redirects: Record<string, string>;
     email_domain?: string;
     session_ttl?: number;
@@ -47,6 +56,7 @@ export interface IdentityGateway {
     headers?: Partial<Record<"user" | "email" | "name" | "groups" | "uid", string>>;
     oidc?: {
         issuer_port: number;
+        browser?: GatewayBrowser;
         clients: GatewayClient[];
         rewrite_json: {
             method: string;

package/dist/standalone/identity-gateway.js

@@ -133,6 +133,7 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
             "upstream",
             "listen",
             "passthrough",
+            "optional_passthrough",
             "redirects",
             "email_domain",
             "session_ttl",
@@ -193,6 +194,28 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
     const passthrough = v.passthrough ?? [];
     if (!strings(passthrough, (p) => localPath(p) && p !== "/" && !/^\/_sso(\/|$)/.test(p)))
         return invalid("passthrough must be path prefixes such as /share/, outside /_sso.");
+    const optional = v.optional_passthrough;
+    if (optional !== undefined) {
+        const [major, minor] = v.sdk.split(".").map(Number);
+        if (!(major > 0 || minor >= 18))
+            return invalid("optional_passthrough requires the next minor SDK (0.18.0 or later).");
+        if (!record(optional) || Object.keys(optional).length > 16)
+            return invalid("optional_passthrough is a map of at most 16 fixed entries.");
+        const prefixes = [...passthrough];
+        const contains = (p, base) => p === base.replace(/\/$/, "") || p.startsWith(base.replace(/\/$/, "") + "/");
+        for (const [id, rule] of Object.entries(optional)) {
+            if (!name(id) || !record(rule) || !only(rule, ["prefixes"]) ||
+                !strings(rule.prefixes, p => localPath(p) && p !== "/" &&
+                    !p.includes("//") && !p.includes("%") && !/^\/_sso(\/|$)/.test(p), 16) ||
+                !rule.prefixes.length)
+                return invalid("optional_passthrough entries need a valid id and 1–16 fixed prefixes; they always default off.");
+            for (const prefix of rule.prefixes) {
+                if (prefixes.some(p => contains(prefix, p) || contains(p, prefix)))
+                    return invalid("optional and permanent passthrough prefixes must not overlap.");
+                prefixes.push(prefix);
+            }
+        }
+    }
     const redirects = v.redirects ?? {};
     if (!record(redirects) ||
         Object.entries(redirects).some(([from, to]) => !localPath(from) || !localPath(to)))
@@ -237,6 +260,7 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
             ...(listen.https ? { https: listen.https } : {}),
         },
         passthrough: passthrough,
+        ...(optional !== undefined ? { optional_passthrough: optional } : {}),
         redirects: redirects,
         ...(v.email_domain ? { email_domain: v.email_domain } : {}),
         ...(v.session_ttl ? { session_ttl: v.session_ttl } : {}),
@@ -246,7 +270,7 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
     if (v.mode === "oidc") {
         const o = v.oidc;
         if (!record(o) ||
-            !only(o, ["issuer_port", "clients", "rewrite_json"]) ||
+            !only(o, ["issuer_port", "clients", "rewrite_json", "browser"]) ||
             !port(o.issuer_port) ||
             !Array.isArray(o.clients) ||
             !o.clients.length ||
@@ -266,8 +290,30 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
                 name(r.field))) {
             return invalid("oidc.rewrite_json entries are { method, path, field }.");
         }
+        const b = o.browser;
+        if (b !== undefined) {
+            const [major, minor] = v.sdk.split(".").map(Number);
+            if (!(major > 0 || minor >= 18))
+                return invalid("oidc.browser requires SDK 0.18.0 or later.");
+            const path = (p) => localPath(p) && !p.includes("%") && !p.startsWith("/_sso");
+            let start;
+            if (record(b) && typeof b.start === "string") {
+                try {
+                    start = new URL(b.start, "https://app.invalid");
+                }
+                catch { /* invalid below */ }
+            }
+            if (!record(b) || !only(b, ["start", "login_paths", "callback_paths", "completion_query"]) ||
+                typeof b.start !== "string" || b.start.length > 1024 || !b.start.startsWith("/") || b.start.startsWith("//") ||
+                /[%\\\s#]/.test(b.start) || !start || start.origin !== "https://app.invalid" || !path(b.start.split("?")[0]) ||
+                !strings(b.login_paths, path, 16) || !b.login_paths.length ||
+                !strings(b.callback_paths, path, 16) || !b.callback_paths.length ||
+                (b.completion_query !== undefined && !name(b.completion_query)))
+                return invalid("oidc.browser needs fixed local start, login_paths and callback_paths outside /_sso.");
+        }
         gateway.oidc = {
             issuer_port: o.issuer_port,
+            ...(b !== undefined ? { browser: b } : {}),
             clients: clients,
             rewrite_json: rewrite,
         };
@@ -336,6 +382,7 @@ export function identityGatewayConfig(m) {
         authorize_cgi: `/webman/3rdparty/${m.package}/sso/authorize.cgi`,
         state_dir: `/var/packages/${m.package}/var/sso`,
         passthrough: g.passthrough,
+        ...(g.optional_passthrough ? { optional_passthrough: g.optional_passthrough } : {}),
         redirects: g.redirects,
         ...(g.email_domain ? { email_domain: g.email_domain } : {}),
         ...(g.session_ttl ? { session_ttl_seconds: g.session_ttl } : {}),

package/dist/standalone/oidc-resume.d.ts

@@ -0,0 +1,2 @@
+/** No caller-provided URL reaches location: only a transaction and a declared port. */
+export declare function oidcResumeRuntime(pkg: string, ports: number[]): string;

package/dist/standalone/oidc-resume.js

@@ -0,0 +1,16 @@
+/** No caller-provided URL reaches location: only a transaction and a declared port. */
+export function oidcResumeRuntime(pkg, ports) {
+    return `(function(param) {
+  var value = param && param.ssoResume;
+  if (typeof value !== 'string') return false;
+  var parts = /^([A-Za-z0-9_-]{1,128}):([0-9]{1,5})$/.exec(value);
+  if (!parts || ${JSON.stringify(ports)}.indexOf(Number(parts[2])) < 0) return false;
+  var target = new URL(${JSON.stringify(`/webman/3rdparty/${pkg}/sso/authorize.cgi`)},location.origin);
+  var app = new URL(location.origin); app.port = parts[2]; app.pathname = '/_sso/dsm-return';
+  target.searchParams.set('return',app.href);
+  target.searchParams.set('txn',parts[1]);
+  target.searchParams.set('login_attempt','1');
+  location.replace(target.href);
+  return true;
+ })`;
+}

package/package.json

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

package/skills/SKILL.md

@@ -9,6 +9,8 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
+For upstream OSS packaging, leave `ctl` absent from the manifest by default. Ask whether the user wants AI control; implement it only when explicitly requested. Read [reference/ctl.md](reference/ctl.md) for the required `ctl-plan`, UI/API coverage checklist and asynchronous-operation rules. Own Apps retain the native template's ctl defaults, with commands covering their main features; status-only coverage is incomplete.
+
 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.

package/skills/reference/create.md

@@ -1,5 +1,11 @@
 # 建立（Create）
 
+For upstream OSS Apps, ask whether AI control is needed and omit `ctl` from the
+manifest unless explicitly requested. Own Apps retain the template's ctl defaults.
+When designing commands for either kind, follow [ctl-plan and the coverage
+checklist](ctl.md#plan-command-coverage): cover existing main features, including
+common reads and writes, rather than stopping at status commands.
+
 先選擇 `native-go`（Go CGI + DSM 視窗）、`native-python`／`native-node`／`native-rust`（同一個 App，backend 換成 Python、Node.js（TypeScript）或 Rust）、`binary`（預建服務程式）或 `compose`（上游容器）。`compose` 產生 schema-2 的上游 Compose 範例與 DSM 差異宣告，`--from <compose.yaml>` 匯入現有 Compose。
 
 ```sh

package/skills/reference/ctl.md

@@ -14,18 +14,119 @@ Use `ctl host show nas` to inspect approvals/pins, `ctl host revoke nas PackageI
 
 Stdout defaults to JSON without a TTY. Success is {ok:true,data}; failure is {ok:false,error:{code,message,hint,allowed?}}. Multi-host output uses {ok,results:[{host,ok,data|error}]}. Follow the concrete hint and complete allowed list; do not guess another method or bypass ctl with raw HTTP. Exit codes: 2 authentication, 3 parameters/names, 4 permissions/trust, 5 App/contract, 6 network, 7 confirmation, 8 partial failure.
 
+## Plan command coverage
+
+For packaging an upstream open-source App (including forks with `synology/`),
+ask whether the user needs AI control unless it was already explicitly requested.
+Without that opt-in, omit the manifest's `ctl` block and do not build ctl adapters.
+Own Apps retain their native template ctl defaults and the command guidance below.
+For both kinds, commands must cover the App's existing main features, including
+common reads and writes; `status` / `service status` alone are incomplete.
+
+Before implementing commands, create `ctl-plan` in the task's requested artifact
+location (otherwise `ctl-plan.md` in the App's documentation; upstream wrappers
+keep it under `synology/`). Record each operation, existing UI action/API endpoint,
+proposed CLI path, effect, caller permission, upstream identity, risk/confirmation,
+coverage or exclusion reason, and validation evidence. Use these steps every time:
+
+1. List every main UI page and its primary buttons: list, details, create, update,
+   delete and enable/disable where present. Trace each action to its existing API.
+2. Inventory every externally exposed App CGI/API endpoint and every upstream
+   native API endpoint for the selected version, including non-REST transports.
+   Cross-reference each endpoint with the UI inventory and proposed commands.
+   Record internal-only, duplicate, sensitive or unsupported endpoints with a
+   specific exclusion reason; do not infer ctl coverage from route registration.
+3. Check each category below against the UI/API inventory. If present, cover its
+   common operations; if absent, record `N/A` with evidence and a reason. Record
+   unsupported existing capabilities as blockers, not as absent features.
+
+| Category | Required inventory |
+| --- | --- |
+| Main UI tasks | Every main page/button, including reads and available mutations |
+| API endpoints | Every external App CGI/API and upstream native endpoint, with a command mapping or exclusion reason |
+| Settings | Read and modify the existing main settings |
+| Diagnostics | Existing status, health, version and log-summary operations |
+| Search | Existing search, filters and bounded result traversal |
+| Long operations | Existing asynchronous start, progress/status, result, cancel and list capabilities, only where provided |
+| Import/export | Existing formats, limits and sensitive output |
+| Permissions | Existing access, grant and authorization-status queries |
+
+Completion requires every primary UI action and every public API endpoint to have
+a command mapping or a documented exclusion reason. All applicable categories
+must be accounted for, with common reads and writes validated. A blocked main
+task means coverage is incomplete even if its exclusion is documented. Review the
+plan against the actual selected source/UI, not a guessed list of useful features.
+Do not add an App capability solely to fill a checklist cell. Mark unsupported
+transports and missing APIs for discussion with the user.
+
+Validate mapped commands through their real handlers and the CLI schemas. Every
+write/destructive operation needs a non-mutating `--dry-run` plan and explicit
+confirmation before execution, plus a readback of the actual outcome. A CLI plan
+does not simulate upstream effects or replace backend authorization.
+
+Use existing native APIs without upstream source patches, database edits, root
+App processes or a second control service. Keep DSM admission, upstream API
+authentication and resource ownership distinct. An idgateway browser login,
+including OIDC, does not automatically grant headless API access; document the
+actual upstream token/header/API-password mapping and shared-account semantics.
+
 ## Designing commands for AI
 
 Declare explicit `ctl.commands` in dsm-package.yaml; build/inspect compare references with actual route registrations and permissions. Internal bindings are not CLI commands. Each command needs a stable cli path, description, parameter JSON Schema (descriptions/enums/defaults/examples), effect and examples. The build derives permissions; don't duplicate authorization. Missing schema means --input file/- only.
 
-Prefer a high-level backend method when sequencing is App-specific. Download Hub's immediate acceptance/background preparation, owner-bound search resultId, destination grants and BT file selection must not become a raw gopeed.request proxy. Offer downloads add/list/pause/resume and search tasks with stable responses. search.stream uses NDJSON; use the fixed ndjson flow, not the JSON method adapter. Torrent import needs a dedicated high-level backend contract, not a CLI-specific sequence.
+Wrap existing high-level backend methods when sequencing is App-specific. Download Hub's immediate acceptance/background preparation, owner-bound search resultId, destination grants and BT file selection must not become a raw gopeed.request proxy. Map its existing download/task/search APIs with stable responses. search.stream uses NDJSON; use the fixed ndjson flow, not the JSON method adapter. Use the existing high-level torrent contract; if one is missing, record the gap for discussion rather than inventing a CLI-specific sequence.
 
-Reclaim scan start/poll/result can use the fixed job flow once backend job identifiers/states have a stable documented shape. Existing job.result can be an explicit read command. Never automatically run cleanup.plan then cleanup.apply: the plan identity, freshness and permanent-deletion confirmation belong in the App backend; mark an eventual cleanup command destructive.
+Map Reclaim's existing scan start/status/result APIs with their documented identifiers and states. Never automatically run cleanup.plan then cleanup.apply: the plan identity, freshness and permanent-deletion confirmation belong in the App backend; mark a cleanup-apply command destructive.
 
 Connect status/ports listing can be invoke commands; connecting is accepted, not completed. Use job polling or a high-level method for completion and retain provider/exposure confirmation. Do not hide browser authorization in a supposedly successful CLI call.
 
 Only fixed generic flows are supported: invoke, bounded job start/poll/result (--wait/--no-wait), bounded offset pagination, bounded NDJSON collection, and SDK upload. SDK upload currently streams a local file once through nas.files.upload to File Station multipart; there is no generic chunk/start/finish protocol to invent. Metadata cannot specify scripts, arbitrary URLs or expressions; every step is bound to the same package's allowlisted methods and normal server permissions.
 
+## Long operations and AI polling
+
+ctl must not synchronously wait for operations that may take more than about
+30 seconds, such as scans, batch processing or large downloads. Wrap the App's
+existing asynchronous API and return its accepted ID immediately. Expose progress,
+status, result, cancellation and listing only when that API actually provides
+them. Preserve existing IDs, states,
+progress/phase/ETA, pagination and single-operation behavior. Report unavailable
+fields as unknown or record their absence in `ctl-plan`; never fabricate an ETA,
+stop method or "return existing ID" behavior. If the API already returns an active
+ID, retain it so the client can reconnect to that operation.
+
+If the only existing API is a synchronous long call, stop that command's
+implementation and report the blocker for discussion. Do not create a job layer,
+new cancellation mechanism or background worker just to expose it through ctl.
+
+Reuse the fixed `job` flow for existing compatible start/poll/result APIs. It
+waits by default: AI consumers must pass `--no-wait` for long operations, then
+call the discovered status/result commands by the returned ID. Native Apps
+already using the SDK `background` module and `bg.jobs.*` routes can map those
+existing submit/list/get/result/cancel/pause/resume capabilities. Check the
+installed SDK/template contract and enabled capability first: these routes are
+not automatic ctl commands, a generic ETA/paged-result service, or proof that
+every App supports cancellation or singleton deduplication.
+
+For AI consumers:
+
+1. Discover the real command schema and current jobs if listing is supported.
+   Dry-run mutations, obtain authorization, then submit once with `--yes` and
+   `--no-wait` when using a job flow. Keep host, App and original operation ID.
+2. Poll its existing status API using the server's retry interval; otherwise use
+   2 seconds, then 5, 10 and at most 30 seconds between polls. Do not invent a
+   polling method if the API has none. Reconnect by the same ID after a lost
+   connection; never repeat start merely because a reply was lost.
+3. Report acceptance promptly, then report meaningful phase/progress changes or
+   about every 30–60 seconds while observing. Use a bounded observation window
+   (default two minutes per turn); when it expires, return the ID, latest state
+   and exact follow-up command. Do not wait indefinitely or call a timeout a
+   failed/canceled job. A completion notification is available only if the App
+   already supplies it.
+4. On a terminal state, fetch the existing result with bounded pagination where
+   supported. Preserve partial/error states; preparation is not download or save
+   completion. If cancellation exists and is authorized, dry-run and confirm
+   before calling it; read status back until the existing API proves it stopped.
+
 For AI consumers: execute commands that describe a complete task. Do not manually concatenate hidden API methods, invent job polling, or treat accepted as completed. Let the fixed command adapter handle the declared flow and surface its timeout/partial state.
 
 ## Sensitive parameters

package/skills/reference/identity-gateway.md

@@ -42,3 +42,82 @@ Containers use a fixed package identity and do not inherit the signed-in user's
 For native Apps, retain the existing daemon, identity_gateway and account.on_delete declarations. Use fixed native argv adapters and package-private paths for deletion; the gateway never writes an upstream database. Test rename, demotion, two-user visibility, stale credentials and account deletion against the actual upstream image.
 
 Bridge readiness is availability only: declared App health + loopback TCP + the current-version SDK lifecycle acquire generation. It cannot attest actual image/project/generation: another process already executing on the NAS can occupy the port. This local-code-execution threat is accepted; restore official full readback when available. Never use root, Docker socket access or borrowed admin credentials. See compose.md.
+
+
+## Optional native-client prefixes (next minor SDK)
+
+For user-controlled mobile API or WebDAV access, declare fixed prefixes:
+
+```yaml
+identity_gateway:
+  # Add to the existing complete identity_gateway declaration.
+  sdk: 0.18.0
+  optional_passthrough:
+    mobile:
+      prefixes: [/dav, /api/mobile]
+```
+
+This unreleased capability requires the next minor SDK (0.18.0+); do not adopt
+it in an App until an approved release exists. There are at most 16 entries,
+each with 1–16 prefixes and no default-enabled option. Root, `/_sso`, encoded or
+ambiguous prefixes and overlaps with optional/permanent passthrough are invalid.
+Generated `gateway.json` carries the same declaration. Other paths still use the
+App's DSM admission policy; existing permanent passthrough stays permanent.
+
+Register the loaded SDK gateway Config's `OptionalPassthroughRoutes()` with the
+App's existing authenticated API. `gateway.passthrough.status` and
+`gateway.passthrough.set` are reserved administrator-only SDK methods. The latter
+takes only `{"id":"mobile","enabled":true}`. Show the switch only to admins and
+warn before enabling: it opens an entry without DSM sign-in, protected only by
+the App's own credentials, allowing clients to read/write authorized files.
+Mention the App account's required WebDAV/API permission. Keep native Basic Auth;
+never inject a shared admin credential. Provide a disable switch at all times.
+
+State defaults off and persists in private package `sso/passthrough-<id>.json`
+files. The SDK writes atomically then signals the same-UID gateway with SIGHUP;
+no root, port, Unix control socket or restart is needed. Disable returns 403
+before the DSM gate on the next request and reload cancels active optional
+requests. Any switch cancels streams across optional entries. Invalid state or a
+failed signal fails closed. Control responses describe configured state and a
+requested reload, not an acknowledgement. Test actual Basic Auth, streams,
+closing with a valid admin session, traversal/encoded paths and WebDAV COPY/MOVE
+Destination headers. Upstream App authentication and permissions remain the
+App's responsibility.
+
+### Native OIDC browser entry (SDK 0.18.0)
+
+An upstream with its own OIDC login can opt into a generic browser bridge:
+
+```yaml
+identity_gateway:
+  sdk: 0.18.0
+  mode: oidc
+  access: dsm-admins
+  upstream: 8000
+  listen: {https: 18443}
+  oidc:
+    issuer_port: 18090
+    clients:
+      - id: native-app
+        redirect_paths: [/auth/callback]
+    browser:
+      start: /auth/oidc?method=login
+      login_paths: [/login]
+      callback_paths: [/auth/callback]
+      completion_query: token # optional, presence only for callback on a login page
+```
+
+`start` is a fixed same-origin native SSO URI. Paths are exact, unencoded and
+outside `/_sso`. The upstream still owns all credential delivery and storage.
+The bridge starts native OIDC on document entry, resumes a bounded local deep
+link, and watches SPA history navigation to a declared login page after logout.
+It stores no upstream token/password. Storage-disabled browsers retain native
+login. Failed/expired flows do not continuously retry. HTML needs a `<head>` and
+CSP that permits the same-origin `/_sso/browser.js`; the SDK never weakens CSP.
+Downloads and non-HTML bodies are not rewritten. The gateway verifies DSM
+admission before the native callback, including an existing session for OIDC.
+A cold DSM login uses the CLI's fixed App-launch transaction resume; no supplied
+URL is accepted as the return destination. The transaction expires in five minutes.
+
+This declares navigation only; upstream account provisioning/role mapping must
+use that upstream's supported configuration APIs and be tested independently.

package/skills/reference/upstream-fork.md

@@ -6,6 +6,18 @@ Never edit upstream README, Dockerfile, source, config, workflows or ignore file
 Do not rewrite the App or treat it as an SDK component. Use `.git/info/exclude`
 for local output when needed.
 
+## Decide whether to expose AI control
+
+Ask whether the user needs AI control unless they have already explicitly requested it.
+Leave the manifest without a `ctl` block when they have not opted in; packaging an
+upstream App does not itself request ctl. If requested, follow
+[the ctl coverage checklist](ctl.md#plan-command-coverage) and produce `ctl-plan`.
+Cover common reads and writes through existing native APIs, including the main
+UI tasks; `status` and `service status` alone are incomplete. Keep upstream code
+unchanged and run adapters as the package account. Report unsupported transports
+or synchronous-only long operations for discussion; do not invent App features
+or bypass the current Compose ctl restriction.
+
 ## Container: official image and a matching source tag
 
 Use the upstream **official image**, pinned as `repository:tag@sha256:digest`.

package/skills/reference/wrap.md

@@ -1,5 +1,11 @@
 # 封裝上游 Compose
 
+Ask whether the user needs AI control. Keep `ctl` absent unless explicitly
+requested, then use [ctl-plan and the coverage checklist](ctl.md#plan-command-coverage)
+to map existing upstream UI/API operations. Compose does not support automatic
+ctl descriptions; report this blocker without adding a fake backend or inventing
+features to work around it.
+
 只使用 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