kb-ingest

/kb-ingest

Download an external documentation site into the personal knowledge base as a doc pack and source note. Safe to run from any working directory.

Input

Scope: $ARGUMENTS

Two forms:

Web crawl: <url> [category] [tool] [version] [path_prefix] [selector]

Local copy: <local-path> [category] [tool] [version]

• url or local-path — required. An https:// URL to crawl, or an absolute/relative path to a local directory of already-downloaded docs.
• category — optional. Where in raw/external/ to file the pack (e.g. providers, tooling, protocols, languages, libraries).
• tool — optional. Tool/service name slug (e.g. fastmail, jmap, uv).
• version — optional. Defaults to latest.
• path_prefix — optional (web only). Limits crawl to URLs with this prefix. Leave empty to crawl from root.
• selector — optional (web only). CSS selector for content extraction. Defaults to main.

---

Step 1: Resolve the KB path

Run ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-kb-path.sh and capture its stdout as kb_path. Every subsequent command uses "$kb_path" (double-quoted).

kb_path=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-kb-path.sh")

If the script exits non-zero, relay its stderr message to the user verbatim and stop — do not guess a fallback path.

---

Step 2: Parse arguments and classify

Extract the first token from $ARGUMENTS. Detect mode:

• If it starts with /, ~/, or ./ → local mode (copy from a local directory; skip the web crawl)
• Otherwise → web mode (crawl from the URL)

In local mode, resolve the source path:

src_path=$(realpath "$first_token" 2>/dev/null)
[ -d "$src_path" ] || { echo "Source path not found"; exit 1; }

If category and tool are not provided, derive them from the URL domain (web mode) or ask once (local mode):

Domain	category	tool
fastmail.com	providers	fastmail
jmap.io	protocols	jmap
anthropic.com	providers	anthropic
openai.com	providers	openai
docs.*.com or similar	ask	ask