cngkit 1.1.18 → 1.1.20

package/dist/chunk-SKK2XLRZ.js

@@ -0,0 +1,1590 @@
+// src/cli/help-specs.ts
+import { createElement } from "react";
+
+// src/cli/help-components.tsx
+import { Box, Text } from "ink";
+import { jsx, jsxs } from "react/jsx-runtime";
+function HelpDocument({ document }) {
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx(Text, { bold: true, color: "magenta", children: document.heading }),
+    document.blocks.map((block, index) => /* @__PURE__ */ jsx(HelpBlockView, { block }, `${block.kind}-${index}`))
+  ] });
+}
+function HelpBlockView({ block }) {
+  if (block.kind === "section") {
+    return /* @__PURE__ */ jsx(Box, { marginTop: 1, children: /* @__PURE__ */ jsx(Text, { bold: true, color: "blue", children: block.title }) });
+  }
+  if (block.kind === "paragraph") {
+    return /* @__PURE__ */ jsx(Box, { children: /* @__PURE__ */ jsx(Text, { wrap: "wrap", children: /* @__PURE__ */ jsx(InlineText, { text: block.text }) }) });
+  }
+  if (block.kind === "list") {
+    return /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: block.items.map((item, index) => /* @__PURE__ */ jsxs(Text, { wrap: "wrap", children: [
+      /* @__PURE__ */ jsx(Text, { color: "cyan", children: "- " }),
+      /* @__PURE__ */ jsx(InlineText, { text: item })
+    ] }, `${item}-${index}`)) });
+  }
+  return /* @__PURE__ */ jsx(Box, { flexDirection: "column", marginLeft: 2, children: block.lines.map((line, index) => /* @__PURE__ */ jsx(Text, { color: "green", children: line }, `${line}-${index}`)) });
+}
+function InlineText({ text }) {
+  return text.split(/(`[^`]+`)/g).map((part, index) => {
+    const isCodeSpan = part.startsWith("`") && part.endsWith("`") && part.length > 1;
+    if (isCodeSpan) {
+      return /* @__PURE__ */ jsx(Text, { color: "cyan", children: part.slice(1, -1) }, `${part}-${index}`);
+    }
+    return part;
+  });
+}
+
+// src/cli/help-topic-content.ts
+var helpTopicDocuments = [
+  {
+    title: "cngkit",
+    aliases: ["", "overview", "help"],
+    heading: "cngkit",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "CNG operator CLI for shared code rooms, safe local cleanup, local agent transcripts, and hosted Harness knowledges."
+      },
+      {
+        kind: "section",
+        title: "Run Now"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "npx --yes cngkit@latest --help",
+          "npx --yes cngkit@latest knowledges search Cloudflare --limit 3"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Installed Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit <command> [options]"]
+      },
+      {
+        kind: "section",
+        title: "Global Options"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit --format text|json|markdown ...", "cngkit --no-color ..."]
+      },
+      {
+        kind: "section",
+        title: "Commands"
+      },
+      {
+        kind: "list",
+        items: [
+          "`cngkit login` - open browser login, or print the URL in headless shells.",
+          "`cngkit coderoom ...` - share or join a live developer room for a working tree.",
+          "`cngkit scrub [path]` - scan for secrets; rewrite only when `--yes` is passed.",
+          "`cngkit transcripts ...` - list, read, and grep local Claude/Codex transcripts.",
+          "`cngkit knowledges ...` - search and read the hosted Harness knowledge catalog.",
+          "`cngkit hooks ...` - install Hookify forwarding hooks into supported AI coding tools.",
+          "`cngkit hookify ...` - forward local hook events to Hookify."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Help Map"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit help <topic>",
+          "cngkit <command> --help",
+          "cngkit coderoom --help",
+          "cngkit coderoom <subcommand> --help",
+          "cngkit transcripts --help",
+          "cngkit hooks --help",
+          "cngkit hooks install --help",
+          "cngkit hooks uninstall --help",
+          "cngkit knowledges --help",
+          "cngkit knowledges <subcommand> --help",
+          "cngkit hookify --help",
+          "cngkit hookify ingest --help"
+        ]
+      },
+      {
+        kind: "section",
+        title: "AI And Scripts"
+      },
+      {
+        kind: "list",
+        items: [
+          "Help renders as structured terminal text by default, even in pipes.",
+          "Use `--format json` or `--json` on read-only data commands for typed payloads.",
+          "Use `--format markdown` only when raw Markdown source is intentional.",
+          "Use `--no-color` or `CNGKIT_COLOR=never` for logs, screenshots, and strict plain text.",
+          "Use `npm_config_progress=false npx --yes cngkit@latest ...` for clean one-shot npx captures."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Backend"
+      },
+      {
+        kind: "paragraph",
+        text: "API: `https://curly.ng`"
+      }
+    ]
+  },
+  {
+    title: "login",
+    aliases: ["login"],
+    heading: "cngkit login",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Open browser login. In headless shells, print the URL so an agent can show it to the operator."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["npx --yes cngkit@latest login", "cngkit login"]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "First line names the login URL being opened.",
+          "If no browser opener exists, the CLI prints a direct URL.",
+          "No credentials are printed or persisted by this command."
+        ]
+      }
+    ]
+  },
+  {
+    title: "transcripts",
+    aliases: ["transcripts", "transcript"],
+    heading: "cngkit transcripts",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Read local Claude and Codex transcript JSONL files."
+      },
+      {
+        kind: "paragraph",
+        text: "This is local-only operator tooling. It does not call the backend and it does not upload transcript content."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit transcripts list [--source all|codex|claude] [--limit <n>] [--json|--format json]",
+          "cngkit transcripts read <path-or-session-id> [--source all|codex|claude] [--limit <n>] [--include-internal] [--json|--format json]",
+          "cngkit transcripts grep <query> [--source all|codex|claude] [--limit <n>] [--file-limit <n>] [--include-internal] [--json|--format json]"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Sources"
+      },
+      {
+        kind: "list",
+        items: [
+          "`~/.codex/sessions`",
+          "`~/.codex/archived_sessions`",
+          "`~/.claude/projects`",
+          "`~/.claude/history.jsonl`"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Defaults"
+      },
+      {
+        kind: "list",
+        items: [
+          "`list`: newest 12 transcript files.",
+          "`read`: newest 80 user/assistant entries from the selected file.",
+          "`grep`: first 80 matching user/assistant entries from the newest 60 files.",
+          "`--source`: `all`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints source, role, timestamp when available, and extracted message text.",
+          "Internal developer/system payloads and hook/tool noise are skipped unless `--include-internal` is passed.",
+          "Direct file paths, home-relative paths, and partial session ids are accepted by `read`."
+        ]
+      }
+    ]
+  },
+  {
+    title: "hookify",
+    aliases: ["hookify"],
+    heading: "cngkit hookify",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Forward local hook events to Hookify."
+      },
+      {
+        kind: "paragraph",
+        text: "Hookify is the hosted hook processing surface. The CLI stays small: it reads hook payloads locally, forwards raw stdin to the backend, prints the backend stdout, and exits with the backend exit code. If forwarding fails, it exits with code 0."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit hookify <subcommand> [options]"]
+      },
+      {
+        kind: "section",
+        title: "Subcommands"
+      },
+      {
+        kind: "list",
+        items: ["`ingest` - read a raw hook payload from stdin and forward it to the backend."]
+      }
+    ]
+  },
+  {
+    title: "hooks",
+    aliases: ["hooks"],
+    heading: "cngkit hooks",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Install local Hookify forwarding hooks into supported AI-assisted coding tools."
+      },
+      {
+        kind: "paragraph",
+        text: "The installer writes user-level config for documented hook surfaces and preserves existing non-cngkit hooks. Re-running it is idempotent: old cngkit Hookify entries are replaced with one current entry per event."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit hooks <subcommand> [options]"]
+      },
+      {
+        kind: "section",
+        title: "Subcommands"
+      },
+      {
+        kind: "list",
+        items: [
+          "`install` - install Hookify forwarding hooks into supported AI coding tools.",
+          "`uninstall` - remove cngkit Hookify forwarding hooks from supported AI coding tools."
+        ]
+      }
+    ]
+  },
+  {
+    title: "hooks install",
+    aliases: ["hooks-install"],
+    heading: "cngkit hooks install",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Install Hookify forwarding hooks into supported AI-assisted coding tools."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit hooks install [--tool all|claude|codex] [--dry-run]"]
+      },
+      {
+        kind: "section",
+        title: "Behavior"
+      },
+      {
+        kind: "list",
+        items: [
+          "Configures Claude Code at `~/.claude/settings.json`.",
+          "Configures Codex at `~/.codex/hooks.json`.",
+          "Preserves existing hook handlers that do not call `cngkit hookify ingest`.",
+          "Replaces older cngkit Hookify handlers to avoid duplicates.",
+          "Uses `cngkit hookify ingest --event <EventName>` for every supported event, avoiding npm package resolution in hook hot paths."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Examples"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit hooks install --dry-run",
+          "cngkit hooks install",
+          "cngkit hooks install --tool codex"
+        ]
+      }
+    ]
+  },
+  {
+    title: "hooks uninstall",
+    aliases: ["hooks-uninstall"],
+    heading: "cngkit hooks uninstall",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Remove cngkit Hookify forwarding hooks from supported AI-assisted coding tools."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit hooks uninstall [--tool all|claude|codex] [--dry-run]"]
+      },
+      {
+        kind: "section",
+        title: "Behavior"
+      },
+      {
+        kind: "list",
+        items: [
+          "Reads Claude Code at `~/.claude/settings.json`.",
+          "Reads Codex at `~/.codex/hooks.json`.",
+          "Removes cngkit Hookify handlers installed with either the current direct `cngkit hookify ingest` command or older `cngkit@latest` npm/npx commands.",
+          "Preserves all non-cngkit hook handlers and all other settings.",
+          "Reports the exact config file, handler count, and event names changed."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Examples"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit hooks uninstall --dry-run",
+          "cngkit hooks uninstall",
+          "cngkit hooks uninstall --tool claude"
+        ]
+      }
+    ]
+  },
+  {
+    title: "hookify ingest",
+    aliases: ["hookify-ingest"],
+    heading: "cngkit hookify ingest",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Read a raw hook payload from stdin and forward it to Hookify."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit hookify ingest [--event <name>] [--async]"]
+      },
+      {
+        kind: "section",
+        title: "Behavior"
+      },
+      {
+        kind: "list",
+        items: [
+          "Reads stdin exactly as the hook provides it.",
+          "Sends the payload to `POST /api/hookify/ingest` as `application/octet-stream`.",
+          "Handles both immediate backend results and workflow-backed pending results.",
+          "Polls `GET /api/hookify/requests/<requestId>` when the backend returns a pending request.",
+          "Prints backend `stdout` without extra formatting.",
+          "Writes backend `stderr` when present.",
+          "Uses backend `exitCode` as the process exit code.",
+          "Falls back to exit code `0` if the backend request fails.",
+          "`--async` tells the backend that workflow-backed processing is acceptable; the local command still waits for the final hook result."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [`printf '{"hook":"PreToolUse"}' | cngkit hookify ingest --event PreToolUse`]
+      }
+    ]
+  },
+  {
+    title: "coderoom",
+    aliases: ["coderoom", "code-room", "repo-sync"],
+    heading: "cngkit coderoom",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Create or join a temporary live room for sharing a working tree over the configured backend."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit coderoom <subcommand> [options]"]
+      },
+      {
+        kind: "section",
+        title: "Subcommands"
+      },
+      {
+        kind: "list",
+        items: [
+          "`share [room-code]` - start a live room from the current directory.",
+          "`join <room-code>` - join another developer's live room from the current directory."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Common Flow"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "npx --yes cngkit@latest coderoom share",
+          "npx --yes cngkit@latest coderoom join <room-code>"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Behavior"
+      },
+      {
+        kind: "list",
+        items: [
+          "Connects to `/api/cng/sync/:roomCode` on the configured backend.",
+          "Uses WebSocket transport backed by the `CngSyncRoom` Durable Object.",
+          "Sends an initial snapshot, then file and delete events.",
+          "Last received change wins.",
+          "Current rooms are live relays, not durable cloud storage."
+        ]
+      }
+    ]
+  },
+  {
+    title: "coderoom share",
+    aliases: ["coderoom-share"],
+    heading: "cngkit coderoom share",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Start a live repository sync room from the current directory."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit coderoom share [room-code]"]
+      },
+      {
+        kind: "section",
+        title: "Behavior"
+      },
+      {
+        kind: "list",
+        items: [
+          "Connects to `/api/cng/sync/:roomCode` on the configured backend.",
+          "Uses WebSocket transport backed by the `CngSyncRoom` Durable Object.",
+          "Sends an initial snapshot, then file and delete events.",
+          "Last received change wins."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Filesystem Contract"
+      },
+      {
+        kind: "list",
+        items: [
+          "Preserves `.git/`.",
+          "Preserves files ignored by the repo's `.gitignore`.",
+          "Sends regular files as base64 payloads in the sync protocol."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "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: "coderoom join",
+    aliases: ["coderoom-join"],
+    heading: "cngkit coderoom join",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Join an existing live repository sync room from the current directory."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit coderoom join <room-code>"]
+      },
+      {
+        kind: "section",
+        title: "Behavior"
+      },
+      {
+        kind: "paragraph",
+        text: "Same transport and filesystem contract as `cngkit coderoom share`. The supplied room code selects the Durable Object room."
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "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"],
+    heading: "cngkit scrub",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Scan a file or directory for secrets with TruffleHog. Report-only is the default."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit scrub [path]", "cngkit scrub [path] --yes"]
+      },
+      {
+        kind: "section",
+        title: "Safety"
+      },
+      {
+        kind: "list",
+        items: [
+          "Default mode does not rewrite files.",
+          "Inline masking rewrites files and requires `--yes`.",
+          "Raw and redacted secret values are never printed."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Requirements"
+      },
+      {
+        kind: "list",
+        items: ["`trufflehog` must be available on `PATH`."]
+      },
+      {
+        kind: "section",
+        title: "Mask Format"
+      },
+      {
+        kind: "code",
+        language: "text",
+        lines: ["[CNGKIT_SECRET:<detector>:<verified|unverified>]"]
+      }
+    ]
+  },
+  {
+    title: "knowledges",
+    aliases: ["knowledges", "knowledge"],
+    heading: "cngkit knowledges",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Search and read the hosted Harness knowledges catalog from the configured backend."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges <subcommand> [options]"]
+      },
+      {
+        kind: "section",
+        title: "Subcommands"
+      },
+      {
+        kind: "list",
+        items: [
+          "`status` - print remote catalog state.",
+          "`audiences` - list valid audience filters.",
+          "`search <query>` - search over Postgres-backed knowledges records.",
+          "`list [query]` - list known topics.",
+          "`files [query]` - list uploaded catalog files.",
+          "`ls [path]` - list remote catalog directory entries.",
+          "`tree [path]` - print a remote catalog directory tree.",
+          "`cat <file-path>` - print a remote catalog file as raw text.",
+          "`head <file-path>` - print the first lines of a remote catalog file.",
+          "`tail <file-path>` - print the last lines of a remote catalog file.",
+          "`stat <path>` - print remote catalog path metadata.",
+          "`find [path]` - find remote catalog paths by name and type.",
+          "`realpath <path>` - normalize a topics-root catalog path.",
+          "`read <file-path>` - Claude-style file read.",
+          "`grep <pattern>` - Claude-style content search.",
+          "`glob [pattern]` - Claude-style file discovery."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Progressive Help"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit help knowledges <subcommand>",
+          "cngkit knowledges <subcommand> --help",
+          "cngkit knowledges read --help",
+          "cngkit knowledges ls --help",
+          "cngkit knowledges tree --help",
+          "cngkit knowledges cat --help",
+          "cngkit knowledges head --help",
+          "cngkit knowledges tail --help",
+          "cngkit knowledges find --help",
+          "cngkit knowledges stat --help",
+          "cngkit knowledges realpath --help",
+          "cngkit knowledges grep --help",
+          "cngkit knowledges glob --help"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Common Examples"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "npx --yes cngkit@latest knowledges search Cloudflare --limit 3",
+          "npx --yes cngkit@latest knowledges ls /",
+          "npx --yes cngkit@latest knowledges tree /libraries --depth 2",
+          "npx --yes cngkit@latest knowledges cat /libraries/lib-cloudflare/TOPIC.md",
+          "npx --yes cngkit@latest knowledges head /libraries/lib-cloudflare/TOPIC.md -n 20",
+          "npx --yes cngkit@latest knowledges tail /libraries/lib-cloudflare/TOPIC.md -n 20",
+          'npx --yes cngkit@latest knowledges find /libraries -name "*cloudflare*" -type f',
+          "npx --yes cngkit@latest knowledges stat /libraries/lib-cloudflare/TOPIC.md",
+          "npx --yes cngkit@latest knowledges realpath /libraries/lib-cloudflare",
+          "npx --yes cngkit@latest knowledges read /libraries/lib-cloudflare/TOPIC.md --limit 80",
+          "npx --yes cngkit@latest knowledges grep Cloudflare --path /libraries/lib-cloudflare --output-mode files_with_matches",
+          'npx --yes cngkit@latest knowledges glob "**/*.md" --path /libraries/lib-cloudflare'
+        ]
+      },
+      {
+        kind: "section",
+        title: "AI-Friendly Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Default output is structured text intended to be directly usable by people and agents.",
+          "`ls` prints one name per line; directories end with `/`. Use `--long` or `-l` for type, path, and metadata fields.",
+          "`tree` prints a deterministic plain-text tree; directories end with `/`.",
+          "`cat`, `head`, and `tail` print raw file content only in text mode.",
+          "`find` prints one resolved path per line.",
+          "`read` renders Markdown files by default and prints exact source with `--format markdown`.",
+          "`grep --output-mode content` prints `path:line` blocks.",
+          "`grep --output-mode files_with_matches` and `glob` print one path per line.",
+          "`--format json` and `--json` print typed backend payloads for machine consumption."
+        ]
+      }
+    ]
+  },
+  {
+    title: "knowledges status",
+    aliases: ["knowledges-status", "status"],
+    heading: "cngkit knowledges status",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Print remote Harness catalog state."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges status [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints catalog name, file count, blob count, and database binding.",
+          "`--format json` and `--json` print the backend data payload."
+        ]
+      }
+    ]
+  },
+  {
+    title: "knowledges audiences",
+    aliases: ["knowledges-audiences", "audiences"],
+    heading: "cngkit knowledges audiences",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "List valid audience filters for catalog browsing."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges audiences [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Use When"
+      },
+      {
+        kind: "paragraph",
+        text: "Run this before `cngkit knowledges files --audience <id>`."
+      }
+    ]
+  },
+  {
+    title: "knowledges search",
+    aliases: ["knowledges-search", "search"],
+    heading: "cngkit knowledges search",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Search the hosted Harness index for relevant skills and topics."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges search <query> [--limit <n>] [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Defaults"
+      },
+      {
+        kind: "list",
+        items: ["`--limit`: `5`"]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["npx --yes cngkit@latest knowledges search Cloudflare --limit 3"]
+      }
+    ]
+  },
+  {
+    title: "knowledges list",
+    aliases: ["knowledges-list", "list"],
+    heading: "cngkit knowledges list",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "List hosted Harness topics, optionally filtered by query."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges list [query] [--limit <n>] [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Defaults"
+      },
+      {
+        kind: "list",
+        items: ["`--limit`: `25`"]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges list cloudflare --limit 10"]
+      }
+    ]
+  },
+  {
+    title: "knowledges files",
+    aliases: ["knowledges-files", "files"],
+    heading: "cngkit knowledges files",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "List uploaded Harness catalog files, optionally filtered by query or audience."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit knowledges files [query] [--audience <id>] [--limit <n>] [--json|--format json]"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Defaults"
+      },
+      {
+        kind: "list",
+        items: ["`--limit`: `25`", "`--audience`: omitted"]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit knowledges files cloudflare --limit 10",
+          'cngkit knowledges files "vector search" --audience builders'
+        ]
+      }
+    ]
+  },
+  {
+    title: "knowledges ls",
+    aliases: ["knowledges-ls", "ls"],
+    heading: "cngkit knowledges ls",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "List immediate children for a hosted Harness catalog directory."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit knowledges ls [path] [--limit <n>] [--json|--format json]",
+          "cngkit knowledges ls [path] --long"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Inputs"
+      },
+      {
+        kind: "list",
+        items: [
+          "`path`: topics-root path prefix. Default: `/`, the hosted equivalent of `~/.agents/topics`.",
+          "`--limit`: maximum entries. Default: `100`. CLI max: `1000`.",
+          "`--long`, `-l`: print type, path, and tab-separated metadata."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints one entry name per line. Directories end with `/`.",
+          "Long text mode prints one entry per line as tab-separated `type`, `path`, and metadata fields.",
+          "Directories are sorted before files, then by path.",
+          "`--format json` and `--json` print `{ path, entries, total_entries, truncated }`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Examples"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit knowledges ls /",
+          "cngkit knowledges ls /libraries/lib-cloudflare",
+          "cngkit knowledges ls /libraries/lib-cloudflare -l"
+        ]
+      }
+    ]
+  },
+  {
+    title: "knowledges tree",
+    aliases: ["knowledges-tree", "tree"],
+    heading: "cngkit knowledges tree",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Print a plain-text tree for a hosted Harness catalog directory."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges tree [path] [--depth <n>] [--limit <n>] [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Defaults"
+      },
+      {
+        kind: "list",
+        items: ["`path`: `/`", "`--depth`: `3`", "`--limit`: `500`"]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints deterministic indented lines.",
+          "Directories end with `/`.",
+          "`--format json` and `--json` print `{ path, entries, total_entries, truncated, depth }`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges tree /libraries --depth 2"]
+      }
+    ]
+  },
+  {
+    title: "knowledges cat",
+    aliases: ["knowledges-cat", "cat"],
+    heading: "cngkit knowledges cat",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Print a hosted Harness catalog file as raw text."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges cat <file-path> [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints returned file content only.",
+          "`--format json` and `--json` print the typed backend read payload."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges cat /libraries/lib-cloudflare/TOPIC.md"]
+      }
+    ]
+  },
+  {
+    title: "knowledges head",
+    aliases: ["knowledges-head", "head"],
+    heading: "cngkit knowledges head",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Print the first lines of a hosted Harness catalog file as raw text."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges head <file-path> [-n <lines>] [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Defaults"
+      },
+      {
+        kind: "list",
+        items: ["`-n`, `--lines`: `10`"]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints returned file content only.",
+          "`--format json` and `--json` print the typed backend read payload."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges head /libraries/lib-cloudflare/TOPIC.md -n 20"]
+      }
+    ]
+  },
+  {
+    title: "knowledges tail",
+    aliases: ["knowledges-tail", "tail"],
+    heading: "cngkit knowledges tail",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Print the last lines of a hosted Harness catalog file as raw text."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges tail <file-path> [-n <lines>] [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Defaults"
+      },
+      {
+        kind: "list",
+        items: ["`-n`, `--lines`: `10`"]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints returned file content only.",
+          "`--format json` and `--json` print the typed backend tail payload."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges tail /libraries/lib-cloudflare/TOPIC.md -n 20"]
+      }
+    ]
+  },
+  {
+    title: "knowledges find",
+    aliases: ["knowledges-find", "find"],
+    heading: "cngkit knowledges find",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Find hosted Harness catalog paths below a directory."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit knowledges find [path] [-name <pattern>] [-type f|d] [--max-depth <n>] [--limit <n>] [--json|--format json]"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Defaults"
+      },
+      {
+        kind: "list",
+        items: ["`path`: `/`", "`--limit`: `500`"]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints one resolved path per line.",
+          "Directory paths end with `/`.",
+          "`--format json` and `--json` print `{ path, entries, total_entries, truncated }`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ['cngkit knowledges find /libraries -name "*cloudflare*" -type f']
+      }
+    ]
+  },
+  {
+    title: "knowledges stat",
+    aliases: ["knowledges-stat", "stat"],
+    heading: "cngkit knowledges stat",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Print metadata for one hosted Harness catalog file or inferred directory."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges stat <path> [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Inputs"
+      },
+      {
+        kind: "list",
+        items: [
+          "`path`: topics-root path. `/libraries/lib-cloudflare/TOPIC.md` means `~/.agents/topics/libraries/lib-cloudflare/TOPIC.md`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints stable `key=value` lines.",
+          "`--format json` and `--json` print the typed backend path metadata."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges stat /libraries/lib-cloudflare/TOPIC.md"]
+      }
+    ]
+  },
+  {
+    title: "knowledges realpath",
+    aliases: ["knowledges-realpath", "realpath"],
+    heading: "cngkit knowledges realpath",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Normalize a topics-root catalog path without calling the backend."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges realpath <path> [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Inputs"
+      },
+      {
+        kind: "list",
+        items: [
+          "`path`: topics-root catalog path.",
+          "`/` is the hosted equivalent of `~/.agents/topics`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints the normalized topics-root path.",
+          "`--format json` and `--json` print `{ path }`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Examples"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit knowledges realpath /",
+          "cngkit knowledges realpath /libraries/lib-cloudflare"
+        ]
+      }
+    ]
+  },
+  {
+    title: "knowledges read",
+    aliases: ["knowledges-read", "read"],
+    heading: "cngkit knowledges read",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Read a hosted Harness catalog file by path."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit knowledges read <file-path> [--offset <n>] [--limit <n>] [--json|--format json|--format markdown]"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Inputs"
+      },
+      {
+        kind: "list",
+        items: [
+          "`file-path`: topics-root file path. `/libraries/lib-cloudflare/TOPIC.md` means `~/.agents/topics/libraries/lib-cloudflare/TOPIC.md`.",
+          "`--offset`: zero-based starting line. Default: `0`.",
+          "`--limit`: maximum lines. Default in CLI: `200`. Backend max: `2000`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode renders Markdown files for terminal reading.",
+          "`--format markdown` prints the exact returned file content.",
+          "If truncated, a final bracketed truncation note is printed after the content.",
+          "`--format json` and `--json` print `{ file_path, content, total_lines, offset, limit, truncated }`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "npx --yes cngkit@latest knowledges read /libraries/lib-cloudflare/TOPIC.md --limit 80"
+        ]
+      }
+    ]
+  },
+  {
+    title: "knowledges grep",
+    aliases: ["knowledges-grep", "grep"],
+    heading: "cngkit knowledges grep",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Search inside hosted Harness catalog files with a JavaScript regular expression."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "cngkit knowledges grep <pattern> [--path <path>] [--include <glob>] [--output-mode <mode>] [--context <n>] [--case-insensitive] [--json|--format json]"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Inputs"
+      },
+      {
+        kind: "list",
+        items: [
+          "`pattern`: JavaScript regular expression source.",
+          "`--path`: topics-root path prefix. Default: `/`.",
+          "`--include`: filename include filter. Default: `*`.",
+          "Modes: content, files_with_matches, or count.",
+          "`--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`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "`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.",
+          "`--format json` and `--json` print the typed backend response union."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Examples"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          "npx --yes cngkit@latest knowledges grep Cloudflare --path /libraries/lib-cloudflare --output-mode files_with_matches",
+          'npx --yes cngkit@latest knowledges grep "Postgres|Hyperdrive" --path /libraries/lib-cloudflare --context 2'
+        ]
+      }
+    ]
+  },
+  {
+    title: "knowledges glob",
+    aliases: ["knowledges-glob", "glob"],
+    heading: "cngkit knowledges glob",
+    blocks: [
+      {
+        kind: "paragraph",
+        text: "Find hosted Harness catalog files by glob pattern."
+      },
+      {
+        kind: "section",
+        title: "Usage"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: ["cngkit knowledges glob [pattern] [--path <path>] [--json|--format json]"]
+      },
+      {
+        kind: "section",
+        title: "Inputs"
+      },
+      {
+        kind: "list",
+        items: [
+          "`pattern`: supported glob pattern. CLI default: `**/*.md`.",
+          "`--path`: topics-root path prefix. Default: `/`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Supported Patterns"
+      },
+      {
+        kind: "list",
+        items: [
+          "`**/*.md`",
+          "`**/TOPIC.md`",
+          "`**/*.TOPIC.md`",
+          "`**/SKILL.md`",
+          "`*.md`",
+          "`TOPIC.md`",
+          "`*.TOPIC.md`",
+          "`SKILL.md`"
+        ]
+      },
+      {
+        kind: "section",
+        title: "Output"
+      },
+      {
+        kind: "list",
+        items: [
+          "Text mode prints one file path per line.",
+          "If truncated, a final bracketed truncation note is printed.",
+          "`--format json` and `--json` print `{ files, total_files, truncated }`."
+        ]
+      },
+      {
+        kind: "section",
+        title: "Example"
+      },
+      {
+        kind: "code",
+        language: "bash",
+        lines: [
+          'npx --yes cngkit@latest knowledges glob "**/*.md" --path /libraries/lib-cloudflare'
+        ]
+      }
+    ]
+  }
+];
+
+// src/cli/help-specs.ts
+var helpTopicNames = helpTopicDocuments.filter((topic) => topic.title !== "cngkit").map((topic) => topic.title).sort();
+var helpTopicByAlias = /* @__PURE__ */ new Map();
+for (const topic of helpTopicDocuments) {
+  for (const alias of topic.aliases) {
+    helpTopicByAlias.set(alias, topic);
+  }
+}
+function renderCngkitHelp(topicName) {
+  const normalizedTopicName = normalizeHelpTopicName(topicName);
+  const topic = helpTopicByAlias.get(normalizedTopicName);
+  if (topic) {
+    return createElement(HelpDocument, { document: topic });
+  }
+  if (normalizedTopicName === "") {
+    const defaultTopic = helpTopicByAlias.get("");
+    if (defaultTopic) {
+      return createElement(HelpDocument, { document: defaultTopic });
+    }
+  }
+  return createElement(HelpDocument, {
+    document: {
+      title: "cngkit help",
+      aliases: [],
+      heading: "cngkit help",
+      blocks: [
+        {
+          kind: "paragraph",
+          text: `No help topic named ${normalizedTopicName}.`
+        },
+        {
+          kind: "section",
+          title: "Available Topics"
+        },
+        {
+          kind: "list",
+          items: helpTopicNames
+        },
+        {
+          kind: "section",
+          title: "Usage"
+        },
+        {
+          kind: "code",
+          language: "bash",
+          lines: ["cngkit help <topic>", "cngkit <command> --help"]
+        }
+      ]
+    }
+  });
+}
+function renderKnowledgesHelp(topicName) {
+  const normalizedTopicName = normalizeHelpTopicName(topicName);
+  const topicKey = normalizedTopicName ? `knowledges-${normalizedTopicName}` : "knowledges";
+  return renderCngkitHelp(topicKey);
+}
+function normalizeHelpTopicName(value) {
+  return value?.trim().toLowerCase().replace(/\s+/g, "-") ?? "";
+}
+
+export {
+  renderCngkitHelp,
+  renderKnowledgesHelp
+};
+//# sourceMappingURL=chunk-SKK2XLRZ.js.map