Bootstrap a new document shelf at shelf_path.

Creates the directory layout (docs/, INDEX.md, .docshelf.json, .gitignore), pre-creates any default_categories, and stores the github_remote so generated INDEX entries link to raw GitHub URLs.

Idempotent — safe to call on an existing shelf to update metadata.

Add a PDF or Markdown file to the shelf and refresh INDEX.md.

• .pdf is converted to Markdown (pymupdf4llm by default; pass quality='high' to use marker-pdf).

• Documents larger than 50 KB with multiple H2 headings are split into one file per section (turn this off with split=False).

• If a different title/category slugifies onto a path an existing document already occupies, the call errors instead of overwriting it — pass overwrite=true to replace it. Re-adding the same title updates in place. The response reports overwritten.

• The response warnings include suspicious section headings and an empty-conversion warning when the source yields little or no text (e.g. a scanned / image-only PDF — consider quality='high' / OCR).

• INDEX.md is regenerated automatically. The caller still owns the git commit / push step.

Add every matching file in a directory, rebuilding INDEX.md once.

Scans source_dir (non-recursively) for patterns — every supported input type by default (Markdown, PDF, DOCX, HTML, EPUB) — adds each under category with a title derived from its filename, and regenerates INDEX.md a single time. A corrupt or unreadable file is reported in failed without aborting the batch.

Read a document or section file from inside the shelf's docs/.

Returns the file content directly over MCP — useful for private or purely-local shelves where the raw.githubusercontent.com fetch trick doesn't apply. Pass a relative_path from search / list_documents. Large files are truncated to max_bytes (default 100 KB) with truncated: true; page with the returned next_offset (slices snap to UTF-8 character boundaries, so it may differ from offset + max_bytes — using it avoids splitting a multibyte character) or read the individual split sections. Paths that escape docs/ are rejected.

Remove a document — its file, split sections, and metadata entry.

Accepts the filename, the slug, or the human title used at add time. INDEX.md is regenerated automatically. Pass dry_run=true to see what would be deleted without touching anything. The caller still owns the git commit / push step.

Retitle, recategorize, or re-describe a document — no re-conversion.

Moves the document .md, its split-section directory, and its .meta.json entry (changing the slug when the title changes, or the directory when the category changes), then regenerates INDEX.md. Give at least one of new_title / new_category / new_description. Refuses to clobber an existing target. Pass dry_run=true to preview. The caller still owns the git commit / push step.

Regenerate INDEX.md from the current on-disk shelf state.

Useful after manual edits to docs/ or .docshelf.json.

Check the shelf for drift and optionally apply the safe fixes.

Reports stale .meta.json entries, orphaned split directories, split sections out of sync with their parent, a stale INDEX.md, duplicate titles, and empty categories. Read-only by default; pass fix=true to prune stale meta entries, delete orphaned split dirs, and rebuild the index (other findings stay report-only). Findings are sorted for stable diffing.

Plain-text search across every Markdown file in the shelf.

Tokens are space-split; each must appear (case-insensitive) for a hit to count. If no file contains all tokens, the search falls back to any-token matching and the response reports match_mode: "any". Heading/title matches are ranked above body-only matches, and for a split document the section files are returned rather than the whole-file parent. Results include the relative path, a word-boundary-trimmed snippet, and — if a remote is configured — the fetch URL so the model can pull the matching file directly.

List documents grouped by category.

Pass a category to filter; omit it to list everything.

Standalone PDF → Markdown conversion (no shelf, no INDEX update).

Use when you want the converted file but don't yet want to commit it to a shelf. Optionally splits the result by H2.