@kweaver-ai/kweaver-sdk 0.8.2 → 0.8.3

package/README.md

@@ -126,23 +126,19 @@ const graph     = await client.bkn.querySubgraph("bkn-id", { /* path spec */ });
 await client.bkn.executeAction("bkn-id", "at-id", { /* params */ });
 const logs      = await client.bkn.listActionLogs("bkn-id");
 
-// Data sources & data views
+// Data sources & vega-backend resources
 const dsList = await client.datasources.list();
 const tables = await client.datasources.listTables("ds-id");
-const viewId = await client.dataviews.create({ name: "v", datasourceId: "ds-id", table: "orders" });
-const views = await client.dataviews.list({ datasourceId: "ds-id" });
-const fuzzy = await client.dataviews.find("BOM", { wait: false });
-const exact = await client.dataviews.find("orders", {
+const resId  = await client.resources.create({ name: "v", datasourceId: "ds-id", table: "orders" });
+const resList = await client.resources.list({ datasourceId: "ds-id" });
+const fuzzy  = await client.resources.find("BOM", { wait: false });
+const exact  = await client.resources.find("orders", {
   datasourceId: "ds-id",
   exact: true,
   wait: true,
 });
-const dv = await client.dataviews.get(viewId);
-const queryRows = await client.dataviews.query(viewId, {
-  sql: "SELECT id, name FROM orders LIMIT 10",
-  limit: 10,
-  needTotal: true,
-});
+const res       = await client.resources.get(resId);
+const queryRows = await client.resources.query(resId, { limit: 10, needTotal: true });
 
 // Dataflow automation (CSV import pipeline, etc.)
 const result = await client.dataflows.execute({
@@ -190,50 +186,28 @@ Use `callTool(name, args)` when you need native MCP `tools/call` access for newl
 
 ## CLI Reference
 
+`kweaver` follows a `gh`-style help layout (see [docs/cli_conventions.md §8](../../docs/cli_conventions.md#8-help-文本格式must)):
+
+```text
+kweaver [--help|-h]                       # gh-style top-level overview
+kweaver help <command>                    # forward to <command> --help
+kweaver help all                          # full per-action signatures (migration fallback)
+kweaver <command> [--help|-h]             # subcommand overview + actions
+kweaver <command> <subcommand> [--help|-h]  # action-level flags + examples
 ```
-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
-kweaver auth list/use/delete/logout
-kweaver config show / list-bd / set-bd <value>   # platform business domain — show/list-bd work with KWEAVER_BASE_URL (+ KWEAVER_TOKEN for list-bd)
-kweaver token
-kweaver ds list/get/delete/tables/connect
-kweaver ds import-csv <ds_id> --files <glob> [--table-prefix <p>] [--batch-size 500] [--recreate]
-kweaver dataflow list/run/runs/logs
-kweaver model llm list/get/add/edit/delete/test/chat/--template
-kweaver model small list/get/add/edit/delete/test/embeddings/rerank/--template
-kweaver dataview list/find/get/query/delete
-kweaver bkn list/get/stats/export/create/update/delete
-kweaver bkn create-from-ds <ds_id> --name <name> [--tables t1,t2] [--build]
-kweaver bkn create-from-csv <ds_id> --files <glob> --name <name> [--build]
-kweaver bkn validate/push/pull
-kweaver bkn object-type list/get/create/update/delete/query/properties
-kweaver bkn metric list/get/create/search/validate/update/delete/query/dry-run
-kweaver bkn relation-type list/get/create/update/delete
-kweaver bkn action-type list/query/execute
-kweaver bkn subgraph / search
-kweaver bkn action-execution get
-kweaver bkn action-log list/get/cancel
-kweaver agent list/get/create/update/delete/chat/sessions/history/publish/unpublish
-kweaver skill list/market/get/market-get/register/status/delete/update-metadata/update-package/history/republish/publish-history/content/read-file/download/install/management-content/management-read-file/management-download
-kweaver vega health/stats/inspect/sql/catalog/resource/connector-type
-kweaver context-loader help <subcommand>
-kweaver context-loader tools|resources|templates|prompts <kn-id>
-kweaver context-loader search-schema <kn-id> <query> [--scope object,relation,action,metric] [--concept-groups ids]
-kweaver context-loader tool-call <kn-id> <name> --args '<json>'
-kweaver context-loader kn-search|kn-schema-search <kn-id> <query> [...]  (deprecated; use search-schema)
-kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
-kweaver context-loader config set/use/list/show                       (deprecated; <kn-id> may be omitted to fall back to saved config)
-kweaver toolbox create/list/publish/unpublish/delete
-kweaver tool upload/list/enable/disable/execute/debug (execute and debug accept --path for OpenAPI path params)
-kweaver call <path> [-X METHOD] [-d BODY] [-H header] [-F key=value]
+
+Top-level command groups:
+
+```text
+AUTHENTICATION & CONFIG  auth · token · config
+DECISION AGENT           agent · toolbox · tool
+AI DATA PLATFORM         bkn · ds · resource · dataflow · vega · context-loader
+TRACE AI                 trace
+FOUNDATION               call · explore · model · skill · help
 ```
 
+For a structured browsable index of every action and flag, run `kweaver help all`.
+
 ### Dataflow CLI examples
 
 ```bash

package/README.zh.md

@@ -124,22 +124,18 @@ const graph     = await client.bkn.querySubgraph("bkn-id", { /* 路径规格 */
 await client.bkn.executeAction("bkn-id", "at-id", { /* 参数 */ });
 const logs      = await client.bkn.listActionLogs("bkn-id");
 
-// 数据源与数据视图
-const dsList = await client.datasources.list();
-const viewId = await client.dataviews.create({ name: "v", datasourceId: "ds-id", table: "orders" });
-const views = await client.dataviews.list({ datasourceId: "ds-id" });
-const fuzzy = await client.dataviews.find("BOM", { wait: false });
-const exact = await client.dataviews.find("orders", {
+// 数据源 & vega-backend 资源
+const dsList    = await client.datasources.list();
+const resId     = await client.resources.create({ name: "v", datasourceId: "ds-id", table: "orders" });
+const resList   = await client.resources.list({ datasourceId: "ds-id" });
+const fuzzy     = await client.resources.find("BOM", { wait: false });
+const exact     = await client.resources.find("orders", {
   datasourceId: "ds-id",
   exact: true,
   wait: true,
 });
-const dv = await client.dataviews.get(viewId);
-const queryRows = await client.dataviews.query(viewId, {
-  sql: "SELECT id, name FROM orders LIMIT 10",
-  limit: 10,
-  needTotal: true,
-});
+const res       = await client.resources.get(resId);
+const queryRows = await client.resources.query(resId, { limit: 10, needTotal: true });
 
 // Vega — 可观测性与查询
 const catalogs = await client.vega.listCatalogs();
@@ -181,43 +177,28 @@ const history = await client.skills.history("skill-id");
 
 ## 命令速查
 
+`kweaver` 采用 `gh` 风格 help 布局（详见 [docs/cli_conventions.md §8](../../docs/cli_conventions.md#8-help-文本格式must)）：
+
+```text
+kweaver --help                            # gh 风格顶层概览
+kweaver help <command>                    # 转发到 `<command> --help`
+kweaver help all                          # 完整 per-action 签名（迁移期兜底）
+kweaver <command> --help                  # 子命令概览 + 动作列表
+kweaver <command> <subcommand> --help     # 动作级 flag + 示例
 ```
-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
-kweaver auth list/use/delete/logout
-kweaver config show / list-bd / set-bd <value>   # 业务域；show/list-bd 在无已保存平台时可与 env 配对
-kweaver token
-kweaver ds list/get/delete/tables/connect
-kweaver dataflow list/run/runs/logs
-kweaver model llm list/get/add/edit/delete/test/chat/--template
-kweaver model small list/get/add/edit/delete/test/embeddings/rerank/--template
-kweaver dataview list/find/get/query/delete
-kweaver bkn list/get/stats/export/create/update/delete
-kweaver bkn object-type list/get/create/update/delete/query/properties
-kweaver bkn metric list/get/create/search/validate/update/delete/query/dry-run
-kweaver bkn relation-type list/get/create/update/delete
-kweaver bkn action-type list/query/execute
-kweaver bkn subgraph
-kweaver bkn action-execution get
-kweaver bkn action-log list/get/cancel
-kweaver agent list/get/chat/sessions/history
-kweaver skill list/market/get/market-get/register/status/delete/update-metadata/update-package/history/republish/publish-history/content/read-file/download/install/management-content/management-read-file/management-download
-kweaver vega health|stats|inspect|sql|catalog|resource|connector-type
-kweaver context-loader help <subcommand>
-kweaver context-loader tools|resources|templates|prompts <kn-id>
-kweaver context-loader search-schema <kn-id> <query> [--scope object,relation,action,metric] [--concept-groups ids]
-kweaver context-loader tool-call <kn-id> <name> --args '<json>'
-kweaver context-loader kn-search|kn-schema-search <kn-id> <query> [...]  （deprecated；请使用 search-schema）
-kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
-kweaver context-loader config set/use/list/show                       （deprecated；省略 <kn-id> 时回退到已保存配置）
-kweaver call <path> [-X METHOD] [-d BODY] [-H header]
+
+顶层命令分组：
+
+```text
+AUTHENTICATION & CONFIG  auth · token · config
+DECISION AGENT           agent · toolbox · tool
+AI DATA PLATFORM         bkn · ds · resource · dataflow · vega · context-loader
+TRACE AI                 trace
+FOUNDATION               call · explore · model · skill · help
 ```
 
+需要查阅每个动作的完整签名（可浏览 / 可 grep）时，运行 `kweaver help all`。
+
 ### Dataflow CLI 示例
 
 ```bash

package/dist/api/resources.d.ts

@@ -0,0 +1,94 @@
+export declare const RESOURCE_LIST_DEFAULT_LIMIT = 30;
+/** Field metadata for a resource schema. */
+export interface ViewField {
+    name: string;
+    type: string;
+    display_name?: string;
+    comment?: string;
+}
+/** Normalized vega-backend Resource model. */
+export interface Resource {
+    id: string;
+    name: string;
+    catalog_id: string;
+    category: string;
+    source_identifier?: string;
+    status?: string;
+    schema_definition?: ViewField[];
+    logic_definition?: unknown;
+}
+export declare function parseResource(raw: Record<string, unknown>): Resource;
+export interface CreateResourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    name: string;
+    datasourceId: string;
+    table: string;
+    fields?: Array<{
+        name: string;
+        type: string;
+    }>;
+    businessDomain?: string;
+}
+export declare function createResource(options: CreateResourceOptions): Promise<string>;
+export interface ListResourcesOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    /** Filter by catalog (data source) id. */
+    datasourceId?: string;
+    /** Server-side name filter. */
+    name?: string;
+    /** Category filter (e.g. "table", "logicview"). */
+    category?: string;
+    /** Max items; ignored when <= 0. */
+    limit?: number;
+}
+export declare function listResources(options: ListResourcesOptions): Promise<Resource[]>;
+export interface DeleteResourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function deleteResource(options: DeleteResourceOptions): Promise<void>;
+export interface GetResourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function getResource(options: GetResourceOptions): Promise<Resource>;
+export interface FindResourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    /** Resource name to search for. */
+    name: string;
+    /** Filter by catalog (data source) id. */
+    datasourceId?: string;
+    /** When true, apply client-side exact name match after server filter (default false). */
+    exact?: boolean;
+    /** When true, poll until a result appears or timeout (default false). */
+    wait?: boolean;
+    /** Total wait budget in ms (default 30000). Only used when wait is true. */
+    timeoutMs?: number;
+}
+export declare function findResource(options: FindResourceOptions): Promise<Resource[]>;
+export interface QueryResourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    offset?: number;
+    limit?: number;
+    needTotal?: boolean;
+    filterCondition?: unknown;
+    sort?: string;
+    direction?: "asc" | "desc";
+    businessDomain?: string;
+}
+export interface ResourceQueryResult {
+    entries?: unknown;
+    total_count?: number;
+}
+export declare function queryResource(options: QueryResourceOptions): Promise<ResourceQueryResult>;

package/dist/api/resources.js

@@ -0,0 +1,166 @@
+import { HttpError } from "../utils/http.js";
+import { buildHeaders } from "./headers.js";
+export const RESOURCE_LIST_DEFAULT_LIMIT = 30;
+export function parseResource(raw) {
+    const res = {
+        id: String(raw.id ?? ""),
+        name: String(raw.name ?? ""),
+        catalog_id: String(raw.catalog_id ?? ""),
+        category: String(raw.category ?? ""),
+    };
+    if (raw.source_identifier != null)
+        res.source_identifier = String(raw.source_identifier);
+    if (raw.status != null)
+        res.status = String(raw.status);
+    if (Array.isArray(raw.schema_definition) && raw.schema_definition.length > 0) {
+        res.schema_definition = raw.schema_definition.map((f) => ({
+            name: String(f.name ?? ""),
+            type: String(f.type ?? "varchar"),
+            display_name: f.display_name != null ? String(f.display_name) : undefined,
+            comment: f.comment != null ? String(f.comment) : undefined,
+        }));
+    }
+    if (raw.logic_definition !== undefined)
+        res.logic_definition = raw.logic_definition;
+    return res;
+}
+function extractListPayload(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === "object") {
+        const obj = data;
+        const items = obj.entries ?? obj.data;
+        if (Array.isArray(items))
+            return items;
+    }
+    return [];
+}
+export async function createResource(options) {
+    const { baseUrl, accessToken, name, datasourceId, table, fields = [], businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/vega-backend/v1/resources`;
+    const body = {
+        name,
+        catalog_id: datasourceId,
+        category: "table",
+        source_identifier: table,
+    };
+    if (fields.length > 0)
+        body.schema_definition = fields;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    const data = JSON.parse(responseBody);
+    return String(data.id ?? "");
+}
+export async function listResources(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", datasourceId, name, category, limit = RESOURCE_LIST_DEFAULT_LIMIT, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/vega-backend/v1/resources`);
+    if (datasourceId)
+        url.searchParams.set("catalog_id", datasourceId);
+    if (name)
+        url.searchParams.set("name", name);
+    if (category)
+        url.searchParams.set("category", category);
+    if (limit && limit > 0)
+        url.searchParams.set("limit", String(limit));
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const bodyText = await response.text();
+    if (!response.ok)
+        throw new HttpError(response.status, response.statusText, bodyText);
+    const parsed = JSON.parse(bodyText);
+    const items = extractListPayload(parsed);
+    return items
+        .filter((item) => item != null && typeof item === "object")
+        .map(parseResource);
+}
+export async function deleteResource(options) {
+    const { baseUrl, accessToken, id, businessDomain = "bd_public" } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/vega-backend/v1/resources/${encodeURIComponent(id)}`;
+    const response = await fetch(url, {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const bodyText = await response.text();
+    if (!response.ok)
+        throw new HttpError(response.status, response.statusText, bodyText);
+}
+export async function getResource(options) {
+    const { baseUrl, accessToken, id, businessDomain = "bd_public" } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/vega-backend/v1/resources/${encodeURIComponent(id)}`;
+    const response = await fetch(url, {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const body = await response.text();
+    if (!response.ok)
+        throw new HttpError(response.status, response.statusText, body);
+    const parsed = JSON.parse(body);
+    // vega-backend GET /:id returns { entries: [...] } (supports comma-separated ids)
+    const items = extractListPayload(parsed);
+    const raw = items.length > 0 ? items[0] : (parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null);
+    if (!raw || typeof raw !== "object")
+        throw new HttpError(500, "Invalid response", body);
+    return parseResource(raw);
+}
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function findResource(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", name, datasourceId, exact = false, wait = false, timeoutMs = 30_000, } = options;
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+    while (true) {
+        const list = await listResources({ baseUrl, accessToken, businessDomain, datasourceId, name });
+        const results = exact ? list.filter((v) => v.name === name) : list;
+        if (results.length > 0 || !wait || Date.now() >= deadline)
+            return results;
+        const delayMs = Math.min(5000, 1000 * 2 ** attempt);
+        attempt += 1;
+        await sleepMs(delayMs);
+    }
+}
+export async function queryResource(options) {
+    const { baseUrl, accessToken, id, offset = 0, limit = 50, needTotal = false, filterCondition, sort, direction, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/vega-backend/v1/resources/${encodeURIComponent(id)}/data`;
+    const body = { offset, limit, need_total: needTotal };
+    if (filterCondition !== undefined)
+        body.filter_condition = filterCondition;
+    if (sort !== undefined)
+        body.sort = sort;
+    if (direction !== undefined)
+        body.direction = direction;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+            "x-http-method-override": "GET",
+        },
+        body: JSON.stringify(body),
+    });
+    const bodyText = await response.text();
+    if (!response.ok)
+        throw new HttpError(response.status, response.statusText, bodyText);
+    const parsed = JSON.parse(bodyText);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return {};
+}

package/dist/cli.js

@@ -9,14 +9,93 @@ import { runContextLoaderCommand } from "./commands/context-loader.js";
 import { runDataflowCommand } from "./commands/dataflow.js";
 import { runDsCommand } from "./commands/ds.js";
 import { runExploreCommand } from "./commands/explore.js";
-import { runDataviewCommand } from "./commands/dataview.js";
+import { runResourceCommand } from "./commands/resource.js";
 import { runModelCommand } from "./commands/model.js";
 import { runSkillCommand } from "./commands/skill.js";
 import { runTokenCommand } from "./commands/token.js";
 import { runToolboxCommand } from "./commands/toolbox.js";
 import { runToolCommand } from "./commands/tool.js";
 import { runVegaCommand } from "./commands/vega.js";
+import { renderHelp } from "./help/format.js";
 function printHelp() {
+    console.log(renderHelp({
+        tagline: "KWeaver SDK — operate KWeaver platform from CLI",
+        usage: [
+            "kweaver [global flags] <command> <subcommand> [flags]",
+            "kweaver --version | -V",
+            "kweaver --help | -h",
+        ],
+        sections: [
+            {
+                title: "AUTHENTICATION & CONFIG",
+                items: [
+                    { name: "auth", desc: "Login / switch / list saved platform credentials" },
+                    { name: "token", desc: "Print current access token (auto-refresh)" },
+                    { name: "config", desc: "Per-platform business-domain config" },
+                ],
+            },
+            {
+                title: "DECISION AGENT",
+                items: [
+                    { name: "agent", desc: "Agent CRUD, chat, sessions, publish" },
+                    { name: "toolbox", desc: "Agent toolbox lifecycle" },
+                    { name: "tool", desc: "Tools inside toolbox" },
+                ],
+            },
+            {
+                title: "AI DATA PLATFORM",
+                items: [
+                    { name: "bkn", desc: "Knowledge network — build, query, action, metric" },
+                    { name: "ds", desc: "Datasource (list, get, connect, tables)" },
+                    { name: "resource (res)", desc: "Resources — list, find, get, query, delete" },
+                    { name: "dataflow", desc: "Dataflow document workflows (run, runs, logs)" },
+                    { name: "vega", desc: "Vega observability — catalog, resource, query" },
+                    { name: "context-loader (context)", desc: "MCP/HTTP context loader (reads BKN schema/instances)" },
+                ],
+            },
+            {
+                title: "TRACE AI",
+                items: [
+                    { name: "trace", desc: "Diagnose conversations / build eval-sets / schema validate" },
+                ],
+            },
+            {
+                title: "FOUNDATION",
+                items: [
+                    { name: "call (curl)", desc: "curl-style API call with auto-injected auth headers" },
+                    { name: "explore", desc: "Interactive web UI" },
+                    { name: "model", desc: "Model factory — LLM / small-model CRUD + chat" },
+                    { name: "skill", desc: "Skill registry / market" },
+                    { name: "help", desc: "Show help — use `help all` for full signatures" },
+                ],
+            },
+        ],
+        flags: [
+            { name: "--base-url <url>", desc: "Override platform URL  (env: KWEAVER_BASE_URL)" },
+            { name: "--token <value>", desc: "Override access token  (env: KWEAVER_TOKEN; disables write commands)" },
+            { name: "--user <id|name>", desc: "Use specific user credentials (env: KWEAVER_USER)" },
+            { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+            { name: "--compact", desc: "Compact JSON output (pipeline-friendly)" },
+            { name: "--help, -h", desc: "Show help" },
+            { name: "--version, -V", desc: "Show version" },
+        ],
+        environment: [
+            { name: "KWEAVER_PROFILE", desc: "Isolate active-platform/user state per shell" },
+            { name: "KWEAVERC_CONFIG_DIR", desc: "Override config root (~/.kweaver)" },
+        ],
+        examples: [
+            "kweaver auth https://platform.example.com",
+            "kweaver agent chat <agent_id> -m \"hello\"",
+            "kweaver bkn build <kn-id> --wait",
+        ],
+        learnMore: [
+            "Use `kweaver <command> --help` for command-specific help",
+            "Use `kweaver help all` for full command signatures (migration fallback)",
+            "For agents/multi-terminal: prefer `--user <id>` over `auth switch`",
+        ],
+    }));
+}
+function printHelpFull() {
     console.log(`kweaver
 
 Usage:
@@ -76,11 +155,11 @@ Usage:
   kweaver model small list|get|add|edit|delete|test|embeddings|rerank|--template ...
   kweaver model --help
 
-  kweaver dataview list [--datasource-id id] [--type atomic|custom] [--limit n] [-bd value]
-  kweaver dataview find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value]
-  kweaver dataview get <id> [-bd value]
-  kweaver dataview query <id> [--sql sql] [--limit n] [--offset n] [--need-total] [--raw-sql] [-bd value]
-  kweaver dataview delete <id> [-y] [-bd value]
+  kweaver resource list [--datasource-id id] [--type table|logicview] [--limit n] [-bd value]
+  kweaver resource find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value]
+  kweaver resource get <id> [-bd value]
+  kweaver resource query <id> [--limit n] [--offset n] [--need-total] [-bd value]
+  kweaver resource delete <id> [-y] [-bd value]
 
   kweaver bkn list [options]
   kweaver bkn get <kn-id> [options]
@@ -176,7 +255,7 @@ Commands:
   ds             Manage datasources (list, get, delete, tables, connect)
   dataflow       Dataflow document workflows (list, run, runs, logs)
   model          Model factory: LLM/small-model CRUD (manager) and llm chat (OpenAI-compatible API)
-  dataview|dv    List, find, get, query (SQL), delete data views (atomic / custom)
+  resource|res   List, find, get, query, delete vega-backend resources (table / logicview)
   bkn            Knowledge network (CRUD, build, validate, export, stats, push/pull,
                  object-type, relation-type, subgraph, action-type, action-execution, action-log)
   config         Per-platform configuration (business domain)
@@ -238,10 +317,23 @@ export async function run(argv) {
         console.log(pkg.version);
         return 0;
     }
-    if (argv.length === 0 || !command || command === "--help" || command === "-h" || command === "help") {
+    if (argv.length === 0 || !command || command === "--help" || command === "-h") {
         printHelp();
         return 0;
     }
+    if (command === "help") {
+        const topic = rest[0];
+        if (!topic) {
+            printHelp();
+            return 0;
+        }
+        if (topic === "all") {
+            printHelpFull();
+            return 0;
+        }
+        // `help <command>` → forward to `<command> --help`
+        return run([...rest, "--help"]);
+    }
     if (command === "auth") {
         return runAuthCommand(rest);
     }
@@ -257,8 +349,8 @@ export async function run(argv) {
     if (command === "model") {
         return runModelCommand(rest);
     }
-    if (command === "dataview" || command === "dv") {
-        return runDataviewCommand(rest);
+    if (command === "resource" || command === "res") {
+        return runResourceCommand(rest);
     }
     if (command === "token") {
         return runTokenCommand(rest);

package/dist/client.d.ts

@@ -3,7 +3,7 @@ import { ConversationsResource } from "./resources/conversations.js";
 import { ContextLoaderResource } from "./resources/context-loader.js";
 import { DataflowsResource } from "./resources/dataflows.js";
 import { DataSourcesResource } from "./resources/datasources.js";
-import { DataViewsResource } from "./resources/dataviews.js";
+import { ResourcesResource } from "./resources/resources.js";
 import { KnowledgeNetworksResource } from "./resources/knowledge-networks.js";
 import { BknResource } from "./resources/bkn.js";
 import { SkillsResource } from "./resources/skills.js";
@@ -98,8 +98,8 @@ export declare class KWeaverClient implements ClientContext {
     readonly dataflows: DataflowsResource;
     /** Data source management (connect, test, list tables). */
     readonly datasources: DataSourcesResource;
-    /** Data view creation and retrieval. */
-    readonly dataviews: DataViewsResource;
+    /** Vega-backend resource management (table/logicview resources under a catalog). */
+    readonly resources: ResourcesResource;
     /** Vega observability platform (catalogs, resources, connector types). */
     readonly vega: VegaResource;
     /** ADP/KWeaver skill registry, market, progressive read, and install helpers. */