/obsidian-ingest

description: Ingest a source or a resumable folder batch into the vault - update entities, consolidate concepts, and resolve contradictions.
category: research
triggers_en: ["ingest this source", "add this article", "import this", "absorb this"]
triggers_de: ["diese Quelle übernehmen", "diesen Artikel hinzufügen", "das importieren", "das in meinen Vault aufnehmen"]
triggers_es: ["haz una ingesta de esta fuente", "añade este artículo", "importa esto", "absorbe esto", "mete esto al vault", "procesa esta fuente"]
triggers_pt: ["ingira esta fonte", "adicione este artigo", "importe isto", "absorva isto"]
triggers_zh: ["把这篇文章纳入知识库", "导入这份资料", "用这个来源更新我的笔记", "消化这份材料"]

Use the obsidian-second-brain skill. Execute `/obsidian-ingest $ARGUMENTS`:

The argument is a URL, file path, directory path, or pasted text. If no argument, ask what to ingest. A directory invokes the procedure below; a single source follows steps 1-9 as before.

Directory ingestion

Examples: `/obsidian-ingest First-Brain/ --preview`, `/obsidian-ingest Sources/ --batch-size 10`. Warm start is the First Brain use case of this general procedure; no specific vault layout is required.

1. Read `_CLAUDE.md`, resolve destinations through `references/folder-map.md`, and treat the selected source collection as read-only for every worker. Preserve bytes and paths; never consolidate back into it. If a destination overlaps the source collection, stop and resolve routing with the user. Do not automatically switch layouts. Honor sensitive-content permissions; selecting a folder does not override its private subfolders. 2. Discover paths with the helper bundled at `SKILL_ROOT/scripts/ingest_batch.py`:

   uv run --directory "SKILL_ROOT" scripts/ingest_batch.py --vault "VAULT" discover "SOURCE" --output "DESTINATION"

Substitute the actual vault/source paths and repeat `--output` for every resolved knowledge, raw, daily, board, research, log, and Bases destination. Discovery does not read source bodies. It covers Markdown/plain text (`.md`, `.markdown`, `.txt`), PDF (`.pdf`), Office/OpenDocument text (`.docx`, `.doc`, `.odt`, format `document`, converted to PDF by the single-source handler, which needs LibreOffice), audio (`.m4a`, `.mp3`, `.wav`, `.ogg`, `.webm`), and images (`.png`, `.jpg`, `.jpeg`, `.webp`), case-insensitively. Existing scan exclusions and `.vault-config.json` directory/path exclusions apply; `exclude-link-scan` is not an ingestion exclusion. Generated output and linked paths are excluded. Excluded directory entries represent pruned directories, not a count of their unread descendants. Do not follow embedded URLs or add unsupported format readers. 3. Resolve read permissions before hashing. For `--preview`, show discovered formats, exclusions, destinations, and known extraction requirements, then stop without writing logs or captures. Otherwise call `plan`, replacing `discover` above, and add `--allow "PERMITTED_PATH"` for approved scopes, `--block "PRIVATE_PATH"` for denied descendants, and `--limit N` (default 10, positive). No `--allow` grants no reads. Add `--raw-root "RAW_DESTINATION"` immediately after `--vault "VAULT"` when the raw route is custom. Map command `--batch-size` to helper `--limit`. Plan hashes permitted files and reads capture headers and completion receipts; it does not extract content. 4. Process the returned `batch` sequentially, finishing one source's full steps 1-9 before starting another. Reuse the plan's raw capture when present and continue consolidation from its body, skipping transcription/OCR/read extraction. Otherwise use the existing source handler below. Newly captured local files retain the planned `source_path` and full byte `source_file_hash`; existing canonical `content_hash` deduplication remains unchanged. Preserve earlier captures. Keep transcripts, PDF extracts, and image descriptions in their existing raw destinations with accurate `capture_scope`; do not claim binary archival. Preserve the current rewrite policy and per-source catalog, daily-note, and normal operation-log updates. Include the completion append in the normal approval batch when confirmation is required. Only after all required work and approvals finish, call:

   uv run --directory "SKILL_ROOT" scripts/ingest_batch.py --vault "VAULT" complete

Supply JSON on stdin containing exactly `source_path`, the planned `source_file_hash`, and the actual `raw_path`. Pass the same `--raw-root` for a custom route. Use JSON stdin, not shell-interpolated source text. The helper verifies unchanged source bytes and an existing published raw capture. It records the agent's completion attestation, not semantic extraction quality. On failure, missing capabilities, changed source bytes, or pending/declined required approvals, do not call `complete`; report the unfinished work and retain any published capture. Stop on unresolved approval. Never change an original to restore its hash. 5. Stop after the selected batch (or earlier for extraction/session limits) and report discovered, excluded, skipped unchanged, completed this run, failed, blocked, and pending sources, plus remaining work. Repeat the same folder command for the next batch or to retry unfinished work after an interrupted session has stopped. No resume or retry flag is needed. Unresolved proposals are regenerated against current pages. Sources blocked by read permissions are reconsidered only after permission is granted. A repeatedly failing source may need to be fixed, explicitly excluded, or handled separately to allow later batches to advance.

Completion format and recovery

Write a new capture to a temporary sibling ending in `.tmp`, then publish its final `.md` path by atomic rename only after the capture is complete and the source byte hash still matches. Never replace an existing immutable capture. Recovery ignores unpublished temporary files; validate and publish a complete one or discard the incomplete tempo