cngkit 1.0.0 → 1.1.1

package/dist/cli.cjs

@@ -7443,7 +7443,7 @@ var logging;
 // src/config.ts
 var import_node_crypto = require("crypto");
 var import_node_process = __toESM(require("process"), 1);
-var packageVersion = "1.0.0";
+var packageVersion = "1.1.1";
 var defaultApiBaseUrl = "https://curly.ng";
 function resolveApiBaseUrl(options) {
   return options.apiBaseUrl ?? import_node_process.default.env.CNGKIT_API_BASE_URL ?? defaultApiBaseUrl;
@@ -7512,6 +7512,426 @@ function browserOpenCommand(url2) {
   return { command: "xdg-open", args: [url2] };
 }
 
+// src/help-specs.ts
+var commandList = [
+  "`cngkit login` - open Curly.ng login.",
+  "`cngkit share [room-code]` - start a live repo sync room.",
+  "`cngkit join <room-code>` - join a live repo sync room.",
+  "`cngkit scrub [path]` - scan for secrets and optionally mask them inline.",
+  "`cngkit knowledges ...` - read the hosted Harness catalog."
+].join("\n");
+var knowledgesCommandList = [
+  "`status` - print remote catalog state.",
+  "`audiences` - list valid audience filters.",
+  "`search <query>` - semantic search over Cloudflare Vectorize-backed records.",
+  "`list [query]` - list known subskills.",
+  "`files [query]` - list uploaded catalog files.",
+  "`read <file-path>` - Claude-style file read.",
+  "`grep <pattern>` - Claude-style content search.",
+  "`glob [pattern]` - Claude-style file discovery."
+].join("\n");
+var helpTopics = [
+  {
+    title: "cngkit",
+    aliases: ["", "overview", "help"],
+    body: `# cngkit
+
+Curly.ng operator CLI for backend-connected repo sync, secret scrubbing, and Harness knowledges access.
+
+## Usage
+
+\`\`\`bash
+cngkit <command> [options]
+\`\`\`
+
+## Commands
+
+${commandList}
+
+## Progressive Help
+
+\`\`\`bash
+cngkit <command> --help
+cngkit knowledges --help
+cngkit knowledges <subcommand> --help
+\`\`\`
+
+The CLI intentionally prints plain Markdown or line-oriented text with no color-only state, tables that require terminal width, or hidden interactive prompts. Add \`--json\` to read-only knowledges commands when another agent or tool needs structured backend data.
+
+## Backend
+
+Default API: \`https://curly.ng\`
+
+Override with:
+
+\`\`\`bash
+cngkit --api-base-url <url> ...
+CNGKIT_API_BASE_URL=<url> cngkit ...
+\`\`\`
+`
+  },
+  {
+    title: "login",
+    aliases: ["login"],
+    body: `# cngkit login
+
+Open Curly.ng login in a browser. In headless environments, print the URL so an agent can surface it to the operator.
+
+## Usage
+
+\`\`\`bash
+cngkit login
+\`\`\`
+
+## Output Contract
+
+- First line names the login URL being opened.
+- If no local browser opener exists, the CLI prints a direct URL.
+- No credentials are printed or persisted by this command.
+`
+  },
+  {
+    title: "share",
+    aliases: ["share", "sync", "repo-sync"],
+    body: `# cngkit share
+
+Start a real-time repository sync room from the current directory.
+
+## Usage
+
+\`\`\`bash
+cngkit share [room-code]
+\`\`\`
+
+## Backend Contract
+
+- Connects to \`/api/cng/sync/:roomCode\` on the configured Curly backend.
+- Uses WebSocket transport backed by the \`CngSyncRoom\` Durable Object.
+- Sends an initial snapshot, then file and delete events.
+- Last received change wins.
+
+## Filesystem Contract
+
+- Preserves \`.git/\`.
+- Preserves files ignored by the repo's \`.gitignore\`.
+- Sends regular files as base64 payloads in the sync protocol.
+
+## Output Contract
+
+- Prints room code, repo root, peer id, backend health, and concise sync events.
+- Keeps running until the socket closes or the process receives a termination signal.
+`
+  },
+  {
+    title: "join",
+    aliases: ["join"],
+    body: `# cngkit join
+
+Join an existing real-time repository sync room in the current directory.
+
+## Usage
+
+\`\`\`bash
+cngkit join <room-code>
+\`\`\`
+
+## Backend Contract
+
+Same transport and filesystem contract as \`cngkit share\`. The supplied room code selects the Durable Object room.
+
+## Output Contract
+
+- Prints backend health, room code, repo root, peer id, and concise sync events.
+- Missing room code exits with a usage error.
+`
+  },
+  {
+    title: "scrub",
+    aliases: ["scrub"],
+    body: `# cngkit scrub
+
+Scan a file or directory for secrets with TruffleHog. Report-only is the default. Inline masking requires \`--yes\`.
+
+## Usage
+
+\`\`\`bash
+cngkit scrub [path]
+cngkit scrub [path] --yes
+\`\`\`
+
+## Requirements
+
+- \`trufflehog\` must be available on \`PATH\`.
+
+## Safety Contract
+
+- Default mode does not rewrite files.
+- \`--yes\` rewrites detected secret values inline with \`[CNGKIT_SECRET:<detector>:<verified|unverified>]\` placeholders.
+- \`--mask\` is accepted as a compatibility alias, but still requires \`--yes\`.
+- Raw and redacted secret values are never printed in the report.
+`
+  },
+  {
+    title: "knowledges",
+    aliases: ["knowledges", "knowledge"],
+    body: `# cngkit knowledges
+
+Read the hosted Harness knowledges catalog from the Curly backend. These commands are read-only and use the generated \`@cng/client\` SDK against public backend routes.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges <subcommand> [options]
+\`\`\`
+
+## Subcommands
+
+${knowledgesCommandList}
+
+## Progressive Help
+
+\`\`\`bash
+cngkit knowledges read --help
+cngkit knowledges grep --help
+cngkit knowledges glob --help
+\`\`\`
+
+## AI-Friendly Output
+
+- Default output is line-oriented and intended to be directly usable by agents.
+- \`read\` prints file content with no wrapper before any truncation note.
+- \`grep --output-mode content\` prints \`path:line\` blocks.
+- \`grep --output-mode files_with_matches\` and \`glob\` print one path per line.
+- \`--json\` prints the typed backend data payload for machine consumption.
+`
+  },
+  {
+    title: "knowledges status",
+    aliases: ["knowledges-status", "status"],
+    body: `# cngkit knowledges status
+
+Print remote Harness catalog state from \`GET /api/harness/knowledges/catalog\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges status [--json]
+\`\`\`
+
+## Output Contract
+
+- Text mode prints catalog name, file count, blob count, Vectorize binding, and latest run when present.
+- \`--json\` prints the backend data payload.
+`
+  },
+  {
+    title: "knowledges audiences",
+    aliases: ["knowledges-audiences", "audiences"],
+    body: `# cngkit knowledges audiences
+
+List valid audience filters from \`GET /api/harness/knowledges/audiences\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges audiences [--json]
+\`\`\`
+
+Use this before \`cngkit knowledges files --audience <id>\`.
+`
+  },
+  {
+    title: "knowledges search",
+    aliases: ["knowledges-search", "search"],
+    body: `# cngkit knowledges search
+
+Run semantic search against the Cloudflare Vectorize-backed Harness index.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges search <query> [--limit <n>] [--json]
+\`\`\`
+
+## Defaults
+
+- \`--limit\`: \`5\`
+
+## Example
+
+\`\`\`bash
+cngkit knowledges search "cloudflare backend" --limit 3
+\`\`\`
+`
+  },
+  {
+    title: "knowledges list",
+    aliases: ["knowledges-list", "list"],
+    body: `# cngkit knowledges list
+
+List known subskills from \`GET /api/harness/knowledges/subskills\`, optionally filtered locally by query.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges list [query] [--limit <n>] [--json]
+\`\`\`
+
+## Defaults
+
+- \`--limit\`: \`25\`
+`
+  },
+  {
+    title: "knowledges files",
+    aliases: ["knowledges-files", "files"],
+    body: `# cngkit knowledges files
+
+List uploaded catalog files from \`GET /api/harness/knowledges/files\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges files [query] [--audience <id>] [--limit <n>] [--json]
+\`\`\`
+
+## Defaults
+
+- \`--limit\`: \`25\`
+- \`--audience\`: omitted
+
+Run \`cngkit knowledges audiences\` to discover supported audience ids.
+`
+  },
+  {
+    title: "knowledges read",
+    aliases: ["knowledges-read", "read"],
+    body: `# cngkit knowledges read
+
+Claude-style read tool for hosted Harness catalog files. Backed by \`GET /api/harness/filesystem/read\` and \`HarnessReadQuerySchema\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges read <file-path> [--offset <n>] [--limit <n>] [--json]
+\`\`\`
+
+## Inputs
+
+- \`file-path\`: normalized catalog path. Shorthand paths such as \`/libraries/lib-cloudflare/SUBSKILL.md\` are expanded to \`skills/knowledges/subskills/libraries/lib-cloudflare/SUBSKILL.md\`.
+- \`--offset\`: zero-based starting line. Default: \`0\`.
+- \`--limit\`: maximum lines. Default in CLI: \`200\`. Backend max: \`2000\`.
+
+## Output Contract
+
+- Text mode prints only the returned file content first.
+- If truncated, a final bracketed truncation note is printed after the content.
+- \`--json\` prints \`{ file_path, content, total_lines, offset, limit, truncated }\`.
+
+## Example
+
+\`\`\`bash
+cngkit knowledges read /libraries/lib-cloudflare/SUBSKILL.md --limit 80
+\`\`\`
+`
+  },
+  {
+    title: "knowledges grep",
+    aliases: ["knowledges-grep", "grep"],
+    body: `# cngkit knowledges grep
+
+Claude-style grep tool for hosted Harness catalog files. Backed by \`GET /api/harness/filesystem/grep\` and \`HarnessGrepQuerySchema\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges grep <pattern> [--path <path>] [--include <glob>] [--output-mode <mode>] [--context <n>] [--case-insensitive] [--json]
+\`\`\`
+
+## Inputs
+
+- \`pattern\`: JavaScript regular expression source.
+- \`--path\`: catalog path prefix. Default: \`/\`.
+- \`--include\`: filename include filter. Default: \`*\`.
+- \`--output-mode\`: \`content\`, \`files_with_matches\`, or \`count\`. Default: \`content\`.
+- \`--context\`: context lines around content matches. Default: \`0\`. Backend max: \`20\`.
+- \`--case-insensitive\`: maps to backend \`case_insensitive=true\`.
+
+## Output Contract
+
+- \`content\`: prints blocks as \`file_path:line_number\`, optional context lines, then \`> matching line\`.
+- \`files_with_matches\`: prints one matching file path per line.
+- \`count\`: prints \`file_path: match_count\` lines.
+- \`--json\` prints the typed backend response union.
+
+## Examples
+
+\`\`\`bash
+cngkit knowledges grep Cloudflare --path /libraries/lib-cloudflare --output-mode files_with_matches
+cngkit knowledges grep "Vectorize|D1" --path /libraries/lib-cloudflare --context 2
+\`\`\`
+`
+  },
+  {
+    title: "knowledges glob",
+    aliases: ["knowledges-glob", "glob"],
+    body: `# cngkit knowledges glob
+
+Claude-style glob tool for hosted Harness catalog files. Backed by \`GET /api/harness/filesystem/glob\` and \`HarnessGlobQuerySchema\`.
+
+## Usage
+
+\`\`\`bash
+cngkit knowledges glob [pattern] [--path <path>] [--json]
+\`\`\`
+
+## Inputs
+
+- \`pattern\`: supported glob pattern. CLI default: \`**/*.md\`.
+- \`--path\`: catalog path prefix. Default: \`/\`.
+
+## Supported Patterns
+
+- \`**/*.md\`
+- \`**/*.SUBSKILL.md\`
+- \`**/SKILL.md\`
+- \`*.md\`
+- \`*.SUBSKILL.md\`
+- \`SKILL.md\`
+
+## Output Contract
+
+- Text mode prints one file path per line.
+- If truncated, a final bracketed truncation note is printed.
+- \`--json\` prints \`{ files, total_files, truncated }\`.
+
+## Example
+
+\`\`\`bash
+cngkit knowledges glob "**/*.md" --path /libraries/lib-cloudflare
+\`\`\`
+`
+  }
+];
+var helpTopicByAlias = /* @__PURE__ */ new Map();
+for (const topic of helpTopics) {
+  for (const alias of topic.aliases) {
+    helpTopicByAlias.set(alias, topic);
+  }
+}
+function formatCngkitHelp(topicName) {
+  const normalizedTopicName = normalizeHelpTopicName(topicName);
+  return (helpTopicByAlias.get(normalizedTopicName) ?? helpTopicByAlias.get(""))?.body.trim() ?? "";
+}
+function formatKnowledgesHelp(topicName) {
+  const normalizedTopicName = normalizeHelpTopicName(topicName);
+  const topicKey = normalizedTopicName ? `knowledges-${normalizedTopicName}` : "knowledges";
+  return formatCngkitHelp(topicKey);
+}
+function normalizeHelpTopicName(value) {
+  return value?.trim().toLowerCase().replace(/\s+/g, "-") ?? "";
+}
+
 // src/scrub/masker.ts
 var import_promises = __toESM(require("fs/promises"), 1);
 var import_node_path = __toESM(require("path"), 1);
@@ -24296,6 +24716,35 @@ async function waitForSessionClose(socket, watcher) {
 }
 
 // src/commands.ts
+async function runKnowledgesCommand(args, options, output, dependencies) {
+  const [subcommand, ...subcommandArgs] = args ?? [];
+  if (subcommand === void 0 || subcommand === "help") {
+    output.info(formatKnowledgesHelp(subcommandArgs[0]));
+    return;
+  }
+  switch (subcommand) {
+    case "status":
+      return runKnowStatusCommand(options, output, dependencies);
+    case "audiences":
+      return runKnowAudiencesCommand(options, output, dependencies);
+    case "search":
+      return runKnowSearchCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    case "list":
+      return runKnowListCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    case "files":
+      return runKnowFilesCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    case "read":
+      return runKnowReadCommand(subcommandArgs[0], options, output, dependencies);
+    case "grep":
+      return runKnowGrepCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    case "glob":
+      return runKnowGlobCommand(optionalJoinedArgument(subcommandArgs), options, output, dependencies);
+    default:
+      throw new Error(
+        "Missing knowledges command. Usage: cngkit knowledges <status|audiences|search|list|files|read|grep|glob>"
+      );
+  }
+}
 async function runLoginCommand(options, output) {
   const loginUrl = new URL("/login", resolveApiBaseUrl(options));
   const loginUrlString = loginUrl.toString();
@@ -24344,6 +24793,172 @@ async function runScrubCommand(targetPath, options, output, dependencies) {
     output.info(`Skipped ${result.skippedFindings} finding(s) outside the scrub root.`);
   }
 }
+async function runKnowStatusCommand(options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.getCatalog();
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  const latestRun = response.data.latestRun;
+  const lines = [
+    `Catalog: ${response.data.name}`,
+    `Files: ${response.data.files}`,
+    `Blobs: ${response.data.blobs}`,
+    `Vectorize: ${response.data.vectorize.index} (${response.data.vectorize.binding})`
+  ];
+  if (latestRun) {
+    lines.push(`Latest run: ${latestRun.status} (${latestRun.id})`);
+    if (latestRun.updated_at) {
+      lines.push(`Updated: ${latestRun.updated_at}`);
+    }
+  } else {
+    lines.push("Latest run: none");
+  }
+  output.info(lines.join("\n"));
+}
+async function runKnowAudiencesCommand(options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.listAudiences();
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  const lines = response.data.audiences.flatMap((audience) => [
+    `${audience.id} - ${audience.label}`,
+    `  ${singleLine(audience.help)}`
+  ]);
+  output.info(lines.length > 0 ? lines.join("\n") : "No audiences available.");
+}
+async function runKnowSearchCommand(query, options, output, dependencies) {
+  if (!query) {
+    throw new Error("Missing search query. Usage: cngkit knowledges search <query>");
+  }
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.search(query, coerceLimit(options.limit, 5));
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  const lines = response.data.results.flatMap((result, index) => [
+    `${index + 1}. ${result.title} (${result.subskillName})`,
+    `   score ${result.score.toFixed(3)} | ${result.path}`,
+    `   ${singleLine(result.description || result.contentPreview)}`
+  ]);
+  output.info(lines.length > 0 ? lines.join("\n") : `No results for "${query}".`);
+}
+async function runKnowListCommand(query, options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.listSubskills();
+  const limit = coerceLimit(options.limit, 25);
+  const normalizedQuery = query?.toLowerCase();
+  const subskills = response.data.subskills.filter((subskill) => {
+    if (!normalizedQuery) {
+      return true;
+    }
+    return [subskill.name, subskill.title, subskill.description, subskill.type].join(" ").toLowerCase().includes(normalizedQuery);
+  }).slice(0, limit);
+  if (options.json) {
+    output.info(formatJson({ subskills, total: subskills.length }));
+    return;
+  }
+  const lines = subskills.flatMap((subskill) => [
+    `${subskill.name} [${subskill.type}]`,
+    `  ${subskill.title} | files ${subskill.fileCount} | rating ${subskill.rating}`,
+    `  ${singleLine(subskill.description)}`
+  ]);
+  output.info(lines.length > 0 ? lines.join("\n") : "No matching subskills.");
+}
+async function runKnowFilesCommand(query, options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.listFiles({
+    query,
+    audience: normalizeAudienceId(options.audience),
+    limit: coerceLimit(options.limit, 25)
+  });
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  const lines = response.data.files.map((file2) => {
+    const title = file2.display_title ?? file2.title ?? file2.subskill_name ?? "Untitled";
+    return `${file2.path}
+  ${title}`;
+  });
+  output.info(lines.length > 0 ? lines.join("\n") : "No matching files.");
+}
+async function runKnowReadCommand(filePath, options, output, dependencies) {
+  if (!filePath) {
+    throw new Error("Missing file_path. Usage: cngkit knowledges read <file_path>");
+  }
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.read({
+    filePath: normalizeCatalogPath(filePath),
+    offset: coerceOptionalNumber(options.offset),
+    limit: coerceLimit(options.limit, 200, 2e3)
+  });
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  output.info(response.data.content);
+  if (response.data.truncated) {
+    output.info(
+      `[truncated: showing ${response.data.limit} lines from offset ${response.data.offset} of ${response.data.total_lines}]`
+    );
+  }
+}
+async function runKnowGrepCommand(pattern, options, output, dependencies) {
+  if (!pattern) {
+    throw new Error("Missing pattern. Usage: cngkit knowledges grep <pattern>");
+  }
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.grep({
+    pattern,
+    path: normalizeCatalogPath(options.path ?? "/"),
+    include: options.include ?? "*",
+    mode: normalizeGrepMode(options.outputMode),
+    context: coerceLimit(options.context, 0, 20),
+    ignoreCase: options.caseInsensitive === true
+  });
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  if (response.data.mode === "files_with_matches") {
+    output.info(
+      response.data.files.length > 0 ? response.data.files.join("\n") : `No files matched "${pattern}".`
+    );
+    return;
+  }
+  if (response.data.mode === "count") {
+    const lines2 = response.data.counts.map((count) => `${count.file_path}: ${count.match_count}`);
+    output.info(lines2.length > 0 ? lines2.join("\n") : `No matches for "${pattern}".`);
+    return;
+  }
+  const lines = response.data.matches.flatMap((match) => [
+    `${match.file_path}:${match.line_number}`,
+    ...match.context_before.map((line) => `  ${line}`),
+    `> ${match.line}`,
+    ...match.context_after.map((line) => `  ${line}`)
+  ]);
+  output.info(lines.length > 0 ? lines.join("\n") : `No matches for "${pattern}".`);
+}
+async function runKnowGlobCommand(pattern, options, output, dependencies) {
+  const api = dependencies?.api ?? createKnowledgesApi(options);
+  const response = await api.glob({
+    pattern: pattern ?? "**/*.md",
+    path: normalizeCatalogPath(options.path ?? "/")
+  });
+  if (options.json) {
+    output.info(formatJson(response.data));
+    return;
+  }
+  output.info(response.data.files.length > 0 ? response.data.files.join("\n") : "No matching files.");
+  if (response.data.truncated) {
+    output.info(`[truncated: ${response.data.total_files} total files]`);
+  }
+}
 async function printBackendStatus(options, output) {
   const health = await readBackendHealth(options);
   output.info(health.ok ? `API: ${health.service} ready` : `API: unavailable (${health.message})`);
@@ -24366,6 +24981,121 @@ function formatScrubReport(findings) {
   }
   return lines.join("\n");
 }
+function createKnowledgesApi(options) {
+  const client = createCngApiClient(options);
+  return {
+    getCatalog: () => client.harnessKnowledges.getHarnessKnowledgesCatalog(),
+    listAudiences: () => client.harnessKnowledges.listHarnessKnowledgesAudiences(),
+    search: (query, limit) => client.harnessKnowledges.searchHarnessKnowledges({
+      q: query,
+      limit
+    }),
+    listSubskills: () => client.harnessKnowledges.listHarnessKnowledgesSubskills(),
+    listFiles: ({ query, audience, limit }) => client.harnessKnowledges.listHarnessSubskillAssets({
+      ...query ? { q: query } : {},
+      ...audience ? { audience } : {},
+      limit
+    }),
+    read: ({ filePath, offset, limit }) => client.harnessFilesystem.getHarnessFilesystemRead({
+      file_path: filePath,
+      offset,
+      limit
+    }),
+    grep: ({ pattern, path: path5, include, mode, context, ignoreCase }) => client.harnessFilesystem.getHarnessFilesystemGrep({
+      pattern,
+      path: path5,
+      include,
+      output_mode: mode,
+      context,
+      case_insensitive: ignoreCase ? "true" : void 0
+    }),
+    glob: ({ pattern, path: path5 }) => client.harnessFilesystem.getHarnessFilesystemGlob({
+      pattern,
+      path: path5
+    })
+  };
+}
+function coerceLimit(value, defaultValue, maxValue = 100) {
+  const normalizedValue = coerceOptionalNumber(value);
+  if (normalizedValue === void 0 || Number.isNaN(normalizedValue)) {
+    return defaultValue;
+  }
+  return Math.max(defaultValue === 0 ? 0 : 1, Math.min(maxValue, Math.trunc(normalizedValue)));
+}
+function coerceOptionalNumber(value) {
+  if (value === void 0 || value === "") {
+    return void 0;
+  }
+  return Number(value);
+}
+function normalizeAudienceId(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  switch (value) {
+    case "all":
+    case "operators":
+    case "builders":
+    case "researchers":
+    case "agent-makers":
+      return value;
+    default:
+      throw new Error(
+        `Unknown audience "${value}". Run cngkit knowledges audiences to see supported values.`
+      );
+  }
+}
+function normalizeGrepMode(value) {
+  if (value === void 0) {
+    return "content";
+  }
+  switch (value) {
+    case "content":
+    case "files_with_matches":
+    case "count":
+      return value;
+    default:
+      throw new Error("Unknown grep mode. Use one of: content, files_with_matches, count.");
+  }
+}
+function singleLine(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function formatJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+function optionalJoinedArgument(values) {
+  return values.length > 0 ? values.join(" ") : void 0;
+}
+function normalizeCatalogPath(value) {
+  const trimmed = value.trim();
+  if (trimmed === "/" || trimmed === "") {
+    return "/";
+  }
+  const relativePath = trimmed.replace(/^\/+/, "");
+  if (relativePath.startsWith("skills/knowledges/")) {
+    return relativePath;
+  }
+  const [firstSegment, ...restSegments] = relativePath.split("/");
+  if (!firstSegment || restSegments.length === 0) {
+    return relativePath;
+  }
+  switch (firstSegment) {
+    case "concepts":
+    case "domains":
+    case "formats":
+    case "languages":
+    case "libraries":
+    case "patterns":
+    case "platforms":
+    case "procedures":
+    case "protocols":
+    case "tools":
+      return `skills/knowledges/subskills/${firstSegment}/${restSegments.join("/")}`;
+    default:
+      return relativePath;
+  }
+}
 
 // src/output.ts
 var consoleOutput = {
@@ -24386,6 +25116,34 @@ function handleFatalError(error51) {
   consoleOutput.error(formatError2(error51));
   import_node_process5.default.exitCode = 1;
 }
+function printMarkdownHelpIfRequested(argv) {
+  const commandName = argv[2];
+  if (commandName === void 0 || commandName === "--help" || commandName === "-h") {
+    consoleOutput.info(formatCngkitHelp());
+    return true;
+  }
+  if (commandName === "help") {
+    const [topicName, subtopicName] = argv.slice(3);
+    const topic = topicName === "knowledges" && subtopicName ? `knowledges-${subtopicName}` : topicName;
+    consoleOutput.info(formatCngkitHelp(topic));
+    return true;
+  }
+  const commandArgs = argv.slice(3);
+  const helpIndex = commandArgs.findIndex((argument) => argument === "--help" || argument === "-h");
+  if (helpIndex < 0) {
+    return false;
+  }
+  if (commandName === "knowledges") {
+    const topic = commandArgs.find((argument, index) => index !== helpIndex && !argument.startsWith("-"));
+    consoleOutput.info(formatKnowledgesHelp(topic));
+    return true;
+  }
+  consoleOutput.info(formatCngkitHelp(commandName));
+  return true;
+}
+if (printMarkdownHelpIfRequested(import_node_process5.default.argv)) {
+  import_node_process5.default.exit(0);
+}
 cli.option(
   "--api-base-url <url>",
   "Curly API base URL. Default: CNGKIT_API_BASE_URL or https://curly.ng"
@@ -24402,6 +25160,9 @@ cli.command("join <room-code>", "Join a real-time repo sync room in the current
 cli.command("scrub [path]", "Scan for secrets with TruffleHog and optionally mask them inline").option("--mask", "Compatibility alias for inline scrubbing; --yes is still required").option("--yes", "Confirm and run inline scrubbing").action((targetPath, options) => {
   void runScrubCommand(targetPath, options, consoleOutput).catch(handleFatalError);
 });
+cli.command("knowledges [...args]", "Use the Cloudflare-backed Harness knowledges catalog").option("--limit <n>", "Maximum results").option("--audience <id>", "Audience filter").option("--offset <n>", "Starting line offset").option("--path <path>", "Catalog path prefix").option("--include <glob>", "Filename include filter").option("--output-mode <mode>", "Output mode: content, files_with_matches, count").option("--context <n>", "Context lines around content matches").option("--case-insensitive", "Case-insensitive search").option("--json", "Print raw JSON").action((args, options) => {
+  void runKnowledgesCommand(args, options, consoleOutput).catch(handleFatalError);
+});
 try {
   cli.parse(import_node_process5.default.argv);
 } catch (error51) {