@kweaver-ai/kweaver-sdk 0.6.6 → 0.6.8

package/README.md

@@ -31,7 +31,9 @@ export KWEAVER_BASE_URL=https://your-kweaver-instance.com
 export KWEAVER_TOKEN=your-token
 ```
 
-With both set, API commands use that token even if you never ran `auth login`. You can also run **`kweaver auth status`**, **`kweaver auth whoami`** (supports `--json`), and **`kweaver config show`** when there is **no** current platform in `~/.kweaver/` — the CLI decodes the token locally (JWT only). If the token is opaque, identity fields are omitted and a short hint is printed.
+With both set, API commands use that token even if you never ran `auth login`. You can also run **`kweaver auth status`**, **`kweaver auth whoami`** (supports `--json`), and **`kweaver config show`** when there is **no** current platform in `~/.kweaver/`. In env-token mode, `whoami` resolves the bound identity from EACP `/api/eacp/v1/user/get` and prints `Type` (user/app), `User ID`, `Account` and `Name`; this works for both opaque and JWT tokens. If EACP is unreachable, the CLI falls back to local JWT decode and prints a short hint when the token is opaque.
+
+`kweaver config list-bd` lists business domains for the current user. App (service) tokens are not bound to an end-user — when the backend rejects the call with `401 invalid user_id`, the CLI re-checks the token type via EACP and, if confirmed `type:"app"`, replaces the cryptic backend body with `This command does not support app accounts.`. Use a user token (interactive `auth login`) for user-bound endpoints.
 
 ### Business domain (platform)
 
@@ -153,8 +155,11 @@ const skillMd = await client.skills.fetchContent("skill-id");
 ## CLI Reference
 
 ```
-kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--http-signin] [--insecure|-k]
+kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--new-password <pwd>] [--http-signin] [--insecure|-k]
 # -u/-p (with or without --http-signin): HTTP POST /oauth2/signin (yields refresh_token). Missing -u/-p are prompted from stdin (password hidden when TTY).
+# If the server returns error 401001017 (initial password), TTY users get a prompt to set a new password; non-interactive scripts must pass --new-password <pwd>.
+kweaver auth change-password [<url>] [-u <account>] [-o <old>] [-n <new>] [--insecure|-k]
+# EACP POST /api/eacp/v1/auth1/modifypassword — no OAuth token required. Omit -o/-n on a TTY to be prompted.
 kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (headless login)
 kweaver auth export [url|alias] [--json]   (export command to run on a headless host)
 kweaver auth status / whoami [url|alias] [--json]   # whoami: --json; with KWEAVER_BASE_URL+KWEAVER_TOKEN when no ~/.kweaver/ platform

package/README.zh.md

@@ -31,7 +31,9 @@ export KWEAVER_BASE_URL=https://your-kweaver-instance.com
 export KWEAVER_TOKEN=your-token
 ```
 
-两者同时设置时，即使未执行 `auth login`，业务命令也会使用该 token。若 **`~/.kweaver/` 无当前平台**，仍可使用 **`kweaver auth status`**、**`kweaver auth whoami`**（支持 `--json`）、**`kweaver config show`**：CLI 会在本地解 JWT 展示身份；若 token 为 opaque，则省略身份字段并给出简短提示。
+两者同时设置时，即使未执行 `auth login`，业务命令也会使用该 token。若 **`~/.kweaver/` 无当前平台**，仍可使用 **`kweaver auth status`**、**`kweaver auth whoami`**（支持 `--json`）、**`kweaver config show`**。环境变量模式下，`whoami` 会通过 EACP `/api/eacp/v1/user/get` 在线获取身份并展示 `Type`（user/app）、`User ID`、`Account`、`Name`，对 opaque 与 JWT token 都生效；若 EACP 不可达，则回退到本地 JWT 解码，opaque token 会给出简短提示。
+
+`kweaver config list-bd` 用于列出当前用户可访问的业务域。**应用（service）token 没有绑定终端用户**——当后端返回 `401 invalid user_id` 时，CLI 会再向 EACP 复核 token 类型，确认为 `type:"app"` 后将晦涩的后端原文替换为 `This command does not support app accounts.`。需要这个能力时请改用交互式 `auth login` 获得的用户 token。
 
 ### 业务域（平台配置）
 
@@ -146,8 +148,10 @@ const skillMd = await client.skills.fetchContent("skill-id");
 ## 命令速查
 
 ```
-kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--http-signin] [--insecure|-k]
+kweaver auth login <url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--new-password <pwd>] [--http-signin] [--insecure|-k]
 # -u/-p（无论是否带 --http-signin）：HTTP POST /oauth2/signin（可拿 refresh_token）；缺失的用户名/密码会从 stdin 提示输入（TTY 下密码隐藏）
+# 若服务端返回 401001017（初始密码），交互终端会引导修改；非交互请使用 --new-password <pwd>。
+kweaver auth change-password [<url>] [-u <account>] [-o <old>] [-n <new>] [--insecure|-k]
 kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (无浏览器登录)
 kweaver auth export [url|alias] [--json]   (导出在无浏览器机器上运行的命令)
 kweaver auth status / whoami [url|alias] [--json]   # whoami 支持 --json；无 ~/.kweaver/ 当前平台时可配 KWEAVER_BASE_URL+KWEAVER_TOKEN

package/dist/api/toolboxes.js

@@ -12,8 +12,8 @@ import { buildHeaders } from "./headers.js";
 //   POST   /tool-box/{id}/tools/status enable/disable (batch)
 //
 // Verified during Task 8 e2e against the live backend (2026-04-18):
-//   GET    /tool-box?keyword=&limit=&offset=  list toolboxes
-//   GET    /tool-box/{id}/tool                list tools
+//   GET    /tool-box/list?keyword=&limit=&offset=  list toolboxes
+//   GET    /tool-box/{id}/tools/list               list tools
 const PATH = "/api/agent-operator-integration/v1/tool-box";
 function url(base, suffix = "") {
     return `${base.replace(/\/+$/, "")}${PATH}${suffix}`;
@@ -74,7 +74,7 @@ export async function listToolboxes(opts) {
         qp.set("limit", String(opts.limit));
     if (opts.offset !== undefined)
         qp.set("offset", String(opts.offset));
-    const suffix = qp.toString() ? `?${qp}` : "";
+    const suffix = `/list${qp.toString() ? `?${qp}` : ""}`;
     const { body } = await fetchTextOrThrow(url(opts.baseUrl, suffix), {
         method: "GET",
         headers: buildHeaders(opts.accessToken, opts.businessDomain ?? "bd_public"),
@@ -82,7 +82,7 @@ export async function listToolboxes(opts) {
     return body;
 }
 export async function listTools(opts) {
-    const { body } = await fetchTextOrThrow(url(opts.baseUrl, `/${encodeURIComponent(opts.boxId)}/tool`), {
+    const { body } = await fetchTextOrThrow(url(opts.baseUrl, `/${encodeURIComponent(opts.boxId)}/tools/list`), {
         method: "GET",
         headers: buildHeaders(opts.accessToken, opts.businessDomain ?? "bd_public"),
     });

package/dist/auth/eacp-modify-password.d.ts

@@ -0,0 +1,25 @@
+/** Encrypt a password with EACP modifypassword's RSA public key, base64-encoded. */
+export declare function encryptModifyPwd(plain: string, publicKeyPem?: string): string;
+/** @internal For unit tests: decrypt ciphertext produced by encryptModifyPwd with the embedded key. */
+export declare function decryptModifyPwdForTest(cipherB64: string): string;
+export interface EacpModifyPasswordOptions {
+    account: string;
+    oldPassword: string;
+    newPassword: string;
+    /** Override the embedded RSA public key (PEM). */
+    publicKeyPem?: string;
+    tlsInsecure?: boolean;
+}
+export interface EacpModifyPasswordResult {
+    status: number;
+    ok: boolean;
+    body: string;
+    json?: unknown;
+}
+/**
+ * Call EACP `POST /api/eacp/v1/auth1/modifypassword` to change a user's password
+ * when the old password is known (`isforgetpwd: false`).
+ *
+ * No bearer token / cookie is required — the endpoint authenticates by old password.
+ */
+export declare function eacpModifyPassword(baseUrl: string, options: EacpModifyPasswordOptions): Promise<EacpModifyPasswordResult>;

package/dist/auth/eacp-modify-password.js

@@ -0,0 +1,84 @@
+import { constants as cryptoConstants, createPrivateKey, createPublicKey, privateDecrypt, publicEncrypt, } from "node:crypto";
+import { normalizeBaseUrl, runWithTlsInsecure } from "./oauth.js";
+/**
+ * 1024-bit RSA private key embedded in ShareServer
+ * (`isf/ShareServer/src/eachttpserver/ncEACHttpServerUtil.cpp`, function
+ * `ncEACHttpServerUtil::RSADecrypt`). It is the keypair used by the EACP
+ * `auth1/modifypassword` endpoint to decrypt `oldpwd` / `newpwd`.
+ *
+ * Note: this key is intentionally hard-coded in the C++ binary and shipped to
+ * every customer; it is not a secret. We embed it here so the CLI can perform
+ * the matching `RSA_PKCS1` encryption without contacting the server.
+ */
+const EACP_MODIFYPWD_PRIVATE_KEY_PEM = `-----BEGIN RSA PRIVATE KEY-----
+MIICXgIBAAKBgQDB2fhLla9rMx+6LWTXajnK11Kdp520s1Q+TfPfIXI/7G9+L2YC
+4RA3M5rgRi32s5+UFQ/CVqUFqMqVuzaZ4lw/uEdk1qHcP0g6LB3E9wkl2FclFR0M
++/HrWmxPoON+0y/tFQxxfNgsUodFzbdh0XY1rIVUIbPLvufUBbLKXHDPpwIDAQAB
+AoGBALCM/H6ajXFs1nCR903aCVicUzoS9qckzI0SIhIOPCfMBp8+PAJTSJl9/ohU
+YnhVj/kmVXwBvboxyJAmOcxdRPWL7iTk5nA1oiVXMer3Wby+tRg/ls91xQbJLVv3
+oGSt7q0CXxJpRH2oYkVVlMMlZUwKz3ovHiLKAnhw+jEsdL2BAkEA9hA97yyeA2eq
+f9dMu/ici99R3WJRRtk4NEI4WShtWPyziDg48d3SOzYmhEJjPuOo3g1ze01os70P
+ApE7d0qcyQJBAMmt+FR8h5MwxPQPAzjh/fTuTttvUfBeMiUDrIycK1I/L96lH+fU
+i4Nu+7TPOzExnPeGO5UJbZxrpIEUB7Zs8O8CQQCLzTCTGiNwxc5eMgH77kVrRudp
+Q7nv6ex/7Hu9VDXEUFbkdyULbj9KuvppPJrMmWZROw04qgNp02mayM8jeLXZAkEA
+o+PM/pMn9TPXiWE9xBbaMhUKXgXLd2KEq1GeAbHS/oY8l1hmYhV1vjwNLbSNrH9d
+yEP73TQJL+jFiONHFTbYXwJAU03Xgum5mLIkX/02LpOrz2QCdfX1IMJk2iKi9osV
+KqfbvHsF0+GvFGg18/FXStG9Kr4TjqLsygQJT76/MnMluw==
+-----END RSA PRIVATE KEY-----`;
+let cachedPubKey;
+function getModifyPwdPublicKey() {
+    if (!cachedPubKey) {
+        cachedPubKey = createPublicKey(createPrivateKey(EACP_MODIFYPWD_PRIVATE_KEY_PEM));
+    }
+    return cachedPubKey;
+}
+/** Encrypt a password with EACP modifypassword's RSA public key, base64-encoded. */
+export function encryptModifyPwd(plain, publicKeyPem) {
+    const key = publicKeyPem ? createPublicKey(publicKeyPem) : getModifyPwdPublicKey();
+    const buf = publicEncrypt({ key, padding: cryptoConstants.RSA_PKCS1_PADDING }, Buffer.from(plain, "utf8"));
+    return buf.toString("base64");
+}
+/** @internal For unit tests: decrypt ciphertext produced by encryptModifyPwd with the embedded key. */
+export function decryptModifyPwdForTest(cipherB64) {
+    const key = createPrivateKey(EACP_MODIFYPWD_PRIVATE_KEY_PEM);
+    const buf = privateDecrypt({ key, padding: cryptoConstants.RSA_PKCS1_PADDING }, Buffer.from(cipherB64, "base64"));
+    return buf.toString("utf8");
+}
+/**
+ * Call EACP `POST /api/eacp/v1/auth1/modifypassword` to change a user's password
+ * when the old password is known (`isforgetpwd: false`).
+ *
+ * No bearer token / cookie is required — the endpoint authenticates by old password.
+ */
+export async function eacpModifyPassword(baseUrl, options) {
+    return runWithTlsInsecure(options.tlsInsecure, async () => {
+        const body = {
+            account: options.account,
+            oldpwd: encryptModifyPwd(options.oldPassword, options.publicKeyPem),
+            newpwd: encryptModifyPwd(options.newPassword, options.publicKeyPem),
+            vcodeinfo: {
+                uuid: "",
+                vcode: "",
+            },
+            isforgetpwd: false,
+        };
+        const url = `${normalizeBaseUrl(baseUrl)}/api/eacp/v1/auth1/modifypassword`;
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/plain, */*",
+            },
+            body: JSON.stringify(body),
+        });
+        const text = await resp.text();
+        let json;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            /* not JSON */
+        }
+        return { status: resp.status, ok: resp.ok, body: text, json };
+    });
+}

package/dist/auth/oauth.d.ts

@@ -1,4 +1,17 @@
 import { type TokenConfig } from "../config/store.js";
+/** Thrown when `POST /oauth2/signin` returns HTTP 401 with EACP code `401001017` (initial password must be changed). */
+export declare class InitialPasswordChangeRequiredError extends Error {
+    readonly code = 401001017;
+    readonly account: string;
+    readonly baseUrl: string;
+    readonly httpStatus = 401;
+    readonly serverMessage: string;
+    constructor(opts: {
+        account: string;
+        baseUrl: string;
+        serverMessage: string;
+    });
+}
 /**
  * Studioweb hardcoded LOGIN public key (PEM) — the single key used for HTTP `/oauth2/signin`.
  * Source: kweaver-ai/kweaver `deploy/auto_cofig/auto_config.sh` `LOGIN_PUBLIC_KEY`.
@@ -14,18 +27,73 @@ export declare const DEFAULT_SIGNIN_RSA_MODULUS_HEX = "C1D9F84B95AF6B331FBA2D64D
  * Build an SPKI PEM from an RSA modulus (hex) and public exponent (default 65537 / 0x10001).
  */
 export declare function rsaModulusHexToSpkiPem(modulusHex: string, exponent?: number): string;
-/** POSIX shell single-quote escaping for copy-paste commands. */
-export declare function shellQuoteForShell(value: string): string;
+/** Identity resolved from EACP `/api/eacp/v1/user/get` for the bound access token. */
+export interface EacpUserInfo {
+    /** "user" — interactive end-user; "app" — service / application identity. */
+    type: "user" | "app";
+    /** EACP id (`userid` for users, `id` for apps). */
+    id: string;
+    /** Login name (e.g. "alice@example.com"). User tokens only. */
+    account?: string;
+    /** Display name — `visionName` for users, app name for apps. */
+    name?: string;
+}
+/**
+ * Probe EACP for the bound identity. Returns `null` on any failure (network,
+ * non-2xx, malformed JSON, unknown `type`). Callers must treat absence as a
+ * soft signal — this never throws and never blocks the user's actual command.
+ *
+ * The shape differs per token type, mirroring the EACP backend:
+ *   - `type: "user"` → `{ userid, account, name, ... }`
+ *   - `type: "app"`  → `{ id, name }`
+ */
+export declare function fetchEacpUserInfo(baseUrl: string, accessToken: string, tlsInsecure?: boolean): Promise<EacpUserInfo | null>;
+/**
+ * Quote a value for safe copy-paste into a shell command.
+ *
+ * Strategy:
+ * - If the value only contains "shell-safe" characters, return it bare. This
+ *   keeps the printed command portable across shells (issue #74: POSIX single
+ *   quotes are literal in cmd.exe, so any quoting locks the line to one OS).
+ * - Otherwise the value contains characters the shell would interpret
+ *   (space, `&`, `|`, `$`, `*`, ...), so we must quote per host shell:
+ *     - win32 (cmd.exe / PowerShell): wrap in `"..."`; embedded `"` -> `""`
+ *     - POSIX (bash/zsh/sh): wrap in `'...'`; embedded `'` -> `'\''`
+ *
+ * `platform` defaults to `process.platform`; passable for tests and for
+ * generating commands targeted at a specific shell.
+ */
+export declare function shellQuoteForShell(value: string, platform?: NodeJS.Platform): string;
 /**
  * Build a one-line `kweaver auth login ...` command for headless / other machines.
  * Omits `--client-secret` when empty (PKCE-only client); headless refresh may still require a confidential client.
+ *
+ * `platform` defaults to `process.platform`; pass explicitly in tests or when
+ * generating a command meant for a different OS.
  */
-export declare function buildCopyCommand(baseUrl: string, clientId: string, clientSecret: string, refreshToken: string | undefined, tlsInsecure?: boolean): string;
+export declare function buildCopyCommand(baseUrl: string, clientId: string, clientSecret: string, refreshToken: string | undefined, tlsInsecure?: boolean, platform?: NodeJS.Platform): string;
 /**
  * HTML shown after successful OAuth callback with a copyable headless login command.
  */
 export declare function buildCallbackHtml(copyCommand: string): string;
 export declare function normalizeBaseUrl(value: string): string;
+/**
+ * Resolve the platform URL the CLI should act on, with explicit precedence:
+ *
+ *   1. **positional**  — caller passed a URL/alias (always wins)
+ *   2. **env**         — `KWEAVER_BASE_URL` is set (explicit user intent;
+ *                        wins over a stale `~/.kweaver/` saved session)
+ *   3. **saved**       — `getCurrentPlatform()` from local config
+ *
+ * `source` lets callers print provenance without re-deriving it. This mirrors
+ * `ensureValidToken()` (which is already env-first), so introspection
+ * commands (`auth status`, `auth whoami`, `config show|list-bd|set-bd`) and
+ * data-path commands agree on which platform "current" means.
+ */
+export declare function resolveActivePlatform(positional?: string | null): {
+    url: string;
+    source: "positional" | "env" | "saved";
+} | null;
 /**
  * Temporarily disable TLS certificate verification for Node `fetch` (sets
  * NODE_TLS_REJECT_UNAUTHORIZED). Used for `--insecure` login and token refresh.

package/dist/auth/oauth.js

@@ -3,6 +3,21 @@ import { createPublicKey } from "node:crypto";
 import { isNoAuth } from "../config/no-auth.js";
 import { deleteClientConfig, getCurrentPlatform, loadClientConfig, loadTokenConfig, loadUserTokenConfig, resolveUserId, saveClientConfig, saveNoAuthPlatform, saveTokenConfig, setCurrentPlatform, } from "../config/store.js";
 import { HttpError, NetworkRequestError, fetchWithRetry } from "../utils/http.js";
+/** Thrown when `POST /oauth2/signin` returns HTTP 401 with EACP code `401001017` (initial password must be changed). */
+export class InitialPasswordChangeRequiredError extends Error {
+    code = 401001017;
+    account;
+    baseUrl;
+    httpStatus = 401;
+    serverMessage;
+    constructor(opts) {
+        super(opts.serverMessage);
+        this.name = "InitialPasswordChangeRequiredError";
+        this.account = opts.account;
+        this.baseUrl = opts.baseUrl;
+        this.serverMessage = opts.serverMessage;
+    }
+}
 const TOKEN_TTL_SECONDS = 3600;
 /** Seconds before access token expiry to trigger refresh (matches Python ConfigAuth). */
 const REFRESH_THRESHOLD_SEC = 60;
@@ -231,42 +246,94 @@ function extractRsaPublicKeyMaterialFromPageProps(pageProps) {
     }
     return deepFindSigninRsaMaterial(pageProps, 5, new Set());
 }
-/** Best-effort fetch of display name via EACP userinfo (ShareServer). */
-async function fetchDisplayName(baseUrl, accessToken, tlsInsecure) {
+/**
+ * Probe EACP for the bound identity. Returns `null` on any failure (network,
+ * non-2xx, malformed JSON, unknown `type`). Callers must treat absence as a
+ * soft signal — this never throws and never blocks the user's actual command.
+ *
+ * The shape differs per token type, mirroring the EACP backend:
+ *   - `type: "user"` → `{ userid, account, name, ... }`
+ *   - `type: "app"`  → `{ id, name }`
+ */
+export async function fetchEacpUserInfo(baseUrl, accessToken, tlsInsecure) {
     try {
         const res = await runWithTlsInsecure(tlsInsecure, () => fetch(`${baseUrl}/api/eacp/v1/user/get`, {
             headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" },
         }));
         if (!res.ok)
             return null;
-        const info = (await res.json());
-        if (typeof info.account === "string")
-            return info.account;
-        if (typeof info.name === "string")
-            return info.name;
-        if (typeof info.mail === "string")
-            return info.mail;
+        const raw = (await res.json());
+        const type = raw.type;
+        if (type !== "user" && type !== "app")
+            return null;
+        const idCandidate = type === "user" ? raw.userid : raw.id;
+        const id = typeof idCandidate === "string" ? idCandidate : "";
+        if (!id)
+            return null;
+        return {
+            type,
+            id,
+            account: typeof raw.account === "string" ? raw.account : undefined,
+            name: typeof raw.name === "string" ? raw.name : undefined,
+        };
     }
     catch {
-        /* Non-critical — displayName will be absent. */
+        return null;
     }
-    return null;
 }
-/** POSIX shell single-quote escaping for copy-paste commands. */
-export function shellQuoteForShell(value) {
+/** Best-effort fetch of display name via EACP userinfo (ShareServer). */
+async function fetchDisplayName(baseUrl, accessToken, tlsInsecure) {
+    const info = await fetchEacpUserInfo(baseUrl, accessToken, tlsInsecure);
+    return info?.account ?? info?.name ?? null;
+}
+/**
+ * Characters that bash/zsh/sh AND cmd.exe/PowerShell all leave untouched when
+ * a value is written without surrounding quotes. Real-world OAuth values
+ * (URLs, UUID-like client IDs, base64url refresh tokens) live in this set, so
+ * we can emit them bare and the resulting command is portable across macOS,
+ * Linux, Windows cmd, and PowerShell — including the copy-mac-paste-to-windows
+ * (and the reverse) workflow.
+ */
+const SHELL_SAFE_VALUE = /^[A-Za-z0-9._:/+=@-]+$/;
+/**
+ * Quote a value for safe copy-paste into a shell command.
+ *
+ * Strategy:
+ * - If the value only contains "shell-safe" characters, return it bare. This
+ *   keeps the printed command portable across shells (issue #74: POSIX single
+ *   quotes are literal in cmd.exe, so any quoting locks the line to one OS).
+ * - Otherwise the value contains characters the shell would interpret
+ *   (space, `&`, `|`, `$`, `*`, ...), so we must quote per host shell:
+ *     - win32 (cmd.exe / PowerShell): wrap in `"..."`; embedded `"` -> `""`
+ *     - POSIX (bash/zsh/sh): wrap in `'...'`; embedded `'` -> `'\''`
+ *
+ * `platform` defaults to `process.platform`; passable for tests and for
+ * generating commands targeted at a specific shell.
+ */
+export function shellQuoteForShell(value, platform = process.platform) {
+    if (value !== "" && SHELL_SAFE_VALUE.test(value)) {
+        return value;
+    }
+    if (platform === "win32") {
+        return `"${value.replace(/"/g, `""`)}"`;
+    }
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 /**
  * Build a one-line `kweaver auth login ...` command for headless / other machines.
  * Omits `--client-secret` when empty (PKCE-only client); headless refresh may still require a confidential client.
+ *
+ * `platform` defaults to `process.platform`; pass explicitly in tests or when
+ * generating a command meant for a different OS.
  */
-export function buildCopyCommand(baseUrl, clientId, clientSecret, refreshToken, tlsInsecure) {
-    const parts = ["kweaver", "auth", "login", shellQuoteForShell(normalizeBaseUrl(baseUrl)), "--client-id", shellQuoteForShell(clientId)];
+export function buildCopyCommand(baseUrl, clientId, clientSecret, refreshToken, tlsInsecure, platform = process.platform) {
+    const q = (v) => shellQuoteForShell(v, platform);
+    const parts = ["kweaver", "auth", "login", q(normalizeBaseUrl(baseUrl)), "--client-id", q(clientId)];
     if (clientSecret) {
-        parts.push("--client-secret", shellQuoteForShell(clientSecret));
+        parts.push("--client-secret", q(clientSecret));
     }
     if (refreshToken) {
-        parts.push("--refresh-token", shellQuoteForShell(refreshToken));
+        parts.push("--refresh-token", q(refreshToken));
     }
     if (tlsInsecure) {
         parts.push("--insecure");
@@ -336,6 +403,33 @@ function buildCallbackExchangeErrorHtml(message) {
 export function normalizeBaseUrl(value) {
     return value.replace(/\/+$/, "");
 }
+/**
+ * Resolve the platform URL the CLI should act on, with explicit precedence:
+ *
+ *   1. **positional**  — caller passed a URL/alias (always wins)
+ *   2. **env**         — `KWEAVER_BASE_URL` is set (explicit user intent;
+ *                        wins over a stale `~/.kweaver/` saved session)
+ *   3. **saved**       — `getCurrentPlatform()` from local config
+ *
+ * `source` lets callers print provenance without re-deriving it. This mirrors
+ * `ensureValidToken()` (which is already env-first), so introspection
+ * commands (`auth status`, `auth whoami`, `config show|list-bd|set-bd`) and
+ * data-path commands agree on which platform "current" means.
+ */
+export function resolveActivePlatform(positional) {
+    if (positional) {
+        const url = /^https?:\/\//.test(positional) ? normalizeBaseUrl(positional) : positional;
+        return { url, source: "positional" };
+    }
+    const envRaw = process.env.KWEAVER_BASE_URL?.trim();
+    if (envRaw) {
+        return { url: normalizeBaseUrl(envRaw), source: "env" };
+    }
+    const saved = getCurrentPlatform();
+    if (saved)
+        return { url: saved, source: "saved" };
+    return null;
+}
 /**
  * Temporarily disable TLS certificate verification for Node `fetch` (sets
  * NODE_TLS_REJECT_UNAUTHORIZED). Used for `--insecure` login and token refresh.
@@ -1268,6 +1362,26 @@ export async function oauth2PasswordSigninLogin(baseUrl, options) {
                 }
             }
             else {
+                if (postResp.status === 401) {
+                    try {
+                        const j = JSON.parse(bodyText);
+                        const c = j.code;
+                        if (c === 401001017 || c === "401001017") {
+                            const msg = typeof j.message === "string" && j.message.trim() !== ""
+                                ? j.message.trim()
+                                : "Initial password must be changed before login.";
+                            throw new InitialPasswordChangeRequiredError({
+                                account: options.username,
+                                baseUrl: base,
+                                serverMessage: msg,
+                            });
+                        }
+                    }
+                    catch (e) {
+                        if (e instanceof InitialPasswordChangeRequiredError)
+                            throw e;
+                    }
+                }
                 throw new HttpError(postResp.status, postResp.statusText, bodyText);
             }
         }
@@ -1610,12 +1724,20 @@ function isTlsVerificationDisabledForProcess() {
         process.env.KWEAVER_TLS_INSECURE === "true");
 }
 export function formatHttpError(error) {
+    if (error instanceof InitialPasswordChangeRequiredError) {
+        return `${error.serverMessage} (code ${error.code})`;
+    }
     if (error instanceof HttpError) {
         const oauthMessage = formatOAuthErrorBody(error.body);
         if (oauthMessage) {
             return `HTTP ${error.status} ${error.statusText}\n\n${oauthMessage}`;
         }
-        return `${error.message}\n${error.body}`.trim();
+        const base = `${error.message}\n${error.body}`.trim();
+        if ((error.status === 403 || error.status === 404) &&
+            /BknBackend\.KnowledgeNetwork\.NotFound/.test(error.body)) {
+            return `Hint: this is a "knowledge network not found" error (the kn-id does not exist), not a permission/auth issue. Verify the kn-id you passed.\n${base}`;
+        }
+        return base;
     }
     if (error instanceof NetworkRequestError) {
         return [

package/dist/cli.js

@@ -23,9 +23,10 @@ Usage:
   kweaver --version | -V
   kweaver --help | -h
 
-  kweaver auth <platform-url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--http-signin] [--insecure|-k]
+  kweaver auth <platform-url> [--alias name] [--no-auth] [--no-browser] [-u user] [-p pass] [--new-password <pwd>] [--http-signin] [--insecure|-k]
   kweaver auth login <platform-url>          (alias for auth <url>)
   kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (run on host without browser)
+  kweaver auth change-password [<platform-url>] [-u <account>] [-o <old>] [-n <new>] [--insecure|-k]
   kweaver auth whoami [platform-url|alias] [--json]
   kweaver auth export [platform-url|alias] [--json]
   kweaver auth status [platform-url|alias]

package/dist/commands/agent-members.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure helpers and orchestrators for managing agent member associations
+ * (skills, tools, mcps) via get → mutate(config) → update.
+ */
+export interface MutationReport {
+    finalIds: string[];
+    added: string[];
+    alreadyAttached: string[];
+    removed: string[];
+    notAttached: string[];
+}
+export interface MutateConfigMembersInput {
+    config: Record<string, unknown>;
+    path: string[];
+    idField: string;
+    addIds: string[];
+    removeIds: string[];
+}
+export interface MutateConfigMembersResult {
+    newConfig: Record<string, unknown>;
+    report: MutationReport;
+    finalIds: string[];
+}
+export declare function mutateConfigMembers(input: MutateConfigMembersInput): MutateConfigMembersResult;
+export interface MemberFetchResult {
+    exists: boolean;
+    published: boolean;
+    name?: string;
+    /** Optional free-form status label for `list` output; e.g. "published" | "draft" | "offline". */
+    status?: string;
+}
+export interface MemberSpec {
+    /** Human-readable noun used in error/warning messages. */
+    memberKind: string;
+    /** Path inside the agent `config` object where the member array lives. */
+    configPath: string[];
+    /** Key inside each array element that identifies the member. */
+    idField: string;
+}
+export interface AgentMembersDeps {
+    getAgent: (agentId: string) => Promise<string>;
+    updateAgent: (agentId: string, body: Record<string, unknown>) => Promise<string>;
+    fetchById: (id: string) => Promise<MemberFetchResult>;
+}
+export interface PatchAgentMembersInput {
+    agentId: string;
+    spec: MemberSpec;
+    addIds: string[];
+    removeIds: string[];
+    strict: boolean;
+    deps: AgentMembersDeps;
+}
+export interface PatchAgentMembersReport extends MutationReport {
+    warnings: string[];
+}
+export declare function patchAgentMembers(input: PatchAgentMembersInput): Promise<PatchAgentMembersReport>;
+export interface ListAgentMembersInput {
+    agentId: string;
+    spec: MemberSpec;
+    deps: Pick<AgentMembersDeps, "getAgent" | "fetchById">;
+}
+export interface ListedMember {
+    id: string;
+    name: string | null;
+    status: string;
+}
+export declare function listAgentMembers(input: ListAgentMembersInput): Promise<ListedMember[]>;
+export declare function runAgentSkillCommand(args: string[]): Promise<number>;