@senso-ai/cli 0.4.0 → 0.6.0

package/dist/cli.js

@@ -578,6 +578,38 @@ function registerApiKeyCommands(program2) {
       process.exit(1);
     }
   });
+  keys.command("kb-permissions-get <keyId>").description("Get the knowledge base node permission grants configured for an API key.").action(async (keyId) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: `/org/api-keys/${keyId}/kb-permissions`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  keys.command("kb-permissions-set <keyId>").description("Set KB node permission grants for an API key. Replaces any existing grants. Each grant requires a node_id (UUID) and role (viewer|editor|owner|admin).").requiredOption("--data <json>", 'JSON: { "grants": [{ "node_id": "<uuid>", "role": "viewer" }] }').action(async (keyId, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "PUT", path: `/org/api-keys/${keyId}/kb-permissions`, body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`KB permissions updated for key ${keyId}.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  keys.command("kb-permissions-delete <keyId>").description("Remove all KB node permission grants from an API key, restoring full org-level access.").action(async (keyId) => {
+    const opts = program2.opts();
+    try {
+      await apiRequest({ method: "DELETE", path: `/org/api-keys/${keyId}/kb-permissions`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`KB permissions removed from key ${keyId}.`);
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/search.ts
@@ -636,13 +668,16 @@ function output(format, data) {
 // src/commands/search.ts
 function registerSearchCommands(program2) {
   const search = program2.command("search").description("Search the knowledge base with natural language queries. Returns AI-generated answers synthesised from matching content chunks, or raw chunks/content IDs.");
-  search.argument("<query>", "Search query").option("--max-results <n>", "Maximum number of results", "5").action(async (query, cmdOpts) => {
+  search.argument("<query>", "Search query").option("--max-results <n>", "Maximum number of results", "5").option("--content-ids <ids...>", "Restrict search to specific content item IDs (space-separated UUIDs)").option("--require-scoped-ids", "Only return results from the specified --content-ids (omit to allow fallback to all content)").action(async (query, cmdOpts) => {
     const opts = program2.opts();
     try {
+      const body = { query, max_results: parseInt(cmdOpts.maxResults) };
+      if (cmdOpts.contentIds) body.content_ids = cmdOpts.contentIds;
+      if (cmdOpts.requireScopedIds) body.require_scoped_ids = true;
       const data = await apiRequest({
         method: "POST",
         path: "/org/search",
-        body: { query, max_results: parseInt(cmdOpts.maxResults) },
+        body,
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
@@ -675,13 +710,16 @@ function registerSearchCommands(program2) {
       process.exit(1);
     }
   });
-  search.command("context <query>").description("Search the knowledge base \u2014 returns matching content chunks only, without AI answer generation. Faster than full search.").option("--max-results <n>", "Maximum results", "5").action(async (query, cmdOpts) => {
+  search.command("context <query>").description("Search the knowledge base \u2014 returns matching content chunks only, without AI answer generation. Use this to feed verified chunks into your own LLM pipeline instead of using Senso's generated answer.").option("--max-results <n>", "Maximum results", "5").option("--content-ids <ids...>", "Restrict search to specific content item IDs (space-separated UUIDs)").option("--require-scoped-ids", "Only return results from the specified --content-ids").action(async (query, cmdOpts) => {
     const opts = program2.opts();
     try {
+      const body = { query, max_results: parseInt(cmdOpts.maxResults) };
+      if (cmdOpts.contentIds) body.content_ids = cmdOpts.contentIds;
+      if (cmdOpts.requireScopedIds) body.require_scoped_ids = true;
       const data = await apiRequest({
         method: "POST",
         path: "/org/search/context",
-        body: { query, max_results: parseInt(cmdOpts.maxResults) },
+        body,
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
@@ -691,13 +729,35 @@ function registerSearchCommands(program2) {
       process.exit(1);
     }
   });
-  search.command("content <query>").description("Search the knowledge base \u2014 returns deduplicated content IDs and titles only. No chunks or AI answer.").option("--max-results <n>", "Maximum results", "5").action(async (query, cmdOpts) => {
+  search.command("content <query>").description("Search the knowledge base \u2014 returns deduplicated content IDs and titles only. Use this to discover which documents are relevant before fetching full content with 'content get <id>'.").option("--max-results <n>", "Maximum results", "5").option("--content-ids <ids...>", "Restrict search to specific content item IDs (space-separated UUIDs)").option("--require-scoped-ids", "Only return results from the specified --content-ids").action(async (query, cmdOpts) => {
     const opts = program2.opts();
     try {
+      const body = { query, max_results: parseInt(cmdOpts.maxResults) };
+      if (cmdOpts.contentIds) body.content_ids = cmdOpts.contentIds;
+      if (cmdOpts.requireScopedIds) body.require_scoped_ids = true;
       const data = await apiRequest({
         method: "POST",
         path: "/org/search/content",
-        body: { query, max_results: parseInt(cmdOpts.maxResults) },
+        body,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      outputByFormat(opts.output, data);
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  search.command("full <query>").description("Alias for the default search \u2014 returns AI answer plus matching chunks. Equivalent to 'senso search <query>'.").option("--max-results <n>", "Maximum results", "5").option("--content-ids <ids...>", "Restrict search to specific content item IDs (space-separated UUIDs)").option("--require-scoped-ids", "Only return results from the specified --content-ids").action(async (query, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = { query, max_results: parseInt(cmdOpts.maxResults) };
+      if (cmdOpts.contentIds) body.content_ids = cmdOpts.contentIds;
+      if (cmdOpts.requireScopedIds) body.require_scoped_ids = true;
+      const data = await apiRequest({
+        method: "POST",
+        path: "/org/search/full",
+        body,
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
@@ -767,7 +827,7 @@ async function uploadToS3(url, buffer, contentType) {
 }
 function registerIngestCommands(program2) {
   const ingest = program2.command("ingest").description("Ingest files into the knowledge base. Upload documents (PDF, TXT, DOCX, etc.) to be parsed, chunked, and embedded for semantic search.");
-  ingest.command("upload <files...>").description("Upload files to the knowledge base. Accepts local file paths (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker.").action(async (files) => {
+  ingest.command("upload <files...>").description("Upload files to the knowledge base. Accepts local file paths (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker. Poll 'senso content get <content-id>' until processing_status is 'complete' before searching the uploaded content.").action(async (files) => {
     const opts = program2.opts();
     if (files.length > 10) {
       error("Maximum 10 files per upload request.");
@@ -777,7 +837,7 @@ function registerIngestCommands(program2) {
       const fileData = await Promise.all(files.map(getFileMetadata));
       const results = await apiRequest({
         method: "POST",
-        path: "/org/ingestion/upload",
+        path: "/org/kb/upload",
         body: { files: fileData.map((f) => f.meta) },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
@@ -813,7 +873,7 @@ function registerIngestCommands(program2) {
       const { meta, buffer } = await getFileMetadata(file);
       const results = await apiRequest({
         method: "PUT",
-        path: `/org/ingestion/content/${contentId}`,
+        path: `/org/kb/nodes/${contentId}/file`,
         body: { file: meta },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
@@ -841,29 +901,30 @@ function registerIngestCommands(program2) {
 import pc6 from "picocolors";
 function registerContentCommands(program2) {
   const content = program2.command("content").description("Manage content items in the knowledge base. List, inspect, delete, unpublish, and manage the verification workflow and ownership of content.");
-  content.command("list").description("List all content items in the knowledge base. Returns title, status, and ID for each item. Use --search to filter by title, --sort to order results.").option("--limit <n>", "Items per page", "10").option("--offset <n>", "Pagination offset", "0").option("--search <query>", "Filter content by title").option("--sort <order>", "Sort order: title_asc, title_desc, created_asc, created_desc").action(async (cmdOpts) => {
+  content.command("list").description("List top-level files and folders in the knowledge base. Use 'kb my-files' for the same result with richer KB node output.").option("--limit <n>", "Items per page", "10").option("--offset <n>", "Pagination offset", "0").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const data = await apiRequest({
-        path: "/org/content",
-        params: { limit: cmdOpts.limit, offset: cmdOpts.offset, search: cmdOpts.search, sort: cmdOpts.sort },
+        path: "/org/kb/my-files",
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
       const format = opts.output || "plain";
-      const rows = Array.isArray(data) ? data : [];
+      const rows = Array.isArray(data) ? data : data.nodes ?? [];
       output(format, {
         json: data,
         table: {
           rows: rows.map((r) => ({
-            id: r.id || r.content_id,
-            title: r.title,
-            status: r.status
+            id: r.node_id,
+            name: r.name,
+            type: r.type,
+            status: r.processing_status
           })),
-          columns: ["id", "title", "status"]
+          columns: ["id", "name", "type", "status"]
         },
         plain: rows.length ? rows.map(
-          (r) => `  ${pc6.bold(String(r.title || "Untitled"))} ${pc6.dim(`(${r.id || r.content_id})`)} ${r.status ? pc6.dim(`[${r.status}]`) : ""}`
+          (r) => `  ${pc6.bold(String(r.name || "Untitled"))} ${pc6.dim(`(${r.node_id})`)} ${r.type ? pc6.dim(`[${r.type}]`) : ""}`
         ) : ["  No content found."]
       });
     } catch (err) {
@@ -1000,7 +1061,7 @@ function registerGenerateCommands(program2) {
       process.exit(1);
     }
   });
-  gen.command("sample").description("Generate an ad hoc content sample for a specific prompt and content type. Returns the generated markdown, SEO title, and publish results.").requiredOption("--prompt-id <id>", "Prompt (geo question) ID to generate content for").requiredOption("--content-type-id <id>", "Content type ID that defines the output format").option("--destination <dest>", "Publish destination (e.g. citeables)").action(async (cmdOpts) => {
+  gen.command("sample").description("Generate an ad hoc content sample for a specific prompt and content type. Returns the generated markdown, SEO title, and publish results. Use 'prompts list' to find a prompt ID, and 'content-types list' to find a content-type ID.").requiredOption("--prompt-id <id>", "Prompt (geo question) ID to generate content for").requiredOption("--content-type-id <id>", "Content type ID that defines the output format (use 'content-types list' to find)").option("--destination <dest>", "Publisher slug to publish to immediately after generation. Omit to save as draft only.").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const body = {
@@ -1023,7 +1084,7 @@ function registerGenerateCommands(program2) {
       process.exit(1);
     }
   });
-  gen.command("run").description("Trigger a content generation run. Processes all prompts (or a specific subset) through the content engine. Runs asynchronously.").option("--prompt-ids <ids...>", "Optional list of prompt IDs to process (omit to run all)").action(async (cmdOpts) => {
+  gen.command("run").description("Trigger a content generation run. Processes all prompts (or a specific subset) through the content engine. Runs asynchronously \u2014 use 'generate runs-list' to monitor progress.").option("--prompt-ids <ids...>", "Optional list of prompt IDs to process (omit to run all)").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const body = cmdOpts.promptIds ? { prompt_ids: cmdOpts.promptIds } : void 0;
@@ -1035,6 +1096,78 @@ function registerGenerateCommands(program2) {
       process.exit(1);
     }
   });
+  gen.command("job-context").description("Get the full content generation job context \u2014 all prompts with queue status (create vs update), content state, and a summary of queue counts.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/content-generation/job-context", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  gen.command("runs-list").description("List content generation runs for the org. Use --status to filter by run status, --active-only to show only in-progress runs.").option("--limit <n>", "Items per page", "20").option("--offset <n>", "Pagination offset", "0").option("--status <status>", "Filter by run status").option("--active-only", "Only return active (in-progress) runs").option("--start-date <date>", "Filter runs on or after this date (YYYY-MM-DD)").option("--end-date <date>", "Filter runs on or before this date (YYYY-MM-DD)").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: "/org/content-generation/runs",
+        params: {
+          limit: cmdOpts.limit,
+          offset: cmdOpts.offset,
+          status: cmdOpts.status,
+          active_only: cmdOpts.activeOnly ? "true" : void 0,
+          start_date: cmdOpts.startDate,
+          end_date: cmdOpts.endDate
+        },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  gen.command("runs-get <runId>").description("Get details for a specific content generation run.").action(async (runId) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: `/org/content-generation/runs/${runId}`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  gen.command("runs-items <runId>").description("List individual prompt items within a content generation run and their per-item status.").option("--limit <n>", "Items per page", "100").option("--offset <n>", "Pagination offset", "0").action(async (runId, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/content-generation/runs/${runId}/items`,
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  gen.command("runs-logs <runId>").description("List log entries for a content generation run.").option("--limit <n>", "Items per page", "100").option("--offset <n>", "Pagination offset", "0").action(async (runId, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/content-generation/runs/${runId}/logs`,
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/engine.ts
@@ -1091,7 +1224,7 @@ function registerBrandKitCommands(program2) {
       process.exit(1);
     }
   });
-  bk.command("set").description("Create or replace the brand kit. The guidelines field is a free-form JSON object defining your brand voice.").requiredOption("--data <json>", 'JSON: { "guidelines": { "tone": "professional", "voice": "..." } }').action(async (cmdOpts) => {
+  bk.command("set").description("Replace the entire brand kit (PUT). All existing fields are overwritten \u2014 run 'brand-kit get' first to preserve fields you are not changing. For a safe partial update, use 'brand-kit patch'.").requiredOption("--data <json>", 'JSON: { "guidelines": { "brand_name": "Acme", "voice_and_tone": "...", "author_persona": "...", "global_writing_rules": [] } }').action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const body = JSON.parse(cmdOpts.data);
@@ -1109,6 +1242,24 @@ function registerBrandKitCommands(program2) {
       process.exit(1);
     }
   });
+  bk.command("patch").description("Partially update the brand kit (PATCH). Only the fields you provide are changed \u2014 existing fields are preserved. Preferred over 'set' for targeted updates.").requiredOption("--data <json>", 'JSON: { "guidelines": { "voice_and_tone": "Warm and approachable" } }').action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({
+        method: "PATCH",
+        path: "/org/brand-kit",
+        body,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      success("Brand kit updated.");
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/content-types.ts
@@ -1157,7 +1308,7 @@ function registerContentTypeCommands(program2) {
       process.exit(1);
     }
   });
-  ct.command("update <id>").description("Update a content type's name or configuration.").requiredOption("--data <json>", 'JSON: { "name": "Updated Name", "config": { ... } }').action(async (id, cmdOpts) => {
+  ct.command("update <id>").description("Replace a content type's name and config (PUT). Both fields are required \u2014 run 'get <id>' first to preserve existing values. For single-field updates, use 'content-types patch <id>'.").requiredOption("--data <json>", 'JSON: { "name": "Updated Name", "config": { "template": "...", "cta_text": "...", "cta_destination": "...", "writing_rules": [] } }').action(async (id, cmdOpts) => {
     const opts = program2.opts();
     try {
       const body = JSON.parse(cmdOpts.data);
@@ -1175,6 +1326,24 @@ function registerContentTypeCommands(program2) {
       process.exit(1);
     }
   });
+  ct.command("patch <id>").description("Partially update a content type (PATCH). Only the fields you provide are changed \u2014 existing fields are preserved. Preferred over 'update' for targeted changes like updating just the template.").requiredOption("--data <json>", 'JSON: { "config": { "template": "Updated template instruction" } }').action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({
+        method: "PATCH",
+        path: `/org/content-types/${id}`,
+        body,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      success(`Content type ${id} updated.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
   ct.command("delete <id>").description("Delete a content type. This cannot be undone.").action(async (id) => {
     const opts = program2.opts();
     try {
@@ -1189,7 +1358,7 @@ function registerContentTypeCommands(program2) {
 
 // src/commands/prompts.ts
 function registerPromptCommands(program2) {
-  const prompts = program2.command("prompts").description("Manage prompts (geo questions). Prompts are the questions that drive AI content generation \u2014 each prompt is run against configured AI models to track brand mentions, claims, and competitor visibility.");
+  const prompts = program2.command("prompts").description("Manage prompts (GEO questions). Each prompt is a question that drives both AI content generation (use with 'generate sample --prompt-id') and brand visibility monitoring \u2014 tracking how AI models mention your brand, products, and competitors.");
   prompts.command("list").description("List all prompts in the organization. Use --search to filter by question text, --sort to order results.").option("--limit <n>", "Maximum prompts to return (max: 100)").option("--offset <n>", "Number of prompts to skip (for pagination)").option("--search <query>", "Filter prompts by question text").option("--sort <order>", "Sort order: created_desc, created_asc, text_asc, text_desc, type_asc, type_desc").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
@@ -1326,19 +1495,30 @@ function registerMemberCommands(program2) {
   });
 }
 
-// src/commands/notifications.ts
-function registerNotificationCommands(program2) {
-  const notif = program2.command("notifications").description("View and manage user notifications. Notifications are triggered by content verification, generation runs, and other system events.");
-  notif.command("list").description("List notifications for the current user. Use --unread-only to filter to unread notifications.").option("--limit <n>", "Maximum notifications to return (default: 50, max: 200)").option("--offset <n>", "Number of notifications to skip (for pagination)").option("--unread-only", "Only return unread notifications").action(async (cmdOpts) => {
+// src/commands/credits.ts
+function registerCreditsCommands(program2) {
+  const credits = program2.command("credits").description("View your organisation's credit balance. Credits are consumed by AI content generation and search operations.");
+  credits.command("balance").description("Get the current credit balance for the organisation. Returns available credits and any spend limit configured.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/credits/balance", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/questions.ts
+function registerQuestionsCommands(program2) {
+  const questions = program2.command("questions").description("Manage org-scoped geo questions. These are lightweight CRUD questions distinct from prompts (which include full run history).");
+  questions.command("list").description("List geo questions for the org.").option("--type <type>", "Filter by question type: organization | network", "organization").action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
       const data = await apiRequest({
-        path: "/app/v1/notifications",
-        params: {
-          limit: cmdOpts.limit,
-          offset: cmdOpts.offset,
-          unread_only: cmdOpts.unreadOnly ? "true" : void 0
-        },
+        path: "/org/questions",
+        params: { question_type: cmdOpts.type },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
@@ -1348,16 +1528,363 @@ function registerNotificationCommands(program2) {
       process.exit(1);
     }
   });
-  notif.command("read <id>").description("Mark a notification as read.").action(async (id) => {
+  questions.command("create").description("Create a new geo question. Type must be one of: decision, consideration, awareness, evaluation.").requiredOption("--data <json>", 'JSON: { "question_text": "...", "type": "decision", "tag_ids": [] }').action(async (cmdOpts) => {
     const opts = program2.opts();
     try {
-      await apiRequest({
-        method: "PATCH",
-        path: `/app/v1/notifications/${id}/read`,
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "POST", path: "/org/questions", body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success("Question created.");
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  questions.command("patch <questionId>").description("Partially update a question. Currently supports updating tag associations.").requiredOption("--data <json>", 'JSON: { "tag_ids": ["<uuid>", ...] } \u2014 pass null to clear all tags').action(async (questionId, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "PATCH", path: `/org/questions/${questionId}`, body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Question ${questionId} updated.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  questions.command("delete <questionId>").description("Delete a geo question.").action(async (questionId) => {
+    const opts = program2.opts();
+    try {
+      await apiRequest({ method: "DELETE", path: `/org/questions/${questionId}`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Question ${questionId} deleted.`);
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/kb.ts
+import { createHash as createHash2 } from "crypto";
+import { readFile as readFile2, stat as stat2 } from "fs/promises";
+import { basename as basename2, resolve as resolve2 } from "path";
+var MIME_TYPES2 = {
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".csv": "text/csv",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".md": "text/markdown",
+  ".json": "application/json",
+  ".xml": "application/xml"
+};
+function getMimeType2(filename) {
+  const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase();
+  return MIME_TYPES2[ext] || "application/octet-stream";
+}
+async function getFileMetadata2(filePath) {
+  const absPath = resolve2(filePath);
+  const buffer = await readFile2(absPath);
+  const stats = await stat2(absPath);
+  const hash = createHash2("md5").update(buffer).digest("hex");
+  return {
+    meta: {
+      filename: basename2(absPath),
+      file_size_bytes: stats.size,
+      content_type: getMimeType2(basename2(absPath)),
+      content_hash_md5: hash
+    },
+    buffer
+  };
+}
+async function uploadToS32(url, buffer, contentType) {
+  const res = await fetch(url, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    body: buffer
+  });
+  if (!res.ok) throw new Error(`S3 upload failed: ${res.status} ${res.statusText}`);
+}
+function registerKBCommands(program2) {
+  const kb = program2.command("kb").description("Manage the knowledge base. Browse nodes, upload files, create folders, create raw content, and manage the KB tree.");
+  kb.command("root").description("Get the root KB node for the org.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/kb/root", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("my-files").description("List top-level files and folders in the knowledge base.").option("--limit <n>", "Items per page", "50").option("--offset <n>", "Pagination offset", "0").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: "/org/kb/my-files",
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("find").description("Search KB nodes by name.").requiredOption("--query <q>", "Name search query").option("--limit <n>", "Items per page", "20").option("--offset <n>", "Pagination offset", "0").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: "/org/kb/find",
+        params: { q: cmdOpts.query, limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("sync-status").description("Get the vector sync status for the org's knowledge base.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/kb/sync-status", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("get <id>").description("Get a KB node by ID.").action(async (id) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: `/org/kb/nodes/${id}`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("children <id>").description("List children of a KB folder node.").option("--limit <n>", "Items per page", "50").option("--offset <n>", "Pagination offset", "0").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/kb/nodes/${id}/children`,
+        params: { limit: cmdOpts.limit, offset: cmdOpts.offset },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("ancestors <id>").description("Get the ancestor chain (breadcrumb) for a KB node.").action(async (id) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: `/org/kb/nodes/${id}/ancestors`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("get-content <id>").description("Get the content detail for a KB content node.").option("--version <version>", "Specific version to retrieve").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/kb/nodes/${id}/content`,
+        params: { version: cmdOpts.version },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("download-url <id>").description("Get a presigned S3 download URL for a KB file node.").option("--version <version>", "Specific version to download").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({
+        path: `/org/kb/nodes/${id}/download-url`,
+        params: { version: cmdOpts.version },
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl
       });
-      success(`Notification ${id} marked as read.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("create-folder").description("Create a new folder in the knowledge base.").requiredOption("--name <name>", "Folder name").option("--parent-id <id>", "Parent folder node ID (omit to create at root)").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = { name: cmdOpts.name };
+      if (cmdOpts.parentId) body.parent_node_id = cmdOpts.parentId;
+      const data = await apiRequest({ method: "POST", path: "/org/kb/folders", body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Folder "${cmdOpts.name}" created.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("rename <id>").description("Rename a KB node.").requiredOption("--name <name>", "New name").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ method: "PATCH", path: `/org/kb/nodes/${id}/rename`, body: { name: cmdOpts.name }, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} renamed to "${cmdOpts.name}".`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("move <id>").description("Move a KB node to a different parent folder.").requiredOption("--parent-id <parentId>", "Target parent folder node ID").action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ method: "PATCH", path: `/org/kb/nodes/${id}/move`, body: { parent_node_id: cmdOpts.parentId }, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} moved.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("delete <id>").description("Delete a KB node (soft delete).").action(async (id) => {
+    const opts = program2.opts();
+    try {
+      await apiRequest({ method: "DELETE", path: `/org/kb/nodes/${id}`, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} deleted.`);
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("create-raw").description("Create a raw (text/markdown) content item in the knowledge base.").requiredOption("--data <json>", 'JSON: { "name": "My doc", "text": "# Hello", "kb_folder_node_id": "<uuid>" }').action(async (cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "POST", path: "/org/kb/raw", body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success("Raw content node created.");
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("update-raw <id>").description("Fully replace the text content of a raw KB node (creates a new version).").requiredOption("--data <json>", 'JSON: { "text": "# Updated content" }').action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "PUT", path: `/org/kb/nodes/${id}/raw`, body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} content replaced.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("patch-raw <id>").description("Partially update the text content of a raw KB node.").requiredOption("--data <json>", 'JSON: { "text": "Updated text", "name": "New name" }').action(async (id, cmdOpts) => {
+    const opts = program2.opts();
+    try {
+      const body = JSON.parse(cmdOpts.data);
+      const data = await apiRequest({ method: "PATCH", path: `/org/kb/nodes/${id}/raw`, body, apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      success(`Node ${id} content patched.`);
+      console.log(JSON.stringify(data, null, 2));
+    } catch (err) {
+      error(err instanceof SyntaxError ? "Invalid JSON in --data" : formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("upload <files...>").description("Upload files to the knowledge base (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker.").option("--folder-id <id>", "Parent folder node ID to place files in (omit for root)").action(async (files, cmdOpts) => {
+    const opts = program2.opts();
+    if (files.length > 10) {
+      error("Maximum 10 files per upload request.");
+      process.exit(1);
+    }
+    try {
+      const fileData = await Promise.all(files.map(getFileMetadata2));
+      const body = { files: fileData.map((f) => f.meta) };
+      if (cmdOpts.folderId) body.kb_folder_node_id = cmdOpts.folderId;
+      const results = await apiRequest({
+        method: "POST",
+        path: "/org/kb/upload",
+        body,
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      const items = Array.isArray(results) ? results : [];
+      let uploaded = 0;
+      for (const item of items) {
+        if (item.status === "upload_pending" && item.upload_url) {
+          const match = fileData.find((f) => f.meta.filename === item.filename);
+          if (match) {
+            await uploadToS32(item.upload_url, match.buffer, match.meta.content_type);
+            uploaded++;
+            success(`Uploaded ${item.filename} (content_id: ${item.content_id})`);
+          }
+        } else {
+          warn(`Skipped ${item.filename}: ${item.status}${item.message ? ` \u2014 ${item.message}` : ""}`);
+        }
+      }
+      if (uploaded > 0) {
+        success(`${uploaded} file(s) uploaded. Background processing will parse, chunk, and embed them.`);
+      }
+      if (opts.output === "json") console.log(JSON.stringify(results, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+  kb.command("update-file <id> <file>").description("Replace the file on an existing KB file node with a new version.").action(async (id, file) => {
+    const opts = program2.opts();
+    try {
+      const { meta, buffer } = await getFileMetadata2(file);
+      const results = await apiRequest({
+        method: "PUT",
+        path: `/org/kb/nodes/${id}/file`,
+        body: { file: meta },
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl
+      });
+      const items = Array.isArray(results) ? results : [];
+      for (const item of items) {
+        if (item.status === "upload_pending" && item.upload_url) {
+          await uploadToS32(item.upload_url, buffer, meta.content_type);
+          success(`Uploaded ${meta.filename} for node ${id}. Background re-processing started.`);
+        } else {
+          warn(`Skipped: ${item.status}${item.message ? ` \u2014 ${item.message}` : ""}`);
+        }
+      }
+      if (opts.output === "json") console.log(JSON.stringify(results, null, 2));
+    } catch (err) {
+      error(formatApiError(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/permissions.ts
+function registerPermissionsCommands(program2) {
+  const perms = program2.command("permissions").description("View available role permissions for the organization.");
+  perms.command("list").description("List all available permission keys with their names, descriptions, and categories. Useful for building role management UIs.").action(async () => {
+    const opts = program2.opts();
+    try {
+      const data = await apiRequest({ path: "/org/permissions", apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+      console.log(JSON.stringify(data, null, 2));
     } catch (err) {
       error(formatApiError(err));
       process.exit(1);
@@ -1422,7 +1949,10 @@ registerContentTypeCommands(program);
 registerPromptCommands(program);
 registerRunConfigCommands(program);
 registerMemberCommands(program);
-registerNotificationCommands(program);
+registerCreditsCommands(program);
+registerQuestionsCommands(program);
+registerKBCommands(program);
+registerPermissionsCommands(program);
 registerUpdateCommand(program);
 async function main() {
   const quiet = process.argv.includes("--quiet") || process.argv.includes("--output") && process.argv[process.argv.indexOf("--output") + 1] === "json";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senso-ai/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Senso CLI — Infrastructure for the Agentic Web. Interact with your Senso knowledge base from the terminal.",
   "type": "module",
   "bin": {