Vault Ingest

Vault Ingest

Overview

Discipline skill for multimodal capture into the vault as fleeting notes. Detects input modality (voice, image, PDF, YouTube, screenshot), verifies the required transcription or OCR tool is installed, dispatches capture-normalizer to produce a clean transcript, presents the transcript for user approval, and writes a frontmatter-annotated fleeting note to the vault inbox. Every capture produces a note with status: draft, type: fleeting, and full provenance fields so downstream skills (process-notes, vault-schema) can reason about it.

When to Use

• Ingesting voice memos (.m4a, .wav, .mp3) into the vault with transcription.
• Capturing screenshots or images (.png, .jpg, .heic) via OCR.
• Importing PDF content into a single fleeting note.
• Capturing YouTube videos via auto-subtitle download.

When NOT to use

• Processing fleeting notes that are already in the vault — use process-notes.
• Atomizing long captured notes into permanent atomic notes — use process-notes as a follow-up after capture.
• Proposing [[wikilinks]] between notes — use vault-connect.
• Importing research reports or brainstorm outputs — use vault-research.

Constants

• TASK_DIR: .mz/task/
• INBOX_FOLDER: inbox/
• MAXTRANSCRIPTPREVIEW: 500 (words shown in the approval gate; longer transcripts are truncated with ...)
• VOICEMAXDURATION_SEC: 3600 (warn before transcribing audio longer than 1 hour)
• PDFMAXPAGES: 50 (warn before extracting from PDFs longer than this)

Core Process

| Phase | Goal | Details | | ----- | ---------------------------- | --------------------------------- | | 0 | Setup | Inline below | | 1 | Detect tooling + transcribe | phases/detect_and_transcribe.md | | 1.5 | User approval — transcript | Inline below | | 2 | Write fleeting note to vault | phases/approve_and_write.md |

Phase 0: Setup

1. Parse $ARGUMENTS. First argument is the input path or URL. Second argument (optional) is an explicit modality hint: voice, image, pdf, or youtube.
2. If the first argument is empty, ask the user via AskUserQuestion what to ingest. Never guess.
3. Detect modality from the input:

• Extension .m4a, .wav, .mp3 → voice.
• Extension .png, .jpg, .jpeg, .heic → image (record source_type: screenshot if user confirmed it is a screenshot, else image).
• Extension .pdf → pdf.
• URL containing youtube.com or youtu.be → youtube.
• If the second argument is present, it overrides the detected modality.
• If modality cannot be inferred and no hint was given, ask via AskUserQuestion.

1. Resolve the vault path with precedence: $OBSIDIAN_VAULT_PATH → $MZ_VAULT_PATH → walk up from cwd to the nearest .obsidian/ directory. If none found, ask via AskUserQuestion.
2. Derive task_name = _vault-ingest_ where ` is today's date (underscores); on same-day collision append v2, v3. Create TASK_DIR/` on disk.
3. Write state.md with schema_version: 2, Status: running, Phase: 0, Started: , Input: , Modality: , Vault: , phase_complete: false, what_remains: [].

Phase 1.5: User Approval — Transcript

This orchestrator (not a subagent) presents this gate. This step is interactive and must not be delegated.

Pre-read: Read .mz/task//transcript.md and capture the full contents into context. Note the modality, tool, and duration/pages from the frontmatter.

Surface 1 — emit the plan message. Output the transcript verbatim as a normal markdown chat message (truncated at MAX_TRANSCRIPT_PREVIEW words with a trailing ... when longer):

## Transcript ready for review — vault-ingest

Transcript produced from . Modality: , transcription tool: , duration/pages: .

---
**Approve** → proceed to Phase 2, write the fleeting note to the vault  ·  **Reject** → task marked aborted, no fleeting note written  ·  reply with feedback to revise

Emit the full verbatim contents of .mz/task//transcript.md (transcript body, up to MAX_TRANSCRIPT_PREVIEW words) — do not substitute a path, summary, or placeholder.

Surface 2 — call AskUserQuestion. A short selector — do not re-embed the transcript in the question body, it lives in the plan message above:

• question: The transcript above is ready for review.
• options:
• Approve — proceed to Phase 2, write the fleeting note to the vault
• Reject — abort, no fleeting note written

Response handling:

• Approve → update state to transcript_approved, proceed to Phase 2.
• Reject → update state to aborted_by_user and stop. Do not proceed.
• Any other reply (feedback) → common feedback is "try a different tool" (switch whisper-cpp → whisper, ocrit → tesseract) or "the transcript is truncated, rerun". Incorporate the feedback, re-run Phase 1 with the adjusted tool choice, return to this gate, re-read .mz/task//transcript.md, and re-emit the entire plan message from scratch (never diff-only). This is a loop — repeat until the user explicitly approves. Never proceed to Phase 2 without explicit approval.

Techniques

Techniques: delegated to phase files — see Phase Overview table above.

Common Rationalizations

| Rationalization | Rebuttal | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | "The tool is missing — just write an empty fleeting note with a source link." | "An empty note with provenance metadata masquerading as captured content is worse than no note at all — it pollutes future search and appears 'processed' when it is not. Escalate via BLOCKED." | | "Skip the approval gate — the user already chose to capture this." | "Tool output is noisy: VTT timestamps survive, whisper inserts [inaudible], OCR mangles layout. The approval gate exists so the user sees what the vault will actually contain." | | "Transcript has garbage — ship it anyway, the user can fix it in Obsidian." | "Captured notes are the raw intake layer for the entire pipeline. Bad captures propagate into atomization, linking, and Q&A. Either a fallback tool recovers quality or the user says BLOCKED." |

Red Flags

• Dispatching capture-normalizer before running which detection.
• Writing a fleeting note with an empty body because the transcription tool failed.
• Presenting the approval gate as a path or one-line status instead of the verbatim transcript.
• Skipping the modality detection step and guessing from filename alone when $ARGUMENTS[2] was provided.
• Writing to the vault root or to /permanent/ instead of //.
• Omitting source_type, captured_at, or status: draft from the frontmatter.

Verification

Print this block before concluding — silent checks get skipped:

vault-ingest verification:
  [ ] Tool detection logged to tooling.md before capture-normalizer dispatch
  [ ] Transcript shown verbatim via AskUserQuestion before any vault write
  [ ] Fleeting note written under // with source_type + captured_at + status: draft
  [ ] state.md Status is `complete` with Completed timestamp

If any box is unchecked, the skill did not run correctly — report the failure explicitly rather than claiming success.

State Management

State persists to .mz/task//state.md. Schema is v2: the file's first line is schema_version: 2, and alongside the skill's existing Status / Phase / Started keys it carries phase_complete (boolean) and what_remains (YAML list of strings). Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass; refresh what_remains on every phase transition; what_remains MUST be [] when Status: complete. On reading a schema_version: 1 or unversioned file, add the missing keys, set schema_version: 2, and log the upgrade.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DoctorMozg
• Source: DoctorMozg/claude-pipelines
• License: MIT

Install and usage instructions live in the source repository linked above.