@synopackageland/cli 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.19.1 (2026-10-20)
+
+- Record SDK 0.19.1 executor and lifecycle digests for the executor fix that accepts `deadline_ms` on delegated `webapi.call`; SDK 0.19.0 digests remain. Executor Apps rebuilt with SDK 0.19.1 require one administrator reapproval after upgrading.
+- Compare upgrade approval requirements with a baseline SPK: `build --baseline` and `inspect --baseline` report root program digests, policy differences, task template changes and executor-only handoff eligibility.
+- Retain templates 0.19.0 (SDK 0.19.0) and UI 0.12.5.
+
+## 0.19.0 (2026-10-20)
+
+- Align the CLI SDK minor line and templates at 0.19.0; retain UI 0.12.5.
+- Support native DSM OIDC login without a browser bridge for compatible clients.
+- Refresh canonical executor setup fixtures and all three executor/lifecycle architecture pins for SDK 0.19.0. Rebuilt executor Apps require one administrator reapproval after upgrading.
+
 ## 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.

package/README.md

@@ -119,6 +119,19 @@ window's approval waits for it, while a status read answers `executor_starting`
 SDK's panels check again on their own. The program cannot declare `run` or `job`, and
 declaring it changes the policy digest, so an administrator approves the App again.
 
+Before releasing an executor App, compare it with the previous released SPK of
+that package and architecture. Include the resulting summary in release notes:
+
+```sh
+synopkgland build --arch x86_64 --baseline previous.spk --json
+synopkgland inspect current.spk --baseline previous.spk
+```
+
+The summary covers root program digests, permission/parameter differences, task
+template changes and executor-only handover eligibility. Without a comparable
+baseline, approval retention is unknown. Eligibility still requires live protected
+runtime and exact DSM task readback. See [the approval guide](skills/reference/approval-upgrades.md).
+
 ## Commands
 
 | Command | Purpose |

package/dist/cli.js

@@ -33,6 +33,7 @@ import { buildNativeLayout, isNativeLayout, loadNativeLayout, LAYOUT_ARCHES, } f
 import { buildStandalone, runnerFor } from "./standalone/build.js";
 import { checkJobs, commitOutputs, forEachArch, } from "./standalone/arch-jobs.js";
 import { checkReproducible } from "./reproducible.js";
+import { spkApprovalDiff, formatApprovalDiff } from "./runtime/approval-diff.js";
 import { inspectAnySpk } from "./spk/inspect.js";
 function failure(code, message, hint = "Fix the configuration and retry; use --help to see command usage.") {
     return Object.assign(new Error(codedMessage(code, message)), { code, hint });
@@ -389,16 +390,18 @@ export async function runCli(argv) {
     });
     program
         .command("inspect <spk>")
+        .option("--baseline <spk>", "Compare approval requirements with the previous SPK")
         .description("Inspect any SPK against the DSM 7 package format without installing; for a synopkgland-built SPK also check the build contract and root privilege requirements")
         .option("--json", "Print a single JSON object")
-        .action(async (input) => {
+        .action(async (input, options) => {
         const spk = resolve(input);
         if (existsSync(spk) && statSync(spk).isDirectory())
             throw failure("SPK_INSPECTION_FAILED", `${spk} is a directory; inspect checks .spk files.`, "Use synopkgland check to inspect project settings.");
         const report = await inspectAnySpk(spk);
         if (!report.dsm.ok || report.findings.length)
             throw Object.assign(failure("SPK_INSPECTION_FAILED", formatSpkChecks(report).join("\n"), "Fix the SPK by error code and repackage; see reference/errors for the codes; do not install an SPK that fails inspection."), { report: { spk, ...report } });
-        emit("inspect", { spk, ...report }, formatSpkReport(spk, report));
+        const approval = await spkApprovalDiff(spk, options.baseline && resolve(options.baseline), report);
+        emit("inspect", { spk, ...report, approval }, formatSpkReport(spk, report) + "\n" + formatApprovalDiff(approval));
     });
     const images = program.command("images").description("Container image tools");
     images
@@ -624,6 +627,7 @@ export async function runCli(argv) {
     skill.command("show <id>").action((id) => stdout(readSkill(id)));
     program
         .command("build")
+        .option("--baseline <spk>", "Compare approval requirements with the previous SPK (one matching architecture)")
         .description("Build an SPK from synology-app.yaml or dsm-package.yaml")
         .option("--json", "Print a single JSON object")
         .option("-o, --output <path>", "Output SPK; use with a single --arch")
@@ -684,13 +688,15 @@ export async function runCli(argv) {
                         outDir: undefined,
                     }),
             });
+        const approval = await Promise.all(outputs.map(async (output) => ({ output, ...await spkApprovalDiff(output, options.baseline && resolve(options.baseline)) })));
         const lines = [
+            ...approval.map(item => item.output + "\n" + formatApprovalDiff(item)),
             ...outputs.map((output) => `Built ${output}`),
             ...(reproducible ? reproducibleLines(reproducible) : []),
         ];
         if (reproducible && !reproducible.identical)
             throw Object.assign(failure("BUILD_NOT_REPRODUCIBLE", lines.join("\n"), "Find the payload files that differ between builds (timestamps, random paths, unpinned dependencies) and retry after fixing them."), { report: { outputs, reproducible } });
-        emit("build", { outputs, ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
+        emit("build", { outputs, approval, ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
     });
     if (json)
         console.log = (...args) => console.error(...args);

package/dist/error-registry.js

@@ -11,6 +11,7 @@ export const ERROR_REGISTRY = {
     CTL_DESCRIBE_FAILED: { "code": "CTL_DESCRIBE_FAILED", "description": "The backend registry export failed.", "suggestion": "Check the backend --describe output and build diagnostics." },
     CTL_COMMAND_UNREGISTERED: { "code": "CTL_COMMAND_UNREGISTERED", "description": "A command references an unregistered backend method.", "suggestion": "Correct ctl.commands bindings or register the backend method." },
     CTL_DESCRIPTOR_INVALID: { "code": "CTL_DESCRIPTOR_INVALID", "description": "The generated API description violates the public contract.", "suggestion": "Correct ctl.commands and rebuild the private synopkgland-api.json." },
+    APPROVAL_BASELINE_INVALID: { code: "APPROVAL_BASELINE_INVALID", description: "The --baseline SPK failed inspection, so approval retention cannot be compared.", suggestion: "Pass the previous released SPK of the same package and architecture, unmodified; inspect it to see each finding." },
     CTL_DECLARATION_INVALID: { "code": "CTL_DECLARATION_INVALID", "description": "The ctl declaration is invalid.", "suggestion": "Check ctl.enabled, aliases and explicit commands in dsm-package.yaml." },
     ...{
         LAUNCHER_PORTAL_MISMATCH: {

package/dist/runtime/approval-diff.d.ts

@@ -0,0 +1,37 @@
+import type { ExecutorPolicy } from './executor-policy.js';
+import { type SpkReport } from '../spk/inspect.js';
+export interface ApprovalInventory {
+    package: string;
+    arch: string;
+    executorDigest: string;
+    policyDigest: string;
+    anchored: boolean;
+    policy: ExecutorPolicy;
+    tasks: Array<{
+        kind: string;
+        name: string;
+        script: string;
+    }>;
+}
+export interface ApprovalDifference {
+    retention: 'unknown' | 'eligible' | 'required';
+    permissions: 'unknown' | 'unchanged' | 'expanded' | 'review-required';
+    executor_only: boolean;
+    task_template_changed: boolean | null;
+    old_policy_digest?: string;
+    new_policy_digest?: string;
+    root_programs: Array<{
+        name: string;
+        old: string | null;
+        new: string | null;
+    }>;
+    policy_changes: Array<{
+        path: string;
+        old: unknown;
+        new: unknown;
+    }>;
+    reason: string;
+}
+export declare function approvalDiff(old: ApprovalInventory | undefined, next: ApprovalInventory | undefined): ApprovalDifference;
+export declare function spkApprovalDiff(current: string, baseline?: string, report?: SpkReport): Promise<ApprovalDifference>;
+export declare function formatApprovalDiff(d: ApprovalDifference): string;

package/dist/runtime/approval-diff.js

@@ -0,0 +1,56 @@
+import { inspectAnySpk } from '../spk/inspect.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => JSON.stringify(k) + ':' + canonical(v)).join(',') + '}';
+    return JSON.stringify(value) ?? 'null';
+}
+function authority(policy) {
+    const p = structuredClone(policy);
+    p.root = Object.fromEntries(Object.entries(policy.root).map(([name, entry]) => [name, typeof entry === 'string' ? {} : Object.fromEntries(Object.entries(entry).filter(([key]) => key !== 'digest'))]));
+    return p;
+}
+function changes(a, b, path = '', out = []) {
+    if (canonical(a) === canonical(b))
+        return out;
+    if (a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+        for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort())
+            changes(a[key], b[key], path + '/' + key.replaceAll('~', '~0').replaceAll('/', '~1'), out);
+    }
+    else
+        out.push({ path, old: a ?? null, new: b ?? null });
+    return out;
+}
+const rootDigests = (p) => Object.fromEntries(Object.entries(p.root).map(([name, e]) => [name, typeof e === 'string' ? e : e.digest]));
+export function approvalDiff(old, next) {
+    const unknown = { retention: 'unknown', permissions: 'unknown', executor_only: false, task_template_changed: null, root_programs: [], policy_changes: [], reason: 'Cannot determine whether approval can be retained: a valid, matching baseline SPK and executor inventory are required.' };
+    if (!old || !next || old.package !== next.package || old.arch !== next.arch)
+        return unknown;
+    const a = rootDigests(old.policy), b = rootDigests(next.policy);
+    const root_programs = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort().filter(name => a[name] !== b[name]).map(name => ({ name, old: a[name] ?? null, new: b[name] ?? null }));
+    const policy_changes = changes(authority(old.policy), authority(next.policy));
+    const expanded = next.policy.operations.some(op => !old.policy.operations.includes(op)) || Object.keys(next.policy.root).some(name => !(name in old.policy.root));
+    const templates = (i) => i.tasks.map(t => ({ kind: t.kind, name: t.name, script: t.script.replaceAll(i.policyDigest, '@POLICY_DIGEST@') })).sort((a, b) => a.kind < b.kind ? -1 : 1);
+    const task_template_changed = canonical(templates(old)) !== canonical(templates(next));
+    const eligible = old.policyDigest === next.policyDigest && !task_template_changed && (old.executorDigest === next.executorDigest || next.anchored);
+    return { retention: eligible ? 'eligible' : 'required', permissions: expanded ? 'expanded' : policy_changes.length ? 'review-required' : 'unchanged', executor_only: eligible && old.executorDigest !== next.executorDigest, task_template_changed, old_policy_digest: old.policyDigest, new_policy_digest: next.policyDigest, root_programs, policy_changes, reason: eligible ? 'Approval can be retained if the installed protected runtime and exact DSM task readback still match this baseline.' : 'Administrator reapproval is required for the changed payload, policy, executor anchor or task definitions.' };
+}
+function inventory(r) {
+    if (!r.dsm.ok || r.findings.length || !r.executor || !r.package || !r.arch)
+        return;
+    return { package: r.package, arch: r.arch, ...r.executor, anchored: true }; // inspect verifies the INFO anchor and every root payload digest.
+}
+export async function spkApprovalDiff(current, baseline, report) {
+    if (!baseline)
+        return approvalDiff(undefined, undefined);
+    const next = inventory(report ?? await inspectAnySpk(current));
+    const old = await inspectAnySpk(baseline);
+    if (!old.dsm.ok || old.findings.length)
+        throw new Error('[APPROVAL_BASELINE_INVALID] Baseline SPK failed inspection: ' + [...old.findings, ...old.dsm.errors.map(e => e.message)].join('; '));
+    return approvalDiff(inventory(old), next);
+}
+export function formatApprovalDiff(d) {
+    const short = (s) => s?.slice(0, 12) ?? '—';
+    return ['Approval: ' + d.reason, 'Permissions: ' + d.permissions, ...d.root_programs.map(p => `Root program ${p.name}: ${short(p.old)} → ${short(p.new)}`), ...d.policy_changes.map(c => `Policy ${c.path}: ${JSON.stringify(c.old)} → ${JSON.stringify(c.new)}`), `Task template: ${d.task_template_changed === null ? 'unknown' : d.task_template_changed ? 'changed' : 'unchanged'}`, `Executor-only handover: ${d.executor_only ? 'eligible under the INFO anchor' : 'not established'}`].join('\n');
+}

package/dist/runtime/executor-digests.json

@@ -1,8 +1,19 @@
 {
-    "0.18.0": {
-        "x86_64": "6d9d5a12ac4c990639b31c555560a1b6e49cbe1c267c626a23b91833dcc4452e",
-        "aarch64": "efbed582ce1249fed09de72b7bbe553510a55553e44ccf76fa93c684864e8bb8",
-        "armv7": "670f83c3349497263c96b0244ec142153c094d5e223dae091c9c8614c0ea04b6",
+    "0.19.0": {
+        "x86_64": "3b23252a4d2ad188e8920aee3c022d054a85f31797dfb9f34a576449f8b08f41",
+        "aarch64": "024a8a01977324645b475330371afb8b8c8387eac6a11ec3d9d30a4a0e445174",
+        "armv7": "fae3266f65863815f1417332a3c73d12507941029077e0ddc118da8461e8cff3",
+        "lifecycle": {
+            "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972",
+            "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb",
+            "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
+        },
+        "goToolchain": "go1.26.9"
+    },
+    "0.19.1": {
+        "x86_64": "e27cfeb85fed221b06f9c58166f02c0f701a724308cd17c96a43a843a0b5c4aa",
+        "aarch64": "908db00cbd37d072f6ffc339e7bca24da5efb8cddd4befcbad02c7398beb7191",
+        "armv7": "a0f35d62ec80a1bf3fb49f5e2d1a5f7576eda569a6fd0695084cec6cb8e100bc",
         "lifecycle": {
             "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972",
             "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb",

package/dist/standalone/dsm-window.js

@@ -379,7 +379,7 @@ ${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"))};` : ""}
+${(manifest.identityGateway?.oidc?.native_login || 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.
@@ -408,7 +408,7 @@ Ext.define(${JSON.stringify(`${ns}.MainWindow`)}, {
   },
   onOpen: function (param) {
     this.callParent(arguments);
-    ${manifest.identityGateway?.oidc?.browser ? `if (${ns}.resumeOIDC(param)) return;` : ""}
+    ${(manifest.identityGateway?.oidc?.native_login || manifest.identityGateway?.oidc?.browser) ? `if (${ns}.resumeOIDC(param)) return;` : ""}
     var me = this;
     if (me.mounted) {
       me.reopenEvents.emit();
@@ -471,7 +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;` : ""}
+    ${(manifest.identityGateway?.oidc?.native_login || 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

@@ -55,6 +55,7 @@ export interface IdentityGateway {
     roles?: GatewayRoles;
     headers?: Partial<Record<"user" | "email" | "name" | "groups" | "uid", string>>;
     oidc?: {
+        native_login?: boolean;
         issuer_port: number;
         browser?: GatewayBrowser;
         clients: GatewayClient[];

package/dist/standalone/identity-gateway.js

@@ -270,7 +270,8 @@ 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", "browser"]) ||
+            !only(o, ["issuer_port", "clients", "rewrite_json", "browser", "native_login"]) ||
+            (o.native_login !== undefined && typeof o.native_login !== "boolean") ||
             !port(o.issuer_port) ||
             !Array.isArray(o.clients) ||
             !o.clients.length ||
@@ -312,6 +313,7 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
                 return invalid("oidc.browser needs fixed local start, login_paths and callback_paths outside /_sso.");
         }
         gateway.oidc = {
+            ...(o.native_login !== undefined ? { native_login: o.native_login } : {}),
             issuer_port: o.issuer_port,
             ...(b !== undefined ? { browser: b } : {}),
             clients: clients,

package/dist/standalone/oidc-resume.js

@@ -1,6 +1,18 @@
 /** No caller-provided URL reaches location: only a transaction and a declared port. */
 export function oidcResumeRuntime(pkg, ports) {
     return `(function(param) {
+  if (typeof param === 'string') {
+    if (param.length > 512) return false;
+    try { param = JSON.parse(param); }
+    catch (_) {
+      try {
+        var query = new URLSearchParams(param);
+        if (Array.from(query.keys()).length !== 1 || query.getAll('ssoResume').length !== 1) return false;
+        param = {ssoResume:query.get('ssoResume')};
+      } catch (_) { return false; }
+    }
+  }
+  if (!param || typeof param !== 'object' || Array.isArray(param)) return false;
   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);

package/dist/standalone/root-window.js

@@ -359,9 +359,14 @@ export const ROOT_RUNTIME = `function createRootAccess(options) {
   // here, and that first status serves the health check. Approval and
   // control read back on their own.
   function checked(status) { return pinned(status) && !!status.tasks && status.tasks.state === "ready"; }
+  function approvalExplanation(verified, status) {
+    var diff = status && status.approval;
+    if (verified.state === "needs-admin-approval" && diff && options.pins && diff.package === options.pins.package && diff.new_policy_digest === options.pins.policyDigest && diff.new_executor_digest === options.pins.executorDigest && (diff.old_policy_digest !== diff.new_policy_digest || diff.task_template_changed)) verified.approval = diff;
+    return verified;
+  }
   function adminStatus() {
     var asked = options.call("executor.status", {});
-    function verify() { return read().then(function (verified) { return health(verified, 0, asked); }); }
+    function verify() { return read().then(function (verified) { return health(verified, 0, asked); }).then(function (verified) { return asked.then(function (status) { return approvalExplanation(verified, status); }, function () { return verified; }); }); }
     return asked.then(function (status) {
       return checked(status) ? {state: "ready", tasks: {boot: {state: "ready"}, control: {state: "ready"}}, executor: status} : verify();
     }, verify);

package/package.json

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

package/skills/SKILL.md

@@ -5,6 +5,8 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
+Before releasing an executor App, read [reference/approval-upgrades.md](reference/approval-upgrades.md). Run build/inspect with the previous released SPK as `--baseline` and include the approval difference in release notes. Without a comparable baseline, retention is unknown.
+
 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.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.

package/skills/reference/approval-upgrades.md

@@ -0,0 +1,36 @@
+# Approval changes before release
+
+Run the current CLI against the previous released SPK for the same package and
+architecture before releasing an executor App:
+
+```sh
+synopkgland build --arch x86_64 --baseline previous-x86_64.spk --json
+synopkgland inspect current-x86_64.spk --baseline previous-x86_64.spk
+synopkgland inspect current-x86_64.spk --baseline previous-x86_64.spk --json
+```
+
+`inspect` returns `data.approval`; `build` returns one entry per output in
+`data.approval`. Put the human summary in release notes. Optionally copy that
+same summary into the manifest's `metadata.changelog`, which the existing build writes to INFO for Package Center.
+Do not assume DSM automatically opens an App after upgrading it.
+
+The summary names root programs and their old/new SHA-256 prefixes, policy
+permission/parameter paths, and task template changes. Task template comparison
+removes only the policy pin; a policy pin change still requires approval.
+`unchanged` means the policy excluding root digests is identical. Added root
+programs or operations are `expanded`; other permission/parameter changes are
+`review-required`, because arbitrary schema and scope changes cannot generally
+be proven to narrow permissions. Program bytes can change behavior even when
+the declared policy is unchanged.
+
+`eligible` is conditional: the live protected runtime must still match the
+baseline and DSM must read back the exact approved tasks. An executor-only
+handover additionally needs the new executor's valid INFO anchor. This offline
+summary does not grant approval. With no baseline, an incompatible package or
+architecture, or no executor inventory, retention is `unknown`; never promise
+that approval will be retained. Invalid baselines fail inspection.
+
+The SDK approval screen reads root-produced diagnostics through executor.status,
+then uses the existing PasswordConfirm and exact task readback. Older protected
+runtimes without diagnostic support show an explicit unknown explanation. No App
+option supplies an approved baseline or permission claim.

package/skills/reference/identity-gateway.md

@@ -121,3 +121,14 @@ URL is accepted as the return destination. The transaction expires in five minut
 
 This declares navigation only; upstream account provisioning/role mapping must
 use that upstream's supported configuration APIs and be tested independently.
+
+## Server-managed OIDC navigation (development)
+
+For an upstream that automatically starts OIDC (for example a native web-server
+authentication module), leave `oidc.browser` unset and declare
+`oidc.native_login: true`. This reuses native DSM cold-login/resume without
+injecting an HTML/SPA bridge into the upstream. It requires the matching SDK
+capability; released SDK 0.18.0 does not yet implement this field. Native Compose
+URL entries resume only a bounded transaction and declared public gateway port.
+Normal menu entry remains the classless SDK CGI. Existing browser consumers keep
+their previous behavior. Never invent fake login paths just to enable DSM login.