@synopackageland/cli 0.14.1 → 0.15.0

package/skills/reference/compose.md

@@ -0,0 +1,349 @@
+# Upstream Compose packages
+
+The CLI converts schema-2 declarations to an SPK. The SDK owns Compose planning,
+identity gateway and lifecycle control. There is no separate wrapper container
+or SSO Server. Upstream files stay byte-for-byte unchanged, including comments.
+
+```yaml
+schema: 2
+package: MediaApp
+version: 0.1.0
+build: 1
+displayname: Media App
+description: Upstream application
+maintainer: Example
+os_min_ver: "7.2.1-69057"
+arches: [x86_64, aarch64]
+capabilities: {}
+compose:
+  files: [compose.yaml, site.yaml]
+  env_files: [.env]
+  profiles: []
+  web: {service: web, port: 8080, health: {path: /health, status: 200}}
+  network: {egress: isolated}
+  # Private package binds are rejected by DSM build; keep compatible upstream named volumes.
+identity_gateway:
+  sdk: 0.15.0
+  mode: none
+  access: dsm-users
+  listen: {http: 28000}
+ui: {launch: new-page}
+```
+
+No backend, dummy CGI, UI directory or helper payload is required. Omit `web`
+and `identity_gateway` for headless projects. Optional `compose.helpers` names
+architecture-specific native payloads for token/account adapters. All lifecycle
+scripts run as the package account; containers are managed by Container Manager.
+
+## Planning and artifacts
+
+The pinned compose-go reference loader merges ordered files, env files and
+profiles. Process environment never supplies interpolation values. Local include,
+extends, env_file and label_file dependencies are bounded, confined and copied
+without symlinks. Remote/interpolated dependencies are rejected. CLI import uses
+the SDK inventory, not a second parser for dependency semantics.
+
+`compose/upstream/` preserves input bytes. `generated.override.yaml` is a real
+reference-loader replacement override: lists such as ports and mounts use
+`!override` so original wildcard publications cannot survive list merging.
+`docker-compose.yml` is the final tag-free worker document. `compose.lock.json`
+records input/effective hashes, image/platform inventory, fixed identities,
+mounts, networking and explicit acceptance blockers. `images.json` contains the
+registry manifests/config bytes needed for offline image-volume verification.
+Inspection replays the trusted SDK planner over the packaged inputs and compares
+actual effective, override, lock, launcher, gateway, resources and lifecycle.
+
+Build resolves anonymous registry metadata and pins the Linux platform manifest.
+It verifies pinned upstream index/manifest digests and image config hashes, and
+turns image-declared anonymous VOLUMEs into stable package-namespaced volumes.
+Private registry credentials are not inherited. `SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS`
+is an explicit build-host JSON map of registry names to HTTPS origins; it changes
+metadata transport only, never the repository or runtime reference. Mirrors are
+a build operator trust decision. `check`/`inspect` remain offline.
+
+## Support boundary
+
+| Feature | Current behavior |
+| --- | --- |
+| Files in one directory, profiles, anchors, depends_on, healthcheck | Reference-loader semantics retained; DSM worker compatibility needs device acceptance |
+| Named local volumes | Stable package namespace, retained across recreation; inspect inventory |
+| Private bind data | DSM build rejects COMPOSE_PRIVATE_BIND_TIMING_UNSUPPORTED: clean-install preinst precedes pkgvar creation, while worker acquire precedes postinst; no root initialization or automatic volume conversion |
+| Image VOLUME | Build inventories verified image config and assigns a stable named volume |
+| Existing external volume | Rejected without trusted admin ownership/driver readback |
+| Existing Shared Folder | Explicit opt-in intent only; blocked settings page until official protected ACL/project control exists |
+| Bridge | Default no-publish dedicated internal bridge with a package-derived fixed IP; availability requires App health, TCP and the current lifecycle acquire record; no Docker identity attestation |
+| Host | Explicit verified OIDC web consumer with address_env forced to 127.0.0.1; no container-root; internet access is visible |
+| Egress | isolated internal networks, or explicit internet outbound bridge; fine allowlist declarations fail |
+| Public ports | All upstream publishes removed; the host gateway dials the declared web service on its fixed bridge IP; auxiliary ingress is unsupported |
+| Root | Fixed package UID/GID by default; per-service container-root requires reason, bridge and no host binds; only CHOWN/FOWNER/SETUID/SETGID opt-ins |
+| Build, hooks, privileged, host PID/IPC, devices, sockets | Rejected; no host root workaround |
+| Secret/config file resources, plugins, replicas/deploy | Rejected until their bounded delivery/runtime contract exists |
+| Subpath hosting | Unsupported; use the app's dedicated origin at / |
+
+Container-root is distinct from host elevation. Named-volume ownership and an
+image's arbitrary-UID compatibility are not proved by a valid plan. Test the
+actual immutable image, initialization, health, UID/capabilities and restart.
+Unknown compatibility is never a certification result.
+
+## Shared Folder authority
+
+Containers use a fixed package identity. **They do not inherit the signed-in
+user's File Station ACL.** App library/share settings control which app users
+see mounted data. Read-only prevents source changes; read/write can permit file
+modification and deletion. DSM identity/account bridge and file authority are
+separate features. Per-DSM-user filesystem access requires a File Station session
+or Broker Adapter; it is outside this change and cannot be obtained through a mount.
+
+Declare `capabilities: {composeMounts: true}` and, for example:
+
+```yaml
+compose:
+  shares:
+    media:
+      select: admin-after-install
+      permission: ro
+      mounts: [{service: web, target: /media}]
+```
+
+Selection is after installation by an administrator in the App, not a claim
+that the installation wizard can enumerate existing Shares. `install-draft`
+is only a draft intent. Until authorization, only SDK settings start and no
+upstream docker-project is acquired. The independent authority purpose is
+`compose-mount`; a user destination grant from Download Hub/delegate never
+permits a package-wide mount.
+
+The current implementation does **not** issue a mount grant, invoke ACL tools,
+install a protected executor for Compose, or activate/revoke an upstream project.
+Confirmation returns `COMPOSE_PROJECT_CONTROL_UNAVAILABLE`. It must remain
+unsupported until an official ACL plus fixed project-control adapter can use
+protected policy/digest/generation authority, stop/recreate/read back and revoke
+without reviving stale grants. No app runs as host root to bypass this boundary.
+
+## Gateway transport
+
+`none` keeps native app login; `header`, `token` and embedded `oidc` use supported
+upstream interfaces plus the DSM account bridge. Access defaults to dsm-users;
+admins/groups revalidate NSS membership per request. Public access is explicit
+and only valid with none. Reserved DSM id/did and this gateway's cookies are
+filtered in both directions; other Cookie order/duplicates and Set-Cookie
+attributes are preserved. Claimed identity and DSM token headers are stripped.
+
+Upstream POST does not require SynoToken. Browser mutations and WebSocket upgrades
+require exact scheme/host/port Origin, or Referer when Origin is absent, plus
+SameSite gateway cookies. Missing/null/foreign/duplicate origin fails. Explicit
+app-authenticated passthrough can serve native clients without browser headers;
+when browser evidence is present it is still checked. No identity is injected
+into passthrough. SynoToken remains required at DSM's own authorization CGI.
+
+WebSocket frames, SSE flush, streamed uploads, Range/HEAD downloads and redirects
+have transport tests. Uploads default to 16 GiB; max_upload_bytes can reduce it.
+Known oversize bodies are rejected before proxying; streamed oversize errors
+return 413. Dial, TLS and response-header deadlines are separate; there is no
+whole-response streaming timeout. Exact upstream absolute redirects change
+origin while retaining encoded path, query and fragment; unrelated IdP URLs and
+relative redirects keep their semantics. No HTML/JS body regex rewriting.
+
+## Device acceptance remains required
+
+A Linux gate is not DSM proof. Confirm final SPK digest and DSM/Container Manager
+versions, worker interpolation/model semantics, storage ownership timing,
+declared availability readiness, LAN isolation/egress, protected grant lifecycle, encrypted Share
+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 requires SDK, CLI and templates 0.15.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.
+
+## DSM bridge availability readiness
+
+Declare `compose.web.health: {path: /health, status: 200}` using the App's real
+unauthenticated health endpoint (an origin-relative path and expected 2xx status).
+The SDK follows no redirects, uses no proxy/cookies/DSM credentials, and bounds
+TCP/HTTP timeouts. All three conditions are required before gateway admission:
+
+1. The declared App health endpoint returns the expected status.
+2. The planner-derived fixed bridge IP and container port accept a TCP connection.
+3. A private, durably written `pkgvar/daemon/compose-acquire.json` records an active
+   lifecycle acquire generation, the current installed SPK version and plan digest.
+
+DSM's startup worker returns before the generated start hook records acquire.
+Stop/upgrade/uninstall durably release it before stopping the gateway; a new
+start records a fresh generation. Missing, released, foreign or stale state
+fails closed. This is the package lifecycle's record, not DSM runtime readback.
+
+**Limitation:** these checks cannot prove that the Docker image, project or
+generation actually running is the declared one. The threat is another local
+process occupying the same port and answering health. This is accepted because
+that process must already have code execution on the NAS. Do not use readiness
+as an identity or isolation attestation. Restore full authoritative verification
+when an official package-account readback channel becomes available. Never grant
+Docker socket access, borrow an admin session or use root for readiness.
+
+`inspect` reports `compose.readiness.profile` and this limitation. The old
+bridge-unverified admission blocker is replaced by `COMPOSE_READINESS_INVALID`,
+`COMPOSE_ACQUIRE_GENERATION_INVALID`, `COMPOSE_TCP_NOT_READY` and
+`COMPOSE_HEALTH_NOT_READY`, according to the actual failing condition.
+
+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
+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.
+
+Bridge web ingress uses a dedicated `sdk_ingress` internal bridge. The web service
+receives a fixed IPv4 address, and the package-account gateway connects directly
+to its declared container port. Internal bridges were reachable by package-account
+hooks in the sa3200d and vt-nas feasibility probes. No HAProxy helper, published
+container port, Docker socket or host root is required. Explicit internet egress
+still adds the existing outbound bridge; other App services retain their internal networks.
+
+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
+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
+installation; automatic migration of an installed network is not provided. The exact previous package allocation can be
+reused through a private `pkgvar/compose-ingress.json` allocation record written
+in postinst. Preinst reads DSM7's physical `<SYNOPKG_PKGDEST_VOL>/@appdata/<id>`
+when `SYNOPKG_PKGVAR` is absent: DSM removes both the old payload and
+`/var/packages/<id>/var` before replacement;
+it does not attest Docker ownership. Missing or invalid history never exempts a
+conflicting route. Container Manager's atomic IPAM check remains the final arbiter for
+concurrent acquisition and networks without a visible host route; the preparer
+does not claim a complete Docker network inventory or network ownership attestation.
+Unavailable kernel inventory fails with `COMPOSE_SUBNET_INVENTORY_UNAVAILABLE`.
+
+`inspect` inventories the address, subnet, service, port and candidate. The gateway
+accepts only its package-derived bridge address; arbitrary private-network URLs,
+DNS targets and user-supplied credentials/query strings are not ingress endpoints.
+The readiness profile is `health-fixed-ip-lifecycle` and retains the existing
+availability-only limitation. Host-network OIDC remains a separate explicit opt-in.
+
+Bridge publish mode has been removed. Existing `web.host_port` declarations are
+accepted for compatibility and ignored by bridge transport; new scaffolds omit it.
+Legacy `.sc` residue is not purged by this topology. Migrating an already published
+installation requires a separately authorized cleanup or an official worker fix;
+a no-publish rebuild cannot claim to remove historical service registrations.
+
+On vt-nas DSM 7.4/Docker 24.0.2, internal networks blocked tested external IPv4
+and external DNS, but allowed NAS host services through the bridge gateway and
+NAS LAN address. Therefore `isolated` is not a host-service firewall. IPv6 had
+no usable default route on this fixture, which is not proof of an IPv6 firewall.
+The official worker added NET_BIND_SERVICE to the capability bounding set even
+with cap_drop ALL; effective/permitted/ambient capabilities were zero for the
+nonroot fixture. Do not claim an empty bounding set or complete NAS isolation.
+
+DSM cookie names `id`, `did`, `_SSID`, `_CrPoSt`, `stay_login` and the complete
+`synopkgland_sso_` namespace are reserved in both request Cookie and response
+Set-Cookie. Other App sessions/native cookies retain their normal semantics.
+Cookies are shared across ports on the same hostname, so filtering only this
+package's SDK cookie would leak another App's SDK session to an upstream.
+
+Historical publish-topology vt-nas validation was release-blocked: the Container Manager
+24.0.2-1706 docker-project worker can return profile error 1202 on update,
+which Package Center reports as postinst-worker failure 277. The owned test
+project and a real Vaultwarden package reproduced this; switching Compose
+publish syntax did not resolve it. No root App, firewall edit or Container
+Manager modification is used as a workaround. Validate acquisition, upgrade
+and uninstall on a working official worker before claiming DSM support.
+
+### Diagnose official worker failures without changing the NAS
+
+Package Center's postinst-worker error is a wrapper. Read only the failed
+package's worker messages and the matching timestamp/PID in DSM logs, removing
+session, token, cookie and password fields before displaying or saving output.
+Distinguish these observed failure chains:
+
+| Worker result | Matching lower-level evidence | Interpretation |
+| --- | --- | --- |
+| Profile 1202, Package Center 277 | `service_conf_section_set.c:92 Port conflict with existing ports` followed by `profile.cpp:118 Fail to create port section` | Official service-port registration rejected a conflict; malformed Compose syntax is not established by these codes |
+| Compose-up 2201, Package Center 276 | Registry request fails with `x509: certificate signed by unknown authority` | The Docker daemon could not fetch an image; gateway authentication and readiness have not been tested yet |
+
+For the first chain, `servicetool --conf-port-conflict-check --tcp PORT` and
+`servicetool --runtime-port-conflict-check --tcp PORT` are read-only checks.
+Read the matching lower-level error even for wrapper 276: a follow-up failed
+reinstall returned 276 with profile 1202, rather than a registry failure.
+Record the reported service/process owner. A clean readback after uninstall
+does not identify the conflict that existed during the failed operation.
+Do not remove service profiles, disable firewall checks, bypass the official
+worker, change ports automatically or restart Container Manager to turn the
+failure into a pass.
+
+Container Manager's status script also requires `synosystemctl` on PATH. A
+status failure from a restricted SSH environment alone does not prove daemon
+failure; correlate the script's actual error, service-unit state and Docker
+server response. Keep administrative diagnostics separate from the App, which
+continues to run as its package account without Docker socket access.
+
+An additional DSM 7.3.2 / Container Manager 24.0.2-1606 fixture passed Header
+and Vaultwarden install/start/upgrade. This does not certify the failing DSM
+7.4 / 24.0.2-1706 environment. Its explicit test configuration used immutable
+mirror image references and declared internet egress for the web service; it
+does not extend the isolated-ingress or original-registry support evidence.
+The same Header SPK also passed install/start/upgrade on a second DSM 7.4 /
+24.0.2-1706 device. The original failure therefore cannot be classified as
+affecting every device with that Container Manager version.
+
+Official uninstall on both additional fixtures removed the packages, projects,
+containers and networks but left their `docker_<container>.sc` service-port
+profiles. Read-only configuration checks still reported those ports as reserved
+after the containers were gone. This is a separate cleanup acceptance failure;
+successful upgrade/reinstall does not clear it. The retained profiles are a
+possible source of later port conflicts, not proof of the original conflict's
+owner. Do not add a root App hook or delete DSM service configuration as a
+workaround; record the owned profiles and resolve the official worker cleanup
+contract before claiming complete uninstall support.
+
+### Official port-profile cleanup boundary
+
+Follow-up tests isolated the uninstall defect from SDK-generated ingress. Minimal
+packages containing only the official docker-project resource, package-account
+hooks and a non-root Node container reproduced retained port reservations with
+all three forms: long loopback publish, short loopback publish and wildcard
+publish. Distinct project names and distinct ports allowed two Apps to run
+concurrently, but did not make their uninstall clean. A no-publish control did
+not create a port-profile `.sc`. Changing syntax or exposing the port to the LAN
+is therefore not a validated cleanup fix.
+
+Read-only inspection of Container Manager 24.0.2-1606 and 1706 found that
+Project.Clean calls Compose.Down before RemoveProfileForAllContainers; that
+cleanup method obtains IDs through Compose.Ps `-qa`. Once Down has removed the
+containers, that lookup can produce no profiles to unregister. The observed
+files were created during install acquisition, before the package was started.
+This supports an official worker cleanup defect; it does not establish the
+exact internal conflict owner or race during a separate failed upgrade.
+
+The documented [port-config worker](https://help.synology.com/developer-guide/resource_acquisition/port_config.html)
+was also tested. Even when its protocol-file basename and section matched the
+CM file, DSM registered it as `<package>.sc`. Container Manager separately
+registered `docker_<container>.sc`; releasing port-config removed only the
+package registration. Declaring that resource did not solve the CM residue.
+The [docker-project contract](https://help.synology.com/developer-guide/resource_acquisition/docker-project.html)
+documents project deletion on PREUNINST and build flags, without a separate
+package-account profile-release option.
+
+The original isolated Header fixture on vt-nas installed and started from a
+clean configuration, then its upgrade still returned port conflict → 1202 →
+277. Historical `.sc` residue alone is therefore insufficient to explain or
+resolve that environment's upgrade failure. Preserve the timestamp/PID chain;
+do not report a clean post-uninstall check as proof that upgrade was fixed.
+
+The publish topology did not pass the complete lifecycle. The no-publish
+implementation above requires its own final-SPK install/upgrade/reinstall/uninstall
+and two-App acceptance before release. An administrator may separately authorize exact
+owned-profile cleanup through official servicetool, with pre-removal hashes and
+file/config readback; this is fixture recovery, never an App hook or a supported
+rootless package cleanup mechanism.
+
+A native package-account listener remains another rootless option. The new
+no-publish bridge topology above implements the separately authorized ingress design. Existing host-network OIDC support requires a
+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.

package/skills/reference/create.md

@@ -1,6 +1,6 @@
 # 建立（Create）
 
-先選擇 `native-go`（Go CGI + DSM 視窗）、`native-python`／`native-node`／`native-rust`（同一個 App，backend 換成 Python、Node.js（TypeScript）或 Rust）、`binary`（預建服務程式）或 `compose`（上游容器）。`compose` 預設示範 Share 與固定 run-as 使用者，`--from <compose.yaml>` 匯入現有 Compose。
+先選擇 `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
 synopkgland init -t native-go --with files,jobs,login --package MyApp my-app
@@ -17,7 +17,8 @@ synopkgland init -t compose --from ./compose.yaml upstream-app
 
 ## 容器存取控制
 
-有 adminport 的容器 App 預設經 DSM 驗證 gateway（`integration.web.access`：dsm-users 預設、dsm-admins、dsm-groups＋groups、public）。Compose published port 必須綁 loopback：`127.0.0.1:<adminport>:<port>`，否則 check 失敗（`COMPOSE_GATEWAY_PORT_EXPOSED`）。gateway 是編譯的 Go，建置需要 Go 與 `--arch`。`public` 才保留匿名 Web Station portal，inspect 會以 `CONTAINER_ANONYMOUS_PORTAL` 提醒。Compose App 沒有 executor，不能宣告 `integration.web.portal`（`CONTRACT_PORTAL_REQUIRES_EXECUTOR`）。
+Compose 只使用 schema-2 `dsm-package.yaml`，上游原樣保留，SDK planner 產生 override 與 worker 單檔。請先讀 [compose.md](compose.md)。預設 none 保留原生登入，另有 identity gateway 的 header／token／OIDC；不架 SSO Server。
+容器固定使用套件身分，不繼承登入者 File Station ACL。Shared Folder 是安裝後 admin 授權，現階段官方 ACL／project control 未驗證，維持 blocked，不 acquire 上游專案。
 
 ## 建置與檢查
 
@@ -39,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.14.1}
-backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.14.1, node: {package: Node.js_v20}}
+backend: {runtime: python, dir: app, entry: main.py, sdk: 0.15.0}
+backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.15.0, node: {package: Node.js_v20}}
 backend: {runtime: rust, dir: app, entry: hello, methods: [hello.greet]}
 ```
 
@@ -232,16 +233,6 @@ 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`。
+Compose 在 `dsm-package.yaml` 使用 `ui.launch`，預設 new-page；省略時也不宣告 Application Portal。
+
+Compose classless gateway 用 `type: url`，有 AppWindow wrapper 的原生 App 才使用 `standalone`；都沿用 CLI 共用 app-launch 解析。Compose 的差異請見 [compose.md](compose.md)。

package/skills/reference/ctl.md

@@ -0,0 +1,41 @@
+# Control registered NAS Apps with ctl
+
+Use this for operating installed Apps, rather than building/deploying projects.
+
+1. `synopkgland ctl host list --json` checks registered machines and sessions.
+2. Register with `ctl host add nas --url https://nas.example:5001 --username alice`, or renew with `ctl host login nas`. Credentials are hidden interactive input; `--password-stdin` is available. Do not put passwords/OTP in argv. Sessions and remembered-device tokens use OS secure storage, never a plaintext fallback.
+3. Run `synopkgland ctl list --host nas --json` for all registered Apps, commands, schemas, effects, permissions and executable examples. If description access needs approval, ask the user to approve the whole candidate batch; do not self-approve. An explicit `--approve-installed` records permission to send the DSM session to the displayed inventory's fixed description endpoints. Use `--app <package>` to narrow the batch. No description endpoint is anonymous.
+4. Use the discovered alias, CLI path and typed flags with an explicit `--host nas`; inspect `--help` and `--dry-run` before execution. For example, `synopkgland ctl notes list --status pending --host nas --dry-run`. Use the real command/schema from discovery, not this illustrative name.
+5. Reads need no write confirmation. For authorized write/destructive commands, add `--yes`; without it the CLI returns a plan and confirmation error. A --yes flag does not replace the user's authorization or the App's backend checks.
+
+There is no shared current context: with multiple hosts, always specify --host. `--host a,b` and --all-hosts return per-host results, with exit 8 on partial failure. Do not retry a write merely because one host failed; query its state first. --refresh rereads descriptions; unchanged package versions use the host/account/package/version/hash cache. Never assume cached metadata grants resource permission.
+
+Use `ctl host show nas` to inspect approvals/pins, `ctl host revoke nas PackageID` to remove an App approval, `ctl host logout nas` to retain registration, and `ctl host remove nas --yes` to delete sessions, device token, approvals and cache. A failed NAS logout is reported independently from successful local removal.
+
+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.
+
+## 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.
+
+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.
+
+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.
+
+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
+
+App authors must mark passkeys, tokens, private URLs, torrent/base64 and upload content with standard JSON Schema `writeOnly: true`, including nested objects, array items and local references. Mark sensitive response fields in resultSchema too. Do not embed real secrets in schema defaults/enums/examples or command examples.
+
+CLI plans, dry-run, missing-yes errors, JSON/multi-host output and known input values repeated by the App use the fixed string `<redacted>`. Schema validation errors never echo instance values or paths. This changes presentation only: authorized requests still send the original values. The CLI does not log or cache business parameters. Sensitive description examples/defaults are masked in list/help and disk caches; a cache altered by redaction requires a fresh authenticated description/hash check before execution. Fill placeholders locally; never paste secrets into AI messages or logs.
+
+## Command naming recommendations
+
+Prefer `<resource> <verb>`. Common verbs are `list`, `get`, `export` (often reads), `create`, `update`, `import`, `run` (often writes), and `delete` (often destructive). Pick one synonym within an App; avoid mixing show/get/status for the same task. These are recommendations only: Apps may use domain verbs such as `pause` and `resume`.
+
+Every command must explicitly declare its required `effect`. CLI/build never infer or overwrite effect from the verb. The existing check that command effect must not be less restrictive than its bindings remains. There is no verb allowlist or new verb rejection rule.

package/skills/reference/deploy.md

@@ -5,7 +5,7 @@
 3. Review `synopkgland deploy --dry-run --arch x86_64`, which does not connect to a NAS.
 4. Only when installation is authorized, run `synopkgland deploy --host <profile>`.
 
-Deployment uploads directly to DSM. It does not publish artifacts. Container install answers use --share, --run-as and --param; omitted upgrade answers are retained by package preinst, which also rejects missing newly required values.
+Deployment uploads directly to DSM. It does not publish artifacts. Compose uses schema-2 differences and fixed package identity. Existing Shared Folder intent requires admin confirmation after install; official protected ACL/project control is currently blocked. No install answer or user destination grant activates a package mount. See compose.md and its device acceptance blockers.
 
 For native-go root-ops, approve fixed operations in DSM after installation. Updates that change the task text require fresh approval. Uninstall removes the executor tasks, the App's Application Privileges rules and a stale portal alias itself. Never delete installed packages or data as part of a code cleanup.
 

package/skills/reference/files.md

@@ -122,3 +122,7 @@ sweep forward the cancel instead of admitting it.
   forward. This is not proof of other DSM releases or full writer/reboot behavior.
 
 The pinned scope-selection task also binds the protected generation observed before confirmation. The executor compares it under the publish lock and refuses stale tasks, so a retained task cannot replay an older selection after another confirmation.
+
+## Container mounts
+
+Containers use a fixed package identity and never inherit the signed-in user's File Station ACL. Mount grants are distinct from user destination grants. Per-user file access requires a session/Broker Adapter, outside this change. Read [compose.md](compose.md); official ACL/project control remains blocked.