@fnnas-labs/fnos-cli 0.0.0-stage → 0.2.1

package/skill/reference/user.md

@@ -0,0 +1,139 @@
+# 用户与认证参考
+
+## OAuth 登录
+
+fnos-cli 使用 OAuth 2.0 Authorization Code + PKCE 建立代理 session，不使用 NAS 用户名密码、
+2FA 登录或旧 token 恢复链。CLI 按用户、文件读写、下载、应用中心、相册、系统、日志、存储和
+Docker 模块申请 `trim.*` scope；完整列表见 `oauth.md`。
+
+生产环境只使用交互式登录：
+
+```bash
+fnos-cli --profile home --host <host> --port <port> login
+```
+
+CLI 输出授权链接并在当前 profile 保存一次性 PKCE verifier，然后保持运行并等待
+`Authorization code`。用户自行在浏览器输入账号密码、确认授权、复制页面显示的 code，再粘贴
+到 CLI 提示。不要自动填写账号密码、点击授权或读取页面 code，也不要把 code 放进命令参数。
+无法自动打开浏览器时添加 `--no-open`。授权 URL 不包含 `redirect_uri`，不要自行追加；token
+交换成功后一次性 PKCE 文件会被删除。
+
+Session 保存以下认证信息：
+
+| Field | Meaning |
+| --- | --- |
+| `accessToken` | 代理业务请求的 Bearer token |
+| `refreshToken` | access token 刷新凭据 |
+| `accessTokenExpiresAt` | access token 的 Unix 秒过期时间 |
+| `oauthClientId` | CLI 使用的 OAuth client id |
+| `oauthDeviceId` | 本机持久化的 OAuth device id |
+| `oauthScope` | 已授权 scope |
+
+普通已认证命令会在 access token 临近过期时自动调用 refresh。也可以显式执行：
+
+```bash
+fnos-cli --profile home login --refresh
+```
+
+refresh 响应没有返回新 refresh token 时，CLI 保留已有 refresh token。刷新前会先确认当前
+profile 的 session 存储可写；预检失败时停止当前命令，不发送 refresh，也不静默切换到用户名
+密码登录。多个进程同时恢复时，CLI 会复用已写入的新 session，不覆盖较新的 token。
+
+`logout` 只清除当前 profile 的本地 session，不表示服务端 token 已撤销：
+
+```bash
+fnos-cli --profile home logout
+```
+
+## 当前用户与列表
+
+```bash
+fnos-cli user info
+fnos-cli user list
+fnos-cli user list --mode group --group Users
+fnos-cli user request user.list --json '{"limit":100,"offset":0}'
+```
+
+| Command | Endpoint | Important output |
+| --- | --- | --- |
+| `user info` | `user.info` | `userInfo.user`、`uid`、`admin` |
+| `user list` | `user.list` | 用户数组、总数和分页字段 |
+| `user list --mode group` | `user.listUG` | 指定组中的用户 |
+
+`user request` 的 endpoint 必须以 `user.` 开头；`--json` 必须是 JSON object，且不能手工提供
+`req` 或 `reqid`。通用 `user request` 无法从 endpoint 名称可靠判断读写属性，因此默认要求确认；
+自动化时需明确传 `--yes`。已封装的 `user info`、`user list` 等专用只读命令不需要该参数。
+
+## 用户写操作
+
+```bash
+fnos-cli user add <user> [--password <initial-password>] [--groups Users] [--set-admin] --yes
+fnos-cli user mod <user> [--new-name <name>] [--password <new-password>] [--groups Users] --yes
+fnos-cli user del <user> --yes
+fnos-cli user change-password <user> --yes
+fnos-cli user unfreeze <user> --yes
+fnos-cli user set-admin <user> --admin true --yes
+```
+
+| Command | Endpoint | Main request fields |
+| --- | --- | --- |
+| `user add` | `user.add` | `user`、`password`、`groups`、可选联系信息和管理员标记 |
+| `user mod` | `user.mod` | `user` 加显式提供的变更字段 |
+| `user del` | `user.del` | `user` |
+| `user change-password` | `user.changePassword` | `user`、交互输入的新密码 |
+| `user unfreeze` | `user.unfreeze` | `user` |
+| `user set-admin` | `user.setAdmin` | `user`、`admin` |
+
+这里的 `--password` 是创建用户或修改目标用户密码，不是 CLI 登录凭据。不要把用户管理密码
+改写成登录参数。密码不要出现在回复、日志或长期保存的命令记录中；省略可交互输入的密码参数。
+
+删除用户、修改管理员权限、改密码和解冻属于写操作，未得到用户明确授权时不要执行。
+
+## 用户组
+
+```bash
+fnos-cli user group list
+fnos-cli user group info <group>
+fnos-cli user group users <group>
+fnos-cli user group add <group> [--comment <text>] --yes
+fnos-cli user group mod <group> [--new-name <name>] [--comment <text>] --yes
+fnos-cli user group del <group> --yes
+fnos-cli user group set-users <group> --users <user> --yes
+fnos-cli user group add-users <group> --users <user> --yes
+fnos-cli user group del-users <group> --users <user> --yes
+```
+
+| Command | Endpoint | Main request fields |
+| --- | --- | --- |
+| `group list` | `user.groupList` | 无 |
+| `group info` | `user.groupInfo` | `group` |
+| `group users` | `user.groupUsers` | `group` |
+| `group add` | `user.groupAdd` | `group`、可选 `comment` |
+| `group mod` | `user.groupMod` | `group`、可选新名称和备注 |
+| `group del` | `user.groupDel` | `group` |
+| `group set-users` | `user.groupSetUsers` | `group`、`users` |
+| `group add-users` | `user.groupAddUsers` | `group`、`users` |
+| `group del-users` | `user.groupDelUsers` | `group`、`users` |
+
+`--users` 和 `--groups` 支持重复参数或逗号分隔值。空列表、控制字符和明显非法名称会在发请求
+前被拒绝。
+
+## 登录设备
+
+```bash
+fnos-cli user login-devices
+fnos-cli user request user.listLoginDevice
+```
+
+登录设备列表是用户管理数据，不参与 CLI 的 OAuth PKCE 登录。不要根据设备列表尝试旧的
+trusted-device/2FA 登录流程。
+
+## 错误处理
+
+- `saved proxy session is required`：先完成 OAuth 登录。
+- OAuth pending 缺失或过期：重新运行完整的交互式 `login`，不要单独拼装兑换命令。
+- refresh 失败或 refresh token 缺失：重新运行 OAuth 登录，不回退到账号密码。
+- refresh 返回后 session 最终写入失败：不要盲目复用旧 refresh token；它可能已被轮换，应重新登录。
+- 权限错误：先用 `user info` 确认 `admin`，不要自动提升权限。
+- 写操作未确认：向用户说明目标和影响，得到授权后再传 `--yes`。
+- 响应含业务错误码时原样报告错误语义，不要只依据 HTTP 状态判断成功。

package/skill/reference/workflows/device-validation.md

@@ -0,0 +1,66 @@
+# Device validation
+
+Use this workflow for interactive OAuth, minimal probes and read-after-write verification.
+
+## 1. User authorization
+
+Production validation uses interactive OAuth PKCE:
+
+1. The user runs `fnos-cli --profile <profile> --host <host> --port <port> login`
+   in their own interactive terminal.
+2. The CLI displays an authorization link and waits.
+3. The user opens the link, signs in and approves access in the browser.
+4. The user copies the one-time code into the CLI's `Authorization code` prompt.
+5. The CLI exchanges the code and saves the selected profile's session.
+
+The Agent does not collect credentials, approve access, read browser codes or
+pass codes as arguments. Add `--no-open` if the browser cannot open automatically;
+the remaining steps are unchanged. Authorization URLs omit `redirect_uri`.
+
+For DSH, the login terminal must share the DSH Host, system user, configuration
+environment and `--profile`. Remote browsers, SSH shells and containers do not
+automatically inherit that session. macOS background Keychain access may need
+system approval.
+
+## 2. Minimal read-only probes
+
+Before any write:
+
+1. Confirm interactive login established the intended profile's session; do not
+   preconfigure or rotate accounts as part of validation.
+2. Run one or two read-only commands for the target module to check connectivity
+   and permissions.
+3. For files, prefer `file ls` or a read-only search.
+4. For storage, use `storage pools` / `storage disks`.
+5. For Docker, use `docker stats` or `docker container ls`.
+
+Confirm the device target, session and sufficient current-user permissions.
+
+## 3. Write sequence
+
+1. Probe the closest relevant read-only state.
+2. Perform one authorized, explainable and reversible write.
+3. Immediately read the resulting state.
+4. Clean up temporary resources when appropriate.
+
+Keep unrelated writes out of the same validation run.
+
+## 4. Read-after-write verification
+
+Use at least one relevant check:
+
+- Files: `ls`, `search` or `share list`.
+- Storage: `pools`, `disks` or `removable`.
+- Docker: `image ls`, `container ls` or `compose ls`.
+- Users: `user list` or `group list`.
+
+Only claim success when the before/after states can be compared objectively.
+
+## 5. Stop and ask
+
+Stop when OAuth or code exchange fails, the target host is missing, a write may
+affect production data/services, or responses conflict with documented
+constraints and suggest firmware differences.
+
+Read the module reference once the command is selected. Resolve unknown
+profiles, permissions and device state before proceeding.

package/skill/reference/workflows/file-routing.md

@@ -0,0 +1,44 @@
+# File paths and shared-directory routing
+
+Select the command first, then read `../file.md` for field details.
+
+## 1. Match the intent
+
+| Intent | Preferred command | Path and semantic rule |
+| --- | --- | --- |
+| List currently visible directories | `fnos-cli file ls` | Both no argument and `/` omit `path`; this does not promise all volumes |
+| List a concrete directory | `fnos-cli file ls /vol{n}/...` | Keep aggregate roots separate from canonical paths |
+| Search the current user's files | `fnos-cli file search <key>` | Let the CLI probe and derive the current-user directory |
+| Search a specified directory | `fnos-cli file search <key> /vol{n}/...` | Use concrete canonical paths |
+| Upload a local file | `fnos-cli file upload /vol{n}/... <localFile> --yes` | The remote argument is a directory, not a final filename |
+| Search files shared with me | `fnos-cli file search-others <key>` | Distinct from shared-directory listing |
+| Inspect a shared directory | `fnos-cli file share info <path>` | Not share-link management |
+| List visible shared directories | `fnos-cli file share list [uid]` | Not file search |
+| Inspect ACLs | `fnos-cli file acl get <path>` | Permission data, not shared-directory state |
+| Create/delete/copy/move files | `file mkdir/rm/cp/mv` | Concrete paths and explicit `--yes` |
+
+## 2. Resolve paths
+
+1. Writes require concrete canonical `/vol{n}/...` paths.
+2. `file ls` and `file ls /` both omit `path`; neither explicitly requests aggregate root `/`.
+3. Search without a path lets the CLI probe the current-user directory via `file.ls`.
+4. Every explicit search path must be `/vol{n}/...`.
+5. For files shared by others, choose `search-others` or `share list-others` as appropriate.
+
+## 3. Important distinctions
+
+- Shared directories use `file share.*`, not share links.
+- `file search-others` returns matching files, not a shared-directory list.
+- ACL queries report permissions, not share status.
+- `file cp` / `file mv` take a destination directory, not a final filename.
+- Upload `uploadName` is an HTTP upload/resume path, not necessarily the visible filename.
+
+## 4. Stop and ask
+
+Clarify writes with only `/`, relative or ambiguous paths; requests for share
+links when only shared-directory APIs are documented; mixed noncanonical search
+paths; and assumptions that the current-user directory is a fixed value.
+
+For fields read [file.md](../file.md). For uploads read
+[file-upload-validation.md](file-upload-validation.md). Resolve path semantics
+before constructing a payload.

package/skill/reference/workflows/file-upload-validation.md

@@ -0,0 +1,63 @@
+# Upload validation
+
+Verify small uploads, same-name policies and resumable large uploads.
+
+## 1. Prerequisites
+
+- A signed-in target NAS.
+- A confirmed writable `/vol{n}/...` directory.
+- An existing local regular file.
+
+## 2. Small file
+
+1. Create a temporary subdirectory in the confirmed writable directory.
+2. Upload a local file smaller than 20 MiB:
+
+```bash
+fnos-cli file upload /vol1/1000/tmp-upload ./demo.txt --overwrite rename --yes
+```
+
+3. List the temporary directory:
+
+```bash
+fnos-cli file ls /vol1/1000/tmp-upload
+```
+
+4. Confirm the CLI reports the requested target path and the directory contains
+   the matching filename.
+
+## 3. Large file
+
+1. Prepare a local file of at least 20 MiB.
+2. Upload it:
+
+```bash
+fnos-cli file upload /vol1/1000/tmp-upload ./large.bin --overwrite rename --yes
+```
+
+3. List the directory and confirm the original filename exists remotely.
+4. When diagnosing resume, inspect the upload cache in the local configuration
+   directory. Its `upload_path` is the backend's `.~#n` upload path, not the final filename.
+5. Resume only when endpoint, profile, signed-in user, remote target, size,
+   overwrite policy and local SHA-256 all match. A different same-size file at
+   the same local path must begin a new `check-upload`.
+6. Concurrent uploads to the same endpoint and remote target serialize across
+   processes; lock waiting does not by itself indicate corrupt cache.
+
+## 4. Cleanup
+
+After verifying the exact temporary paths, remove the uploaded files and directory:
+
+```bash
+fnos-cli file rm /vol1/1000/tmp-upload/demo.txt --yes
+fnos-cli file rm /vol1/1000/tmp-upload/large.bin --yes
+fnos-cli file rm /vol1/1000/tmp-upload --yes
+```
+
+## 5. Completion criteria
+
+The successful output uses the requested path, and `file ls` shows the uploaded
+file. Small files do not depend on resume cache. Large files may create cache;
+cache paths support HTTP upload/resume and are not visible result paths.
+Legacy caches, caches missing identity fields and local fingerprint mismatches
+must not resume.

package/skill/reference/workflows/photos-routing.md

@@ -0,0 +1,83 @@
+# Photo task routing
+
+Use for library statistics, filtered search, AI semantic search and sampled previews.
+Read the Photos reference after selecting a command.
+
+## 1. Authentication
+
+Photos reuses the current profile's proxy session. Without a valid session, the
+user runs interactive `fnos-cli login`, opens the link, signs in, authorizes
+and pastes the one-time code into the CLI. The Agent does not enter credentials,
+approve access or read browser codes.
+
+For multiple devices, select `--profile`, `--host` and `--port` explicitly.
+Sessions are not interchangeable across devices.
+
+## 2. Scenarios
+
+### Library scope and size
+
+```bash
+fnos-cli photos folders
+```
+
+Summarize returned photo/video counts per scanned folder. Photos indexes only
+folders added to scanning; filesystem image counts are not library index counts.
+
+### Filtered search and counts
+
+```bash
+fnos-cli photos search Beijing --limit 20
+fnos-cli photos search IMG --filter file_type=photo --limit 20
+```
+
+Report the response's `total` as the full match count; `list` is the returned
+sample. For previews, choose a few representative results and call
+`photos preview <id> --size m`, rather than fetching every original.
+
+### Natural-language AI search
+
+Check readiness before searching:
+
+```bash
+fnos-cli photos request post /api/v1/magic-search/ready --yes
+fnos-cli photos request post /api/v1/magic-search/do \
+  --json '{"keyword":"sunset at the beach","antiFilters":[]}' --yes
+```
+
+AI search is a separate endpoint from filtered `photos search`. It usually
+returns `response.data.list` without a stable `total`; report only the number
+returned. If the model is missing, not ready or incompatible with the query
+language, report the business error. A filename-search fallback is not an AI result.
+
+`photos request` preserves the raw envelope and can exit 0 even when
+`response.code != 0`. Both calls require `httpStatus` in `200..299` and
+`response.code == 0`. Select result IDs from `response.data.list` for previews.
+
+### Sampled previews
+
+```bash
+fnos-cli photos preview <id> --size m
+fnos-cli photos preview <id> --size o
+```
+
+Prefer medium previews; use `--size o` only when the user asks for originals.
+
+## 3. Counts and links
+
+| Result | Meaning | Caveat |
+| --- | --- | --- |
+| Filtered search `total` | All matches | Not the current `list` length |
+| AI `list` length | Returned count | Not an exact total without `total` |
+| `previewUrl` | Thumbnail, original or video preview | Browser usually needs a signed-in fnOS cookie |
+
+Keep secure-store tokens private and preserve the CLI's sensitive-URI redaction.
+
+## 4. Stop and clarify
+
+Clarify exact-count requests when AI results lack `total`, public-preview
+requests without browser authentication, and preview-only tasks that would
+fetch every original. Stop on non-2xx `httpStatus` or nonzero `response.code`.
+
+Read [photos.md](../photos.md) for fields/filters/AI endpoints and
+[device-validation.md](device-validation.md) for device differences.

package/skill/reference/workflows/storage-dangerous-ops.md

@@ -0,0 +1,53 @@
+# High-risk storage operations
+
+Probe read-only state before deciding whether a storage write can proceed.
+
+## 1. Identify high-risk writes
+
+Use this workflow before `storage umount/create/stop/add-disk/remove-disk/replace-disk/resize/extend/format/eject/disk-mount/disk-umount`,
+and before `storage request` unless the endpoint is confirmed read-only.
+
+`storage mount` is lower risk but still requires the pool identifier and current
+state. Removable-disk mount/unmount operations require the exact disk target.
+
+## 2. Read-only probes
+
+1. `fnos-cli storage pools`.
+2. `fnos-cli storage disks`.
+3. Before pool creation, `fnos-cli storage free-disks`.
+4. As needed, `fnos-cli storage health <disk>` or `storage smart <disk>`.
+5. For removable devices, `storage removable` and `storage disk-info <disk>`.
+
+Confirm whether the target is a pool UUID/`trim_*` identifier or plain disk
+name, its state and removability. For remaining space on a system disk, use the
+returned `part`, not whole-disk `name`. Keep disk and pool operations distinct.
+
+## 3. Password and confirmation policy
+
+| Policy | Commands |
+| --- | --- |
+| Verify and forward password | `umount`, `create`, `stop`, `add-disk`, `remove-disk`, `replace-disk`, `resize` |
+| Verify without forwarding | `extend`, `format`, `eject` |
+| Confirmation without password verification | `mount`, `disk-mount`, `disk-umount` |
+| Generic request | `request` requires confirmation; explicit `--password` is verified and forwarded |
+
+Agent/noninteractive writes explicitly pass `--yes`. For the first two rows,
+stop if the required password is unavailable; there is no assumed default.
+Treat potentially mutating `stor.*` requests as high risk.
+
+## 4. Distinctions
+
+- `mount` is not the inverse of `stop`; check pool state.
+- `extend` and `resize` are different operations.
+- `format` / `eject` target removable devices, not ordinary pools.
+- Pools use UUIDs or `trim_*`, not legacy `name`.
+- Disks use plain names such as `sda` or `nvme0n1`, not `/dev/sda`.
+
+## 5. Stop and clarify
+
+Stop for ambiguous pool/disk targets, probe results inconsistent with the user's
+description, unavailable required passwords, or stopped/unmounted/non-expandable
+targets and standby/abnormal disks.
+
+Once target and order are confirmed, read [stor.md](../stor.md). Otherwise remain
+at the read-only probe stage.

package/skill/scripts/fnos-cli

@@ -0,0 +1,63 @@
+#!/bin/sh
+
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+BIN_DIR="$SCRIPT_DIR/../bin"
+
+reject_media_command() {
+  skip_value=0
+  for arg in "$@"; do
+    if [ "$skip_value" -eq 1 ]; then
+      skip_value=0
+      continue
+    fi
+    case "$arg" in
+      --host|--port|--profile|--scheme)
+        skip_value=1
+        ;;
+      --host=*|--port=*|--profile=*|--scheme=*|--allow-insecure-http|--tls-insecure)
+        ;;
+      --*)
+        ;;
+      media)
+        echo "Media commands are not available in this skill package." >&2
+        exit 2
+        ;;
+      *)
+        return
+        ;;
+    esac
+  done
+}
+
+reject_media_command "$@"
+
+OS=$(uname -s)
+ARCH=$(uname -m)
+
+case "$OS:$ARCH" in
+  Darwin:arm64)
+    TARGET="$BIN_DIR/trim-cli-darwin-arm64"
+    ;;
+  Darwin:x86_64)
+    TARGET="$BIN_DIR/trim-cli-darwin-x64"
+    ;;
+  Linux:x86_64)
+    TARGET="$BIN_DIR/trim-cli-linux-x64"
+    ;;
+  Linux:aarch64|Linux:arm64)
+    TARGET="$BIN_DIR/trim-cli-linux-arm64"
+    ;;
+  *)
+    echo "Unsupported platform for $0: $OS $ARCH" >&2
+    exit 1
+    ;;
+esac
+
+if [ ! -x "$TARGET" ]; then
+  echo "Missing packaged binary: $TARGET" >&2
+  exit 1
+fi
+
+exec "$TARGET" "$@"

package/skill/scripts/fnos-cli.cmd

@@ -0,0 +1,36 @@
+@echo off
+setlocal
+
+call :reject_media %*
+if errorlevel 1 exit /b %errorlevel%
+
+set "SCRIPT_DIR=%~dp0"
+set "ARCH=%PROCESSOR_ARCHITECTURE%"
+if defined PROCESSOR_ARCHITEW6432 set "ARCH=%PROCESSOR_ARCHITEW6432%"
+if /I "%ARCH%"=="ARM64" (
+  set "TARGET=%SCRIPT_DIR%..\bin\trim-cli-windows-arm64.exe"
+) else (
+  set "TARGET=%SCRIPT_DIR%..\bin\trim-cli-windows-x64.exe"
+)
+
+if not exist "%TARGET%" (
+  echo Missing packaged binary: %TARGET% 1>&2
+  exit /b 1
+)
+
+"%TARGET%" %*
+exit /b %errorlevel%
+
+:reject_media
+if "%~1"=="" exit /b 0
+set "ARG=%~1"
+if /I "%ARG%"=="--host" shift&shift&goto reject_media
+if /I "%ARG%"=="--port" shift&shift&goto reject_media
+if /I "%ARG%"=="--profile" shift&shift&goto reject_media
+if /I "%ARG%"=="--scheme" shift&shift&goto reject_media
+if "%ARG:~0,1%"=="-" shift&goto reject_media
+if /I "%ARG%"=="media" (
+  echo Media commands are not available in this skill package. 1>&2
+  exit /b 2
+)
+exit /b 0

package/skill/scripts/fnos-cli.ps1

@@ -0,0 +1,31 @@
+$Architecture = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString()
+$Platform = if ($Architecture -eq "Arm64") { "windows-arm64" } else { "windows-x64" }
+$Target = Join-Path $PSScriptRoot "..\bin\trim-cli-$Platform.exe"
+
+$SkipValue = $false
+foreach ($Argument in $args) {
+  if ($SkipValue) {
+    $SkipValue = $false
+    continue
+  }
+  if ($Argument -in @("--host", "--port", "--profile", "--scheme")) {
+    $SkipValue = $true
+    continue
+  }
+  if ($Argument.StartsWith("-")) {
+    continue
+  }
+  if ($Argument -eq "media") {
+    Write-Error "Media commands are not available in this skill package."
+    exit 2
+  }
+  break
+}
+
+if (-not (Test-Path $Target)) {
+  Write-Error "Missing packaged binary: $Target"
+  exit 1
+}
+
+& $Target @args
+exit $LASTEXITCODE

package/skill/scripts/trim-cli

@@ -0,0 +1,63 @@
+#!/bin/sh
+
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+BIN_DIR="$SCRIPT_DIR/../bin"
+
+reject_media_command() {
+  skip_value=0
+  for arg in "$@"; do
+    if [ "$skip_value" -eq 1 ]; then
+      skip_value=0
+      continue
+    fi
+    case "$arg" in
+      --host|--port|--profile|--scheme)
+        skip_value=1
+        ;;
+      --host=*|--port=*|--profile=*|--scheme=*|--allow-insecure-http|--tls-insecure)
+        ;;
+      --*)
+        ;;
+      media)
+        echo "Media commands are not available in this skill package." >&2
+        exit 2
+        ;;
+      *)
+        return
+        ;;
+    esac
+  done
+}
+
+reject_media_command "$@"
+
+OS=$(uname -s)
+ARCH=$(uname -m)
+
+case "$OS:$ARCH" in
+  Darwin:arm64)
+    TARGET="$BIN_DIR/trim-cli-darwin-arm64"
+    ;;
+  Darwin:x86_64)
+    TARGET="$BIN_DIR/trim-cli-darwin-x64"
+    ;;
+  Linux:x86_64)
+    TARGET="$BIN_DIR/trim-cli-linux-x64"
+    ;;
+  Linux:aarch64|Linux:arm64)
+    TARGET="$BIN_DIR/trim-cli-linux-arm64"
+    ;;
+  *)
+    echo "Unsupported platform for $0: $OS $ARCH" >&2
+    exit 1
+    ;;
+esac
+
+if [ ! -x "$TARGET" ]; then
+  echo "Missing packaged binary: $TARGET" >&2
+  exit 1
+fi
+
+exec "$TARGET" "$@"

package/skill/scripts/trim-cli.cmd

@@ -0,0 +1,36 @@
+@echo off
+setlocal
+
+call :reject_media %*
+if errorlevel 1 exit /b %errorlevel%
+
+set "SCRIPT_DIR=%~dp0"
+set "ARCH=%PROCESSOR_ARCHITECTURE%"
+if defined PROCESSOR_ARCHITEW6432 set "ARCH=%PROCESSOR_ARCHITEW6432%"
+if /I "%ARCH%"=="ARM64" (
+  set "TARGET=%SCRIPT_DIR%..\bin\trim-cli-windows-arm64.exe"
+) else (
+  set "TARGET=%SCRIPT_DIR%..\bin\trim-cli-windows-x64.exe"
+)
+
+if not exist "%TARGET%" (
+  echo Missing packaged binary: %TARGET% 1>&2
+  exit /b 1
+)
+
+"%TARGET%" %*
+exit /b %errorlevel%
+
+:reject_media
+if "%~1"=="" exit /b 0
+set "ARG=%~1"
+if /I "%ARG%"=="--host" shift&shift&goto reject_media
+if /I "%ARG%"=="--port" shift&shift&goto reject_media
+if /I "%ARG%"=="--profile" shift&shift&goto reject_media
+if /I "%ARG%"=="--scheme" shift&shift&goto reject_media
+if "%ARG:~0,1%"=="-" shift&goto reject_media
+if /I "%ARG%"=="media" (
+  echo Media commands are not available in this skill package. 1>&2
+  exit /b 2
+)
+exit /b 0