save-pdf-kb

Save a PDF to the knowledge base

Use the installed kb CLI. Resolve <vault> to the directory containing its authored or managed index.md front door, then set the shell-local KB_ROOT to that path (KB_ROOT=kb from a typical repository root).

Check the local conversion routes, then capture the PDF:

kb doctor
kb pdf "/absolute/path/to/document.pdf" --output "$KB_ROOT/articles"
kb pdf "https://example.com/document.pdf" --output "$KB_ROOT/articles"

Pass a stable slug or replace a prior tool-owned bundle only when needed:

kb pdf "/absolute/path/to/document.pdf" --slug ben-leaves-zo --output "$KB_ROOT/articles"
kb pdf "/absolute/path/to/document.pdf" --output "$KB_ROOT/articles" --force

The command installs one atomic bundle:

<slug>/
  <slug>.md
  capture.json
  source.pdf
  annotations.json  # present after a reviewed annotation pass
  assets/

source.pdf is the byte-identical input. The manifest records its original name, hash, byte count, page count, bounded document metadata, processed-page and block counts, image geometry, OCR status, and warnings without retaining the original absolute path. A reviewed second pass also retains the exact normalized annotation array as annotations.json; the manifest records its path, count, byte count, and SHA-256 so the image interpretation remains reproducible.

Preserve text and visual evidence

Treat native PDF text and image text as two independent extraction surfaces. Native text supplies layout, heading, link, and reading-order evidence. Local OCR supplies candidate text for scans and screenshots. Keep every extracted image as an asset even when its text is converted to Markdown.

For recognizable conversations, review the source image and turn OCR into readable message blocks with available platform, author, channel, and timestamp metadata. Preserve uncertain words explicitly instead of silently repairing them. Read references/review.md before refining screenshot-heavy or mixed-media PDFs.