hraness 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.
The first capture supplies stable image IDs and hashes in capture.json.
For screenshot-heavy documents, write reviewed interpretations to a JSON array
and rerun the capture:
[
{
"id": "page-5-image-1-0123456789ab",
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"kind": "mixed",
"method": "agent",
"markdown": "> bg @ Oct 15, 2024 at 4:26 PM\n> Message text",
"metadata": {
"platform": "Slack",
"contentType": "message screenshot",
"author": "bg",
"timestamp": "Oct 15, 2024 at 4:26 PM",
"participants": ["bg"]
}
}
]
kb pdf "/absolute/path/to/document.pdf" \
--output "$KB_ROOT/articles" \
--annotations /tmp/pdf-image-annotations.json \
--force
Use only IDs and SHA-256 values from the first manifest. The command rejects a
stale interpretation if the extracted image changed. Omit metadata fields that
are not visible, and use kind: "visual" with an optional alt instead of
inventing a transcription for a non-text image. Put only the transcribed body
in markdown; the renderer owns the image embed, “Text visible in…” heading,
and visible metadata line.
Embed primarily visual images in the Markdown. For text-bearing or mixed images, keep the source image embedded beside the transcription so diagrams, photos, UI state, and spatial meaning remain inspectable. The embed is the source-image reference; do not duplicate it inside an annotation.
Heading inference follows native font, emphasis, spacing, and page geometry. Review semantic hierarchy separately: typography can identify a heading without proving whether it is a peer or a child of the preceding section. Report an ambiguous or incorrect level instead of silently treating the inference as source truth.
Report completeness literally
Use complete only when every page was processed and every extracted image was
classified. Preserve partial when a tool, page, image, byte, time, or OCR
boundary was reached. A usable native-text extraction does not make
unprocessed screenshot pages complete.
Review:
- Compare the manifest page count with the PDF.
- Review inferred headings and report ambiguous or incorrect hierarchy.
- Sample native-text, screenshot, scanned, and visual-only pages.
- Confirm every retained asset resolves from the Markdown or manifest.
- Check that source-image links accompany OCR-derived text.
- Report the output path, status, page and image counts, OCR coverage, and unresolved warnings.
After adding or linking the capture, run the vault's normal refresh and check:
kb percolate "<maintained-note-id>" --root "$KB_ROOT" --limit 25 --json
kb refresh --root "$KB_ROOT"
kb check --root "$KB_ROOT"