@kweaver-ai/kweaver-sdk 0.8.2 → 0.8.3

package/dist/commands/bkn.js

@@ -4,6 +4,7 @@ import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/
 import { listKnowledgeNetworks, getKnowledgeNetwork, createKnowledgeNetwork, updateKnowledgeNetwork, deleteKnowledgeNetwork, } from "../api/knowledge-networks.js";
 import { formatCallOutput } from "./call.js";
 import { resolveBusinessDomain } from "../config/store.js";
+import { renderHelp } from "../help/format.js";
 import { runKnObjectTypeCommand, runKnRelationTypeCommand, runKnActionTypeCommand, runKnConceptGroupCommand, } from "./bkn-schema.js";
 import { runKnSubgraphCommand, runKnActionExecutionCommand, runKnActionLogCommand, runKnSearchCommand, runKnRelationTypePathsCommand, runKnResourcesCommand, } from "./bkn-query.js";
 import { runKnBuildCommand, runKnValidateCommand, runKnPushCommand, runKnPullCommand, runKnCreateFromDsCommand, runKnCreateFromCsvCommand, runKnActionScheduleCommand, runKnJobCommand, } from "./bkn-ops.js";
@@ -357,57 +358,77 @@ export function parseKnDeleteArgs(args) {
         businessDomain = resolveBusinessDomain();
     return { knId, businessDomain, yes };
 }
-const KN_HELP = `kweaver bkn
-
-Subcommands:
-  list [options]       List business knowledge networks
-  get <kn-id> [options]   Get knowledge network detail (use --stats or --export)
-  create [options]     Create a knowledge network (empty or from --body-file)
-  create-from-ds <ds-id> --name X [--tables a,b] [--build]   Create KN from datasource
-  create-from-csv <ds-id> --files <glob> --name X [--table-prefix P] [--build]
-    Import CSVs then create knowledge network
-  update <kn-id> [options]  Update a knowledge network
-  delete <kn-id>       Delete a knowledge network
-  build <kn-id> [--wait|--no-wait] [--timeout n]   Trigger full build
-  validate <directory> [--detect-encoding|--no-detect-encoding] [--source-encoding n]   Validate local BKN (no upload)
-  push <directory> [--branch main] [--detect-encoding|--no-detect-encoding] [--source-encoding n]   Upload BKN as tar
-  pull <kn-id> [<directory>] [--branch main]   Download BKN tar and extract
-  export <kn-id>       Export knowledge network (alias for get --export)
-  stats <kn-id>        Get statistics (alias for get --stats)
-  search <kn-id> <query> [options]   Semantic search within a knowledge network
-  object-type list <kn-id>   List object types (schema)
-  object-type get <kn-id> <ot-id>   Get object type details
-  object-type create <kn-id> [options]   Create object type (--name --dataview-id --primary-key --display-key)
-  object-type update <kn-id> <ot-id> [options]   Update object type
-  object-type delete <kn-id> <ot-ids> [-y]   Delete object type(s)
-  object-type query <kn-id> <ot-id> ['<json>']   Query object instances (ontology-query; supports --limit/--search-after)
-  object-type properties <kn-id> <ot-id> '<json>'   Query instance properties (json: {"_instance_identities":[{pk:val}],"properties":[...]})
-  relation-type list <kn-id>   List relation types (schema)
-  relation-type get <kn-id> <rt-id>   Get relation type details
-  relation-type create <kn-id> [options]   Create relation type (--name --source --target [--mapping src:tgt])
-  relation-type update <kn-id> <rt-id> --source <ot-id> --target <ot-id> [--name X] [--type direct|data_view] [--mapping src:tgt ...]   Update relation type
-  relation-type delete <kn-id> <rt-ids> [-y]   Delete relation type(s)
-  subgraph <kn-id> '<json>'   Query subgraph
-  action-type list <kn-id>   List action types (schema)
-  action-type get <kn-id> <at-id>   Get action type details
-  action-type create <kn-id> '<json>'   Create action type
-  action-type update <kn-id> <at-id> '<json>'   Update action type
-  action-type delete <kn-id> <at-ids> [-y]   Delete action type(s)
-  action-type query <kn-id> <at-id> '<json>'   Query action info
-  action-type inputs <kn-id> <at-id>   List value_from=input params + dynamic_params template
-  action-type execute <kn-id> <at-id> '<envelope-json>' | --dynamic-params '<json>' [--instance '<json>']... [--trigger-type <v>]   Execute action (has side effects)
-  action-execution get <kn-id> <execution-id>   Get execution status
-  action-log list <kn-id> [options]   List action execution logs
-  action-log get <kn-id> <log-id>   Get single execution log
-  action-log cancel <kn-id> <log-id>   Cancel running execution (has side effects)
-  concept-group list|get|create|update|delete|add-members|remove-members <kn-id> ...
-  action-schedule list|get|create|update|set-status|delete <kn-id> ...
-  job list|get|tasks|delete <kn-id> ...
-  relation-type-paths <kn-id> '<json>'   Query relation type paths between OTs
-  resources                              List available resources
-  metric list|get|create|search|validate|update|delete|query|dry-run <kn-id> ...   BKN metrics (definitions + data)
-
-Use 'kweaver bkn <subcommand> --help' for subcommand options.`;
+const KN_HELP = renderHelp({
+    tagline: "Knowledge network — build, validate, push/pull, schema, instances, actions, metrics",
+    usage: "kweaver bkn <subcommand> [args] [flags]",
+    sections: [
+        {
+            title: "LIFECYCLE",
+            items: [
+                { name: "list", desc: "List knowledge networks" },
+                { name: "get", desc: "Get KN detail (use --stats or --export)" },
+                { name: "create", desc: "Create a KN (empty or from --body-file)" },
+                { name: "create-from-ds", desc: "Create KN from datasource (--name --tables --build)" },
+                { name: "create-from-csv", desc: "Import CSVs then create KN (--files glob --name --build)" },
+                { name: "update", desc: "Update a KN" },
+                { name: "delete", desc: "Delete a KN" },
+                { name: "build", desc: "Trigger full build (--wait / --timeout)" },
+                { name: "stats", desc: "Get statistics (alias for `get --stats`)" },
+                { name: "export", desc: "Export KN (alias for `get --export`)" },
+            ],
+        },
+        {
+            title: "LOCAL DIRECTORY",
+            items: [
+                { name: "validate", desc: "Validate local BKN directory (no upload)" },
+                { name: "push", desc: "Upload BKN directory as tar" },
+                { name: "pull", desc: "Download BKN tar and extract" },
+            ],
+        },
+        {
+            title: "SCHEMA",
+            items: [
+                { name: "object-type", desc: "list / get / create / update / delete / query / properties" },
+                { name: "relation-type", desc: "list / get / create / update / delete" },
+                { name: "relation-type-paths", desc: "Query relation-type paths between object types" },
+                { name: "action-type", desc: "list / get / create / update / delete / query / inputs / execute" },
+                { name: "concept-group", desc: "list / get / create / update / delete / add-members / remove-members" },
+                { name: "metric", desc: "list / get / create / search / validate / update / delete / query / dry-run" },
+            ],
+        },
+        {
+            title: "INSTANCES / SEARCH",
+            items: [
+                { name: "search", desc: "Semantic search within a KN" },
+                { name: "subgraph", desc: "Query subgraph (JSON body)" },
+            ],
+        },
+        {
+            title: "EXECUTION / JOBS",
+            items: [
+                { name: "action-execution", desc: "get — execution status" },
+                { name: "action-log", desc: "list / get / cancel" },
+                { name: "action-schedule", desc: "list / get / create / update / set-status / delete" },
+                { name: "job", desc: "list / get / tasks / delete" },
+            ],
+        },
+        {
+            title: "MISC",
+            items: [{ name: "resources", desc: "List available resources" }],
+        },
+    ],
+    inheritedFlags: "--base-url, --token, --user, -bd, --help",
+    examples: [
+        "kweaver bkn list",
+        "kweaver bkn build <kn-id> --wait",
+        "kweaver bkn push ./my-network --branch main",
+        "kweaver bkn search <kn-id> 'customer churn'",
+    ],
+    learnMore: [
+        "Use `kweaver bkn <subcommand> --help` for action-level options",
+        "Use `kweaver help all` for full per-action signatures",
+    ],
+});
 export async function runKnCommand(args) {
     const [subcommand, ...rest] = args;
     if (!subcommand || subcommand === "--help" || subcommand === "-h") {
@@ -522,69 +543,87 @@ async function runKnListCommand(args) {
         return 1;
     }
 }
-const KN_LIST_HELP = `kweaver bkn list [options]
-
-List business knowledge networks from the ontology-manager API.
-
-Options:
-  --offset <n>       Offset (default: 0)
-  --limit <n>        Limit (default: 30)
-  --sort <key>       Sort field (default: update_time)
-  --direction <asc|desc>  Sort direction (default: desc)
-  --name-pattern <s> Filter by name pattern
-  --tag <s>          Filter by tag
-  --detail           Include the detail field in simplified output
-  --verbose, -v      Show full JSON response
-  -bd, --biz-domain <value>  Business domain (default: bd_public)
-  --pretty           Pretty-print JSON output (applies to both modes)`;
-const KN_GET_HELP = `kweaver bkn get <kn-id> [options]
-
-Get knowledge network detail.
-
-Options:
-  --stats            Include statistics
-  --export           Export mode (include sub-types)
-  -bd, --biz-domain <value>  Business domain (default: bd_public)
-  --pretty           Pretty-print JSON output`;
-const KN_CREATE_HELP = `kweaver bkn create [options]
-
-Create a knowledge network.
-
-Options:
-  --name <s>         Name (required unless --body-file)
-  --comment <s>      Comment
-  --tags <t1,t2>     Comma-separated tags
-  --icon <s>         Icon
-  --color <s>        Color
-  --branch <s>       Branch (default: main)
-  --base-branch <s>  Base branch (default: empty for main)
-  --body-file <path> Read full JSON body from file (cannot combine with flags above)
-  --import-mode <normal|ignore|overwrite>  Import mode (default: normal)
-  --validate-dependency <true|false>  Validate dependency (default: true)
-  -bd, --biz-domain <value>  Business domain (default: bd_public)
-  --pretty           Pretty-print JSON output`;
-const KN_UPDATE_HELP = `kweaver bkn update <kn-id> [options]
-
-Update a knowledge network.
-
-Options:
-  --name <s>         Name (required unless --body-file)
-  --comment <s>      Comment
-  --tags <t1,t2>     Comma-separated tags
-  --icon <s>         Icon
-  --color <s>        Color
-  --branch <s>       Branch (default: main)
-  --base-branch <s>  Base branch (default: empty for main)
-  --body-file <path> Read full JSON body from file (cannot combine with flags above)
-  -bd, --biz-domain <value>  Business domain (default: bd_public)
-  --pretty           Pretty-print JSON output`;
-const KN_DELETE_HELP = `kweaver bkn delete <kn-id>
-
-Delete a knowledge network and its object types, relation types, action types, and concept groups.
-
-Options:
-  --yes, -y          Skip confirmation prompt
-  -bd, --biz-domain <value>  Business domain (default: bd_public)`;
+const KN_LIST_HELP = renderHelp({
+    tagline: "List business knowledge networks (ontology-manager API)",
+    usage: "kweaver bkn list [flags]",
+    flags: [
+        { name: "--offset <n>", desc: "Offset (default: 0)" },
+        { name: "--limit <n>", desc: "Limit (default: 30)" },
+        { name: "--sort <key>", desc: "Sort field (default: update_time)" },
+        { name: "--direction <asc|desc>", desc: "Sort direction (default: desc)" },
+        { name: "--name-pattern <s>", desc: "Filter by name pattern" },
+        { name: "--tag <s>", desc: "Filter by tag" },
+        { name: "--detail", desc: "Include the detail field in simplified output" },
+        { name: "--verbose, -v", desc: "Show full JSON response" },
+        { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+        { name: "--pretty", desc: "Pretty-print JSON output (applies to both modes)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: ["kweaver bkn list --limit 50 --tag analytics"],
+});
+const KN_GET_HELP = renderHelp({
+    tagline: "Get knowledge network detail",
+    usage: "kweaver bkn get <kn-id> [flags]",
+    flags: [
+        { name: "--stats", desc: "Include statistics" },
+        { name: "--export", desc: "Export mode (include sub-types)" },
+        { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+        { name: "--pretty", desc: "Pretty-print JSON output" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: ["kweaver bkn get kn-123 --stats"],
+});
+const KN_CREATE_HELP = renderHelp({
+    tagline: "Create a knowledge network (empty or from --body-file)",
+    usage: "kweaver bkn create [flags]",
+    flags: [
+        { name: "--name <s>", desc: "Name (required unless --body-file)" },
+        { name: "--comment <s>", desc: "Comment" },
+        { name: "--tags <t1,t2>", desc: "Comma-separated tags" },
+        { name: "--icon <s>", desc: "Icon" },
+        { name: "--color <s>", desc: "Color" },
+        { name: "--branch <s>", desc: "Branch (default: main)" },
+        { name: "--base-branch <s>", desc: "Base branch (default: empty for main)" },
+        { name: "--body-file <path>", desc: "Read full JSON body from file (cannot combine with flags above)" },
+        { name: "--import-mode <normal|ignore|overwrite>", desc: "Import mode (default: normal)" },
+        { name: "--validate-dependency <true|false>", desc: "Validate dependency (default: true)" },
+        { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+        { name: "--pretty", desc: "Pretty-print JSON output" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver bkn create --name my-kn --tags a,b",
+        "kweaver bkn create --body-file ./kn.json",
+    ],
+});
+const KN_UPDATE_HELP = renderHelp({
+    tagline: "Update a knowledge network",
+    usage: "kweaver bkn update <kn-id> [flags]",
+    flags: [
+        { name: "--name <s>", desc: "Name (required unless --body-file)" },
+        { name: "--comment <s>", desc: "Comment" },
+        { name: "--tags <t1,t2>", desc: "Comma-separated tags" },
+        { name: "--icon <s>", desc: "Icon" },
+        { name: "--color <s>", desc: "Color" },
+        { name: "--branch <s>", desc: "Branch (default: main)" },
+        { name: "--base-branch <s>", desc: "Base branch (default: empty for main)" },
+        { name: "--body-file <path>", desc: "Read full JSON body from file (cannot combine with flags above)" },
+        { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+        { name: "--pretty", desc: "Pretty-print JSON output" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: ["kweaver bkn update kn-123 --name renamed"],
+});
+const KN_DELETE_HELP = renderHelp({
+    tagline: "Delete a KN and its object/relation/action types and concept groups",
+    usage: "kweaver bkn delete <kn-id> [flags]",
+    flags: [
+        { name: "--yes, -y", desc: "Skip confirmation prompt" },
+        { name: "-bd, --biz-domain <value>", desc: "Business domain (default: bd_public)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: ["kweaver bkn delete kn-123 -y"],
+});
 async function runKnGetCommand(args) {
     let options;
     try {

package/dist/commands/call.js

@@ -4,6 +4,28 @@ import { ensureValidToken, formatHttpError, with401RefreshRetry } from "../auth/
 import { isNoAuth } from "../config/no-auth.js";
 import { HttpError } from "../utils/http.js";
 import { resolveBusinessDomain } from "../config/store.js";
+import { renderHelp } from "../help/format.js";
+const CALL_HELP = renderHelp({
+    tagline: "Call an API with curl-style flags and auto-injected auth headers",
+    usage: "kweaver call <url> [-X METHOD] [-H \"Name: value\"] [-d BODY|-F key=val] [flags]",
+    flags: [
+        { name: "<url>", desc: "API path, e.g. /api/ontology-manager/v1/knowledge-networks" },
+        { name: "-X, --request", desc: "HTTP method (default: GET)" },
+        { name: "-H, --header", desc: "Extra header (repeatable)" },
+        { name: "-d, --data, --data-raw", desc: "JSON request body (sets Content-Type: application/json if unset)" },
+        { name: "-F, --form", desc: "Multipart form field: key=value or key=@/path/to/file. Repeatable. Mutually exclusive with -d" },
+        { name: "-bd, --biz-domain", desc: "Override x-business-domain (default: bd_public)" },
+        { name: "-v, --verbose", desc: "Print request info to stderr" },
+        { name: "--pretty", desc: "Pretty-print JSON output (default)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver call /api/ontology-manager/v1/knowledge-networks",
+        "kweaver call -X POST /api/agents -d '{\"name\":\"demo\"}'",
+        "kweaver call -F file=@./spec.yaml /api/toolboxes/{id}/tools/upload",
+    ],
+    learnMore: ["Alias: `kweaver curl ...`"],
+});
 export function parseCallArgs(args) {
     const headers = new Headers();
     let method = "GET";
@@ -160,19 +182,7 @@ export function formatVerboseRequest(invocation) {
 }
 export async function runCallCommand(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
-        console.log(`kweaver call <url> [-X METHOD] [-H "Name: value"] [-d BODY] [-F key=value] [--pretty] [--verbose] [-bd value]
-
-Call an API with curl-style flags and auto-injected token headers.
-
-Options:
-  <url>              API path (e.g. /api/ontology-manager/v1/knowledge-networks)
-  -X, --request      HTTP method (default: GET)
-  -H, --header       Extra header (repeatable)
-  -d, --data, --data-raw   JSON request body (sets Content-Type: application/json if not set)
-  -F, --form         Multipart form field. -F key=value or -F key=@/path/to/file. Repeatable. Mutually exclusive with -d.
-  -bd, --biz-domain  Override x-business-domain (default: bd_public)
-  -v, --verbose      Print request info to stderr
-  --pretty           Pretty-print JSON output (default)`);
+        console.log(CALL_HELP);
         return 0;
     }
     let invocation;

package/dist/commands/config.js

@@ -3,18 +3,28 @@ import { fetchEacpUserInfo, resolveActivePlatform, withTokenRetry } from "../aut
 import { HttpError } from "../utils/http.js";
 import { loadPlatformBusinessDomain, resolveBusinessDomain, savePlatformBusinessDomain, } from "../config/store.js";
 import { assertNotStatelessForWrite } from "../config/stateless.js";
-const HELP = `kweaver config
-
-Subcommands:
-  set-bd <value>    Set the default business domain for the current platform
-  list-bd           List business domains as JSON (requires login)
-  show              Show current config (platform, business domain)
-  --help            Show this message
-
-Examples:
-  kweaver config set-bd 54308785-4438-43df-9490-a7fd11df5765
-  kweaver config list-bd
-  kweaver config show`;
+import { renderHelp } from "../help/format.js";
+const HELP = renderHelp({
+    tagline: "Per-platform business-domain config",
+    usage: "kweaver config <subcommand> [flags]",
+    sections: [
+        {
+            title: "AVAILABLE COMMANDS",
+            items: [
+                { name: "set-bd", desc: "Set default business domain for current platform" },
+                { name: "list-bd", desc: "List business domains as JSON (requires login)" },
+                { name: "show", desc: "Show current config (platform, business domain)" },
+            ],
+        },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver config set-bd 54308785-4438-43df-9490-a7fd11df5765",
+        "kweaver config list-bd",
+        "kweaver config show",
+    ],
+    learnMore: ["Use `kweaver config <subcommand> --help` for flag details"],
+});
 export async function runConfigCommand(args) {
     const [sub, ...rest] = args;
     if (!sub || sub === "--help" || sub === "-h" || sub === "help") {

package/dist/commands/context-loader.js

@@ -3,6 +3,7 @@ import { callTool, searchSchema, queryObjectInstance, queryInstanceSubgraph, get
 import { knSearchHttp, semanticSearch } from "../api/semantic-search.js";
 import { addContextLoaderEntry, getCurrentContextLoaderKn, loadContextLoaderConfig, removeContextLoaderEntry, resolveBusinessDomain, setCurrentContextLoader, } from "../config/store.js";
 import { assertNotStatelessForWrite } from "../config/stateless.js";
+import { renderHelp } from "../help/format.js";
 const CONTEXT_LOADER_CONFIG_DEPRECATION = "[deprecated] `kweaver context-loader config ...` will be removed in a future release. " +
     "Pass <kn-id> as the first positional to runtime subcommands instead, e.g. " +
     "`kweaver context-loader tools <kn-id>` (or use the `--kn-id <id>` flag).";
@@ -10,87 +11,102 @@ const MCP_NOT_CONFIGURED = "Context-loader MCP is not configured. Run: kweaver c
 const MCP_PATH = "/api/agent-retrieval/v1/mcp";
 const DEPRECATED_KN_SEARCH_MESSAGE = "[deprecated] context-loader kn-search is deprecated. Use context-loader search-schema instead.";
 const DEPRECATED_KN_SCHEMA_SEARCH_MESSAGE = "[deprecated] context-loader kn-schema-search is deprecated. Use context-loader search-schema instead.";
-const CONTEXT_LOADER_HELP = `kweaver context-loader
-
-USAGE
-  kweaver context-loader <subcommand> [flags]
-  kweaver context-loader help <subcommand>
-  kweaver context-loader --help
-  kweaver context-loader <subcommand> --help
-
-KN SELECTION
-  Most runtime subcommands require a KN. Pass it as the first positional
-  argument or use --kn-id <id> / -k <id>. Omitting KN falls back to the
-  deprecated saved config managed by kweaver context-loader config.
-
-RECOMMENDED FLOW
-  search-schema:       Discover schema concepts
-  query-*:             Query instances using discovered schema IDs
-  get-*/find-skills:   Enrich instances or inspect actions
-  tool-call:           Raw MCP debugging or unsupported tools only
-
-SCHEMA DISCOVERY COMMANDS
-  search-schema:       Search object/relation/action/metric schemas
-  kn-search:           [deprecated] Use search-schema
-  kn-schema-search:    [deprecated] Use search-schema
-
-INSTANCE QUERY COMMANDS
-  query-object-instance:    Query object instances
-  query-instance-subgraph:  Query instance subgraphs
-
-INSTANCE ENRICHMENT AND ACTION COMMANDS
-  get-logic-properties: Get calculated logic property values
-  get-action-info:      Get action metadata and executable info
-  find-skills:          Recall skills for an object type
-
-ADVANCED MCP COMMANDS
-  tools:       List MCP tools
-  resources:   List MCP resources
-  resource:    Read an MCP resource by URI
-  templates:   List MCP resource templates
-  prompts:     List MCP prompts
-  prompt:      Get an MCP prompt by name
-  tool-call:   Call any MCP tool directly
-
-DEPRECATED CONFIGURATION COMMANDS
-  config:      Manage legacy saved KN selection
-
-FLAGS
-  -k, --kn-id <id>   KN selector for runtime subcommands
-  --pretty           Pretty-print JSON output
-  --compact          Print compact JSON output
-  -h, --help         Show help
-
-LEARN MORE
-  Use \`kweaver context-loader <subcommand> --help\` for arguments, JSON shapes, and examples.`;
-const CONTEXT_LOADER_CONFIG_HELP = `kweaver context-loader config  [deprecated]
-
-Usage:
-  kweaver context-loader config set --kn-id <id> [--name <name>]
-  kweaver context-loader config use <name>
-  kweaver context-loader config list
-  kweaver context-loader config remove <name>
-  kweaver context-loader config show
-
-Description:
-  Manage the deprecated saved context-loader KN selection. Runtime commands should pass
-  <kn-id> as the first positional or use --kn-id <id> / -k <id> instead.
-
-Arguments:
-  <name>          Saved config name.
-
-Options:
-  --kn-id <id>    KN ID to save for config set.
-  --name <name>   Saved config name for config set. Default: default.
-  --help, -h      Show this help and exit before auth/config/network checks.
-
-Examples:
-  kweaver context-loader tools d5iv6c9818p72mpje8pg
-  kweaver context-loader tools --kn-id d5iv6c9818p72mpje8pg
-
-Notes:
-  This command group is deprecated and will be removed in a future release.
-  It is disabled in stateless mode (--token).`;
+const CONTEXT_LOADER_HELP = renderHelp({
+    tagline: "MCP / HTTP context-loader — schema discovery, instance query, action info, skill recall",
+    usage: [
+        "kweaver context-loader <subcommand> [flags]",
+        "kweaver context-loader help <subcommand>",
+    ],
+    sections: [
+        {
+            title: "RECOMMENDED FLOW",
+            items: [
+                { name: "1. search-schema", desc: "Discover schema concepts" },
+                { name: "2. query-*", desc: "Query instances using discovered schema IDs" },
+                { name: "3. get-* / find-skills", desc: "Enrich instances or inspect actions" },
+                { name: "—  tool-call", desc: "Raw MCP debugging or unsupported tools only" },
+            ],
+        },
+        {
+            title: "SCHEMA DISCOVERY",
+            items: [
+                { name: "search-schema", desc: "Search object/relation/action/metric schemas" },
+                { name: "kn-search", desc: "[deprecated] Use search-schema" },
+                { name: "kn-schema-search", desc: "[deprecated] Use search-schema" },
+            ],
+        },
+        {
+            title: "INSTANCE QUERY",
+            items: [
+                { name: "query-object-instance", desc: "Query object instances" },
+                { name: "query-instance-subgraph", desc: "Query instance subgraphs" },
+            ],
+        },
+        {
+            title: "INSTANCE ENRICHMENT / ACTION",
+            items: [
+                { name: "get-logic-properties", desc: "Get calculated logic-property values" },
+                { name: "get-action-info", desc: "Get action metadata and executable info" },
+                { name: "find-skills", desc: "Recall skills for an object type" },
+            ],
+        },
+        {
+            title: "ADVANCED MCP",
+            items: [
+                { name: "tools", desc: "List MCP tools" },
+                { name: "resources", desc: "List MCP resources" },
+                { name: "resource", desc: "Read an MCP resource by URI" },
+                { name: "templates", desc: "List MCP resource templates" },
+                { name: "prompts", desc: "List MCP prompts" },
+                { name: "prompt", desc: "Get an MCP prompt by name" },
+                { name: "tool-call", desc: "Call any MCP tool directly" },
+            ],
+        },
+        {
+            title: "DEPRECATED",
+            items: [{ name: "config", desc: "Manage legacy saved KN selection (set/use/list/remove/show)" }],
+        },
+    ],
+    flags: [
+        { name: "-k, --kn-id <id>", desc: "KN selector for runtime subcommands" },
+        { name: "--pretty", desc: "Pretty-print JSON output" },
+        { name: "--compact", desc: "Compact JSON output" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver context-loader search-schema <id> 'customer churn'",
+        "kweaver context-loader query-object-instance <id> --object-type-id <ot> --limit 10",
+        "kweaver context-loader find-skills <id> <ot-id>",
+    ],
+    learnMore: [
+        "Alias: `kweaver context ...`",
+        "Use `kweaver context-loader <subcommand> --help` for arguments, JSON shapes, examples",
+        "Most runtime subcommands require a KN — first positional or --kn-id / -k",
+    ],
+});
+const CONTEXT_LOADER_CONFIG_HELP = renderHelp({
+    tagline: "[deprecated] Manage the saved context-loader KN selection",
+    usage: [
+        "kweaver context-loader config set --kn-id <id> [--name <name>]",
+        "kweaver context-loader config use <name>",
+        "kweaver context-loader config list",
+        "kweaver context-loader config remove <name>",
+        "kweaver context-loader config show",
+    ],
+    flags: [
+        { name: "--kn-id <id>", desc: "KN id to save (for `config set`)" },
+        { name: "--name <name>", desc: "Saved config name (for `config set`; default: default)" },
+    ],
+    inheritedFlags: "--base-url, --token, --user, --help",
+    examples: [
+        "kweaver context-loader tools d5iv6c9818p72mpje8pg",
+        "kweaver context-loader tools --kn-id d5iv6c9818p72mpje8pg",
+    ],
+    learnMore: [
+        "Deprecated: runtime commands should pass <kn-id> as the first positional or use --kn-id/-k",
+        "Disabled in stateless mode (--token); will be removed in a future release",
+    ],
+});
 const CONTEXT_LOADER_SUBCOMMAND_HELP = {
     tools: `kweaver context-loader tools
 
@@ -734,17 +750,7 @@ export async function runContextLoaderCommand(args) {
 async function runConfigCommand(args) {
     const [action, ...rest] = args;
     if (!action || action === "--help" || action === "-h") {
-        console.log(`kweaver context-loader config  [deprecated]
-
-Subcommands:
-  set --kn-id <id> [--name <name>]   Add or update kn config (default name: default)
-  use <name>                         Switch current config
-  list                               List all configs and current
-  remove <name>                      Remove a config
-  show                               Show current config (knId + mcpUrl)
-
-Note: this command group is deprecated and will be removed in a future release.
-      It is disabled entirely in stateless mode (\`--token\`).`);
+        console.log(CONTEXT_LOADER_CONFIG_HELP);
         return 0;
     }
     // Stateless mode (`--token`) does not support any context-loader config