@kweaver-ai/kweaver-sdk 0.8.2 → 0.8.4

package/dist/commands/bkn-ops.js

@@ -6,13 +6,15 @@ import { prepareBknDirectoryForImport, stripBknEncodingCliArgs, } from "../utils
 import { ensureValidToken, formatHttpError } from "../auth/oauth.js";
 import { createKnowledgeNetwork, createObjectTypes, deleteKnowledgeNetwork, buildKnowledgeNetwork, getBuildStatus, } from "../api/knowledge-networks.js";
 import { listTablesWithColumns, scanDatasourceMetadata } from "../api/vega.js";
-import { createDataView, findDataView } from "../api/dataviews.js";
+import { createResource, findResource } from "../api/resources.js";
 import { resolveFiles } from "./ds.js";
 import { buildTableName } from "./import-csv.js";
 import { downloadBkn, uploadBkn, listActionSchedules, getActionSchedule, createActionSchedule, updateActionSchedule, setActionScheduleStatus, deleteActionSchedules, listJobs, getJob, getJobTasks, deleteJobs, } from "../api/bkn-backend.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { runDsImportCsv } from "./ds.js";
+import { renderHelp } from "../help/format.js";
+import { warnDeprecated } from "../utils/deprecation.js";
 import { pollWithBackoff, detectDisplayKey, formatPkDetectionError, parsePkMap, resolvePrimaryKey, confirmYes, assertVegaCatalogId, } from "./bkn-utils.js";
 // ── BKN object name validation ──────────────────────────────────────────────
 // Mirrors bkn-backend OBJECT_NAME_MAX_LENGTH (interfaces/common.go:28) and
@@ -35,15 +37,22 @@ export function assertValidBknObjectNames(names, context) {
         `(1..${BKN_OBJECT_NAME_MAX_LENGTH} utf-8 chars):\n${lines.join("\n")}`);
 }
 // ── Build ───────────────────────────────────────────────────────────────────
-const KN_BUILD_HELP = `kweaver bkn build <kn-id> [options]
-
-Trigger a full build for a knowledge network.
-
-Options:
-  --wait (default)     Poll until build completes
-  --no-wait            Return immediately after triggering
-  --timeout <seconds>  Max wait time when --wait (default: 300)
-  -bd, --biz-domain    Business domain (default: bd_public)`;
+const KN_BUILD_HELP = renderHelp({
+    tagline: "Trigger a full build for a knowledge network",
+    usage: "kweaver bkn build <kn-id> [flags]",
+    flags: [
+        { name: "--wait", desc: "Poll until build completes (default)" },
+        { name: "--no-wait", desc: "Return immediately after triggering" },
+        { name: "--timeout <seconds>", desc: "Max wait time when --wait (default: 300)" },
+        { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn build kn-123",
+        "kweaver bkn build kn-123 --no-wait",
+        "kweaver bkn build kn-123 --wait --timeout 600",
+    ],
+});
 export function parseKnBuildArgs(args) {
     let knId = "";
     let wait = true;
@@ -349,25 +358,52 @@ export function extractTarToDirectory(tarBuffer, dirPath) {
         throw new Error(`tar extract failed: ${result.stderr?.toString() ?? result.status}`);
     }
 }
-const KN_PUSH_HELP = `kweaver bkn push <directory> [options]
-
-Pack a BKN directory into a tar and upload to import as a knowledge network.
-
-Options:
-  --branch <s>       Branch name (default: main)
-  -bd, --biz-domain  Business domain (default: bd_public)
-  --pretty           Pretty-print JSON output
-  --detect-encoding  Detect .bkn encoding and normalize to UTF-8 (default: on)
-  --no-detect-encoding  Do not detect; require UTF-8 .bkn files
-  --source-encoding <name>  Decode all .bkn files with this encoding (e.g. gb18030); overrides detection`;
-const KN_PULL_HELP = `kweaver bkn pull <kn-id> [<directory>] [options]
-
-Download a BKN tar from a knowledge network and extract to a local directory.
-
-Options:
-  <directory>        Output directory (default: <kn-id>)
-  --branch <s>       Branch name (default: main)
-  -bd, --biz-domain  Business domain (default: bd_public)`;
+const KN_PUSH_HELP = renderHelp({
+    tagline: "Pack a BKN directory into a tar and upload to import as a knowledge network",
+    usage: "kweaver bkn push <directory> [flags]",
+    flags: [
+        {
+            title: "Target",
+            flags: [
+                { name: "--branch <s>", desc: "Branch name (default: main)" },
+                { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+            ],
+        },
+        {
+            title: "Encoding",
+            flags: [
+                { name: "--detect-encoding", desc: "Detect .bkn encoding and normalize to UTF-8 (default: on)" },
+                { name: "--no-detect-encoding", desc: "Do not detect; require UTF-8 .bkn files" },
+                { name: "--source-encoding <name>", desc: "Decode all .bkn files with this encoding, e.g. gb18030 (overrides detection)" },
+            ],
+        },
+        {
+            title: "Output",
+            flags: [{ name: "--pretty", desc: "Pretty-print JSON output" }],
+        },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn push ./my-network",
+        "kweaver bkn push ./my-network --branch feature/v2",
+        "kweaver bkn push ./legacy --source-encoding gb18030",
+    ],
+});
+const KN_PULL_HELP = renderHelp({
+    tagline: "Download a BKN tar from a knowledge network and extract to a local directory",
+    usage: "kweaver bkn pull <kn-id> [<directory>] [flags]",
+    flags: [
+        { name: "<directory>", desc: "Output directory (default: <kn-id>)" },
+        { name: "--branch <s>", desc: "Branch name (default: main)" },
+        { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn pull kn-123",
+        "kweaver bkn pull kn-123 ./out",
+        "kweaver bkn pull kn-123 ./out --branch feature/v2",
+    ],
+});
 export async function runKnPushCommand(args) {
     let options;
     try {
@@ -472,24 +508,47 @@ export async function runKnPullCommand(args) {
         return 1;
     }
 }
-// ── Create from datasource ──────────────────────────────────────────────────
-const KN_CREATE_FROM_DS_HELP = `kweaver bkn create-from-ds <vega-catalog-id> --name X [options]
-
-Create a knowledge network from a vega catalog datasource (dataviews + object types + optional build).
-<vega-catalog-id> is a vega catalog id (use \`kweaver vega catalog list\` to find one;
-legacy data-connection datasource UUIDs are no longer accepted).
-
-Options:
-  --name <s>       Knowledge network name (required)
-  --tables <a,b>   Comma-separated table names (default: all)
-  --pk-map <s>     Explicit primary keys: <table>:<field>[,<table>:<field>...]
-                   Required when auto-detection fails (no unique column in sample)
-  --build (default)  Build after creation
-  --no-build       Skip build after creation
-  --timeout <n>    Build timeout in seconds (default: 300)
-  --no-rollback    Keep partially-created KN on failure (debug; default: rollback)
-  -bd, --biz-domain  Business domain (default: bd_public)
-  --pretty         Pretty-print output (default)`;
+// ── Create from catalog (formerly create-from-ds) ──────────────────────────
+const CREATE_FROM_CATALOG_FLAGS = [
+    { name: "--name <s>", desc: "Knowledge network name (required)" },
+    { name: "--tables <a,b>", desc: "Comma-separated table names (default: all)" },
+    { name: "--pk-map <s>", desc: "Explicit primary keys <table>:<field>[,...]; required when auto-detection fails" },
+    { name: "--build", desc: "Build after creation (default)" },
+    { name: "--no-build", desc: "Skip build after creation" },
+    { name: "--timeout <n>", desc: "Build timeout in seconds (default: 300)" },
+    { name: "--no-rollback", desc: "Keep partially-created KN on failure (debug; default: rollback)" },
+    { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+    { name: "--pretty", desc: "Pretty-print output (default)" },
+];
+const KN_CREATE_FROM_CATALOG_HELP = renderHelp({
+    tagline: "Create a knowledge network from a vega catalog (resources + object types + optional build).",
+    usage: "kweaver bkn create-from-catalog <vega-catalog-id> --name X [flags]",
+    flags: CREATE_FROM_CATALOG_FLAGS,
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn create-from-catalog vcat-123 --name customers",
+        "kweaver bkn create-from-catalog vcat-123 --name orders --tables orders,items --no-build",
+    ],
+    learnMore: [
+        "<vega-catalog-id> is a vega catalog id (use `kweaver vega catalog list` to find one)",
+        "Legacy data-connection datasource UUIDs are no longer accepted",
+        "`kweaver bkn create-from-ds` is kept as a deprecated alias for back-compat",
+    ],
+});
+const KN_CREATE_FROM_DS_HELP = renderHelp({
+    tagline: "[DEPRECATED] Alias for `kweaver bkn create-from-catalog`. Subcommand name retained for back-compat; flags and behavior identical.",
+    usage: "kweaver bkn create-from-ds <vega-catalog-id> --name X [flags]",
+    flags: CREATE_FROM_CATALOG_FLAGS,
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn create-from-ds vcat-123 --name customers",
+        "kweaver bkn create-from-ds vcat-123 --name orders --tables orders,items --no-build",
+    ],
+    learnMore: [
+        "Prefer `kweaver bkn create-from-catalog` in new scripts.",
+        "<vega-catalog-id> is a vega catalog id (use `kweaver vega catalog list` to find one).",
+    ],
+});
 export function parseKnCreateFromDsArgs(args) {
     let dsId = "";
     let name = "";
@@ -548,7 +607,7 @@ export function parseKnCreateFromDsArgs(args) {
     }
     const tables = tablesStr ? tablesStr.split(",").map((s) => s.trim()).filter(Boolean) : [];
     if (!dsId || !name) {
-        throw new Error("Usage: kweaver bkn create-from-ds <ds-id> --name X [options]");
+        throw new Error("Usage: kweaver bkn create-from-catalog <vega-catalog-id> --name X [options]");
     }
     assertVegaCatalogId(dsId);
     const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
@@ -564,7 +623,7 @@ function sanitizeBknId(name) {
 export function generateObjectTypeBkn(tableName, dvId, pk, dk, columns) {
     const safeId = sanitizeBknId(tableName);
     const header = `## ObjectType: ${safeId}\n\n**${tableName}**\n`;
-    const dsTable = `### Data Source\n\n| Type | ID | Name |\n|------|-----|------|\n| data_view | ${dvId} | ${tableName} |\n`;
+    const dsTable = `### Data Source\n\n| Type | ID | Name |\n|------|-----|------|\n| resource | ${dvId} | ${tableName} |\n`;
     const dpHeader = `### Data Properties\n\n| Property | Display Name | Type | Primary Key | Display Key |\n|----------|-------------|------|-------------|-------------|\n`;
     const dpRows = columns.map((c) => {
         const isPk = c.name === pk ? "yes" : "no";
@@ -574,19 +633,23 @@ export function generateObjectTypeBkn(tableName, dvId, pk, dk, columns) {
     const frontmatter = `---\ntype: object_type\nid: ${safeId}\nname: ${tableName}\n---\n\n`;
     return `${frontmatter}${header}\n${dsTable}\n${dpHeader}${dpRows}\n`;
 }
-export async function runKnCreateFromDsCommand(args, sampleRows) {
+export async function runKnCreateFromCatalogCommand(args, sampleRows, invokedAs = "create-from-catalog") {
+    const help = invokedAs === "create-from-ds" ? KN_CREATE_FROM_DS_HELP : KN_CREATE_FROM_CATALOG_HELP;
     let options;
     try {
         options = parseKnCreateFromDsArgs(args);
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(KN_CREATE_FROM_DS_HELP);
+            console.log(help);
             return 0;
         }
         console.error(formatHttpError(error));
         return 1;
     }
+    if (invokedAs === "create-from-ds") {
+        warnDeprecated("kweaver bkn create-from-ds", "renamed to `kweaver bkn create-from-catalog`. The old name is kept as an alias and will be removed in a future major release.");
+    }
     try {
         const token = await ensureValidToken();
         const base = {
@@ -667,12 +730,12 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
                 sampleSize: resolution.sampleSize ?? 0,
             }));
         }
-        // Phase 1: Create DataViews for each table. findDataView is idempotent;
+        // Phase 1: Create vega-backend Resources for each table. findResource is idempotent;
         // not tracked for rollback so a retry can reuse what's already there.
-        console.error(`Creating data views for ${targetTables.length} table(s) ...`);
+        console.error(`Creating resources for ${targetTables.length} table(s) ...`);
         const viewMap = {};
         for (const t of targetTables) {
-            const found = await findDataView({
+            const found = await findResource({
                 ...base,
                 name: t.name,
                 datasourceId: options.dsId,
@@ -680,7 +743,7 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
                 wait: true,
             });
             const dvId = found[0]?.id ??
-                (await createDataView({
+                (await createResource({
                     ...base,
                     name: t.name,
                     datasourceId: options.dsId,
@@ -717,7 +780,7 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
                 return {
                     branch: "main",
                     name: t.name,
-                    data_source: { type: "data_view", id: viewMap[t.name] },
+                    data_source: { type: "resource", id: viewMap[t.name] },
                     primary_keys: [pk],
                     display_key: dk,
                     data_properties: t.columns.map((c) => ({
@@ -806,24 +869,32 @@ export async function runKnCreateFromDsCommand(args, sampleRows) {
     }
 }
 // ── Create from CSV ─────────────────────────────────────────────────────────
-const KN_CREATE_FROM_CSV_HELP = `kweaver bkn create-from-csv <vega-catalog-id> --files <glob> --name X [options]
-
-Import CSV files into a vega catalog datasource, then create a knowledge network.
-<vega-catalog-id> is a vega catalog id (use \`kweaver vega catalog list\` to find one;
-legacy data-connection datasource UUIDs are no longer accepted).
-
-Options:
-  --files <s>          CSV file paths (comma-separated or glob, required)
-  --name <s>           Knowledge network name (required)
-  --table-prefix <s>   Table name prefix (default: none)
-  --batch-size <n>     Rows per batch (default: 500)
-  --tables <a,b>       Tables to include in KN (default: all imported)
-  --build (default)    Build after creation
-  --no-build           Skip build
-  --pk-map <s>         Explicit primary keys: <table>:<field>[,<table>:<field>...]
-  --timeout <n>        Build timeout in seconds (default: 300)
-  --no-rollback        Keep partially-created KN on failure (debug; default: rollback)
-  -bd, --biz-domain    Business domain (default: bd_public)`;
+const KN_CREATE_FROM_CSV_HELP = renderHelp({
+    tagline: "Import CSV files into a vega catalog datasource, then create a knowledge network",
+    usage: "kweaver bkn create-from-csv <vega-catalog-id> --files <glob> --name X [flags]",
+    flags: [
+        { name: "--files <s>", desc: "CSV file paths (comma-separated or glob, required)" },
+        { name: "--name <s>", desc: "Knowledge network name (required)" },
+        { name: "--table-prefix <s>", desc: "Table name prefix (default: none)" },
+        { name: "--batch-size <n>", desc: "Rows per batch (default: 500)" },
+        { name: "--tables <a,b>", desc: "Tables to include in KN (default: all imported)" },
+        { name: "--build", desc: "Build after creation (default)" },
+        { name: "--no-build", desc: "Skip build" },
+        { name: "--pk-map <s>", desc: "Explicit primary keys <table>:<field>[,...]" },
+        { name: "--timeout <n>", desc: "Build timeout in seconds (default: 300)" },
+        { name: "--no-rollback", desc: "Keep partially-created KN on failure (debug; default: rollback)" },
+        { name: "-bd, --biz-domain <s>", desc: "Business domain (default: bd_public)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn create-from-csv vcat-123 --files './data/*.csv' --name imports",
+        "kweaver bkn create-from-csv vcat-123 --files ./a.csv,./b.csv --name two --table-prefix raw_",
+    ],
+    learnMore: [
+        "<vega-catalog-id> is a vega catalog id (use `kweaver vega catalog list` to find one)",
+        "Legacy data-connection datasource UUIDs are no longer accepted",
+    ],
+});
 export function parseKnCreateFromCsvArgs(args) {
     let dsId = "";
     let files = "";
@@ -894,7 +965,7 @@ export function parseKnCreateFromCsvArgs(args) {
     }
     const tables = tablesStr ? tablesStr.split(",").map((s) => s.trim()).filter(Boolean) : [];
     if (!dsId || !files || !name) {
-        throw new Error("Usage: kweaver bkn create-from-csv <ds-id> --files <glob> --name X [options]");
+        throw new Error("Usage: kweaver bkn create-from-csv <vega-catalog-id> --files <glob> --name X [options]");
     }
     assertVegaCatalogId(dsId);
     const pkMap = pkMapStr ? parsePkMap(pkMapStr) : {};
@@ -944,7 +1015,7 @@ export async function runKnCreateFromCsvCommand(args) {
         return importResult.code;
     }
     // (Phase 1.5 metadata scan removed — runDsImportCsv now self-scans on
-    // success, and runKnCreateFromDsCommand's table-discovery retry triggers
+    // success, and runKnCreateFromCatalogCommand's table-discovery retry triggers
     // a scan if the catalog still lags. Two layers of fallback are enough.)
     // Phase 2: Create KN from datasource
     console.error("Phase 2: Creating knowledge network ...");
@@ -966,7 +1037,7 @@ export async function runKnCreateFromCsvCommand(args) {
             : []),
         ...(options.noRollback ? ["--no-rollback"] : []),
     ];
-    return runKnCreateFromDsCommand(knArgs, importResult.sampleRows);
+    return runKnCreateFromCatalogCommand(knArgs, importResult.sampleRows, "create-from-catalog");
 }
 export function parseActionScheduleArgs(args) {
     const [action, ...rest] = args;
@@ -1008,15 +1079,30 @@ export async function runKnActionScheduleCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver bkn action-schedule <action> <kn-id> [args] [--pretty] [-bd value]
-
-Actions:
-  list <kn-id>                                    List action schedules
-  get <kn-id> <schedule-id>                       Get schedule details
-  create <kn-id> '<json>'                         Create schedule
-  update <kn-id> <schedule-id> '<json>'           Update schedule
-  set-status <kn-id> <schedule-id> <status>       Enable/disable schedule (enabled|disabled)
-  delete <kn-id> <schedule-ids> [-y]              Delete schedule(s) (comma-separated)`);
+            console.log(renderHelp({
+                tagline: "Manage action schedules for a KN",
+                usage: "kweaver bkn action-schedule <action> <kn-id> [args] [--pretty] [-bd value]",
+                sections: [{
+                        title: "AVAILABLE COMMANDS",
+                        items: [
+                            { name: "list", desc: "List action schedules" },
+                            { name: "get", desc: "Get schedule details" },
+                            { name: "create", desc: "Create schedule" },
+                            { name: "update", desc: "Update schedule" },
+                            { name: "set-status", desc: "Enable/disable schedule (enabled|disabled)" },
+                            { name: "delete", desc: "Delete schedule(s) (comma-separated)" },
+                        ],
+                    }],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: [
+                    "kweaver bkn action-schedule list <kn-id>",
+                    "kweaver bkn action-schedule get <kn-id> <schedule-id>",
+                    "kweaver bkn action-schedule create <kn-id> '<json>'",
+                    "kweaver bkn action-schedule update <kn-id> <schedule-id> '<json>'",
+                    "kweaver bkn action-schedule set-status <kn-id> <schedule-id> <status>",
+                    "kweaver bkn action-schedule delete <kn-id> <schedule-ids> [-y]",
+                ],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));
@@ -1125,13 +1211,26 @@ export async function runKnJobCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver bkn job <action> <kn-id> [args] [--pretty] [-bd value]
-
-Actions:
-  list <kn-id>                    List jobs
-  get <kn-id> <job-id>            Get job details
-  tasks <kn-id> <job-id>          List tasks within a job
-  delete <kn-id> <job-ids> [-y]   Delete job(s) (comma-separated)`);
+            console.log(renderHelp({
+                tagline: "Manage jobs for a KN",
+                usage: "kweaver bkn job <action> <kn-id> [args] [--pretty] [-bd value]",
+                sections: [{
+                        title: "AVAILABLE COMMANDS",
+                        items: [
+                            { name: "list", desc: "List jobs" },
+                            { name: "get", desc: "Get job details" },
+                            { name: "tasks", desc: "List tasks within a job" },
+                            { name: "delete", desc: "Delete job(s) (comma-separated)" },
+                        ],
+                    }],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: [
+                    "kweaver bkn job list <kn-id>",
+                    "kweaver bkn job get <kn-id> <job-id>",
+                    "kweaver bkn job tasks <kn-id> <job-id>",
+                    "kweaver bkn job delete <kn-id> <job-ids> [-y]",
+                ],
+            }));
             return 0;
         }
         console.error(formatHttpError(error));

package/dist/commands/bkn-query.js

@@ -5,6 +5,7 @@ import { semanticSearch } from "../api/semantic-search.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
 import { parseOntologyQueryFlags } from "./bkn-utils.js";
+import { renderHelp } from "../help/format.js";
 // ── subgraph ─────────────────────────────────────────────────────────────────
 export async function runKnSubgraphCommand(args) {
     let filteredArgs;
@@ -18,9 +19,18 @@ export async function runKnSubgraphCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver bkn subgraph <kn-id> '<json>' [--pretty] [-bd value]
-
-Query subgraph via ontology-query API. JSON body format see references/json-formats.md#subgraph.`);
+            console.log(renderHelp({
+                tagline: "Query subgraph via ontology-query API. JSON body format see references/json-formats.md#subgraph.",
+                usage: "kweaver bkn subgraph <kn-id> '<json>' [flags]",
+                flags: [
+                    { name: "--pretty", desc: "Pretty-print JSON output" },
+                    { name: "-bd, --biz-domain <s>", desc: "Override x-business-domain" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: [
+                    "kweaver bkn subgraph kn-123 '{\"source_object_type_id\":\"ot-1\"}'",
+                ],
+            }));
             return 0;
         }
         throw error;
@@ -80,9 +90,18 @@ export async function runKnActionExecutionCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver bkn action-execution get <kn-id> <execution-id> [--pretty] [-bd value]
-
-Get action execution status.`);
+            console.log(renderHelp({
+                tagline: "Get action execution status.",
+                usage: "kweaver bkn action-execution get <kn-id> <execution-id> [flags]",
+                flags: [
+                    { name: "--pretty", desc: "Pretty-print JSON output" },
+                    { name: "-bd, --biz-domain <s>", desc: "Override x-business-domain" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: [
+                    "kweaver bkn action-execution get kn-123 exec-456",
+                ],
+            }));
             return 0;
         }
         throw error;
@@ -113,12 +132,29 @@ Get action execution status.`);
 export async function runKnActionLogCommand(args) {
     const [action, ...rest] = args;
     if (!action || action === "--help" || action === "-h") {
-        console.log(`kweaver bkn action-log list <kn-id> [options]
-kweaver bkn action-log get <kn-id> <log-id> [options]
-kweaver bkn action-log cancel <kn-id> <log-id> [options]
-
-List/get execution logs. cancel has side effects - only use when explicitly requested.
-Options for list: --limit, --need-total, --action-type-id, --status, --trigger-type, --search-after`);
+        console.log(renderHelp({
+            tagline: "List/get execution logs. cancel has side effects - only use when explicitly requested.",
+            usage: [
+                "kweaver bkn action-log list <kn-id> [flags]",
+                "kweaver bkn action-log get <kn-id> <log-id> [flags]",
+                "kweaver bkn action-log cancel <kn-id> <log-id> [flags]",
+            ],
+            flags: [
+                { name: "--limit <n>", desc: "Max log entries (list, default: 30)" },
+                { name: "--need-total <bool>", desc: "Include total count (list)" },
+                { name: "--action-type-id <s>", desc: "Filter by action type id (list)" },
+                { name: "--status <s>", desc: "Filter by status (list)" },
+                { name: "--trigger-type <s>", desc: "Filter by trigger type (list)" },
+                { name: "--search-after <s>", desc: "Pagination cursor (list)" },
+                { name: "--pretty", desc: "Pretty-print JSON output" },
+                { name: "-bd, --biz-domain <s>", desc: "Override x-business-domain" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver bkn action-log list kn-123 --limit 10",
+                "kweaver bkn action-log get kn-123 log-456",
+            ],
+        }));
         return 0;
     }
     let pretty = true;
@@ -233,16 +269,21 @@ Options for list: --limit, --need-total, --action-type-id, --status, --trigger-t
     }
 }
 // ── search ───────────────────────────────────────────────────────────────────
-const KN_SEARCH_HELP = `kweaver bkn search <kn-id> <query> [--max-concepts <n>] [--mode <mode>] [--pretty] [-bd value]
-
-Semantic search within a knowledge network via agent-retrieval API.
-Returns matched concepts (object types, relation types, action types).
-
-Options:
-  --max-concepts <n>   Max concepts to return (default: 10)
-  --mode <mode>        Search mode (default: keyword_vector_retrieval)
-  --pretty             Pretty-print JSON output
-  -bd, --biz-domain    Override x-business-domain`;
+const KN_SEARCH_HELP = renderHelp({
+    tagline: "Semantic search within a knowledge network — matches object/relation/action types (agent-retrieval API)",
+    usage: "kweaver bkn search <kn-id> <query> [flags]",
+    flags: [
+        { name: "--max-concepts <n>", desc: "Max concepts to return (default: 10)" },
+        { name: "--mode <mode>", desc: "Search mode (default: keyword_vector_retrieval)" },
+        { name: "--pretty", desc: "Pretty-print JSON output" },
+        { name: "-bd, --biz-domain <s>", desc: "Override x-business-domain" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn search kn-123 'customer churn'",
+        "kweaver bkn search kn-123 'revenue by region' --max-concepts 20",
+    ],
+});
 export function parseKnSearchArgs(args) {
     let knId = "";
     let query = "";
@@ -324,18 +365,36 @@ export async function runKnRelationTypePathsCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver bkn relation-type-paths <kn-id> '<json>' [--pretty] [-bd value]
-
-Query relation type paths between object types.`);
+            console.log(renderHelp({
+                tagline: "Query relation type paths between object types.",
+                usage: "kweaver bkn relation-type-paths <kn-id> '<json>' [flags]",
+                flags: [
+                    { name: "--pretty", desc: "Pretty-print JSON output" },
+                    { name: "-bd, --biz-domain <s>", desc: "Override x-business-domain" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: [
+                    "kweaver bkn relation-type-paths kn-123 '{...}'",
+                ],
+            }));
             return 0;
         }
         throw error;
     }
     const [knId, body] = parsed.filteredArgs;
     if (!knId || !body) {
-        console.log(`kweaver bkn relation-type-paths <kn-id> '<json>' [--pretty] [-bd value]
-
-Query relation type paths between object types.`);
+        console.log(renderHelp({
+            tagline: "Query relation type paths between object types.",
+            usage: "kweaver bkn relation-type-paths <kn-id> '<json>' [flags]",
+            flags: [
+                { name: "--pretty", desc: "Pretty-print JSON output" },
+                { name: "-bd, --biz-domain <s>", desc: "Override x-business-domain" },
+            ],
+            inheritedFlags: "--base-url, --token, --user, --help",
+            examples: [
+                "kweaver bkn relation-type-paths kn-123 '{...}'",
+            ],
+        }));
         return knId && !body ? 1 : 0;
     }
     const token = await ensureValidToken();
@@ -357,9 +416,18 @@ export async function runKnResourcesCommand(args) {
     }
     catch (error) {
         if (error instanceof Error && error.message === "help") {
-            console.log(`kweaver bkn resources [--pretty] [-bd value]
-
-List available resources.`);
+            console.log(renderHelp({
+                tagline: "List available resources.",
+                usage: "kweaver bkn resources [flags]",
+                flags: [
+                    { name: "--pretty", desc: "Pretty-print JSON output" },
+                    { name: "-bd, --biz-domain <s>", desc: "Override x-business-domain" },
+                ],
+                inheritedFlags: "--base-url, --token, --user, --help",
+                examples: [
+                    "kweaver bkn resources --pretty",
+                ],
+            }));
             return 0;
         }
         throw error;

package/dist/commands/bkn-schema.d.ts

@@ -22,13 +22,13 @@ export type ObjectTypeCreateParsed = {
 } | {
     mode: "needsDataview";
     knId: string;
-    dataviewId: string;
+    resourceId: string;
     entry: Record<string, unknown>;
     businessDomain: string;
     branch: string;
     pretty: boolean;
 };
-/** Parse object-type create args: --name --dataview-id --primary-key --display-key [--property '<json>' ...] */
+/** Parse object-type create args: --name --resource-id --primary-key --display-key [--property '<json>' ...] */
 export declare function parseObjectTypeCreateArgs(args: string[]): ObjectTypeCreateParsed;
 /**
  * Load dataview fields and build data_properties (with mapped_field). Used when no --property flags.
@@ -36,7 +36,7 @@ export declare function parseObjectTypeCreateArgs(args: string[]): ObjectTypeCre
 export declare function finalizeObjectTypeCreateFromDataview(options: {
     baseUrl: string;
     accessToken: string;
-    dataviewId: string;
+    resourceId: string;
     entry: Record<string, unknown>;
     businessDomain: string;
 }): Promise<string>;