Vault Ingest

---
name: vault-ingest
description:
  Use when raw vault captures need classification, routing, relocation, and
  external-source synthesis from the source inbox into the right vault surfaces
---

# Vault Ingest

Categorize captures in `raw/sources/`, route owned/user-authored material to the
right vault directories, and synthesize tagged external sources into curated
notes while preserving complete source evidence.

Portent reference: `../references/portent-knowledge-base-spec.md`.

## Parameters

- `--mode report|apply` (default: `report`)
  - `report`: preview all planned operations
  - `apply`: execute confirmed operations
- `--path PATH` (optional): override default `./raw/sources` input path

## Core Contract

For each ingestion cycle:

- Source starts in `raw/sources/` (unprocessed inbox)
- The source file itself remains the durable artifact
- Each source is classified by intent, topic, and lifecycle state before moving
- Every capture is classified into a Portent lifecycle state first: `captured`,
  `organized`, or `archived`
- Every organized durable object gets a Portent `type`
- Every organized object should have enough relationship metadata to explain
  future usefulness:
  - `belongs_to` for primary context when one exists
  - `related_to` for secondary associations
- If a capture cannot attach to a Project, Responsibility, Operation, or Topic,
  leave it in `raw/sources/` and report it as a delete/ignore candidate
- Source files move to the most specific existing vault location when they are
  owned/user-authored material or working source records
- Owned notes, project ideas, drafts, and planning captures are moved intact
  rather than summarized
- Notes tagged `external` are browser-clipped or imported external sources and
  should be synthesized during apply-mode processing unless the user explicitly
  requests routing only
- When a capture duplicates or extends an existing note, idea, project, or
  resource, merge it into that destination when confidence is high
- Any source that is summarized or synthesized must keep a complete immutable
  copy in `raw/processed/YYYY-MM-DD/`
- Summaries or synthesized research briefs must link to the archived complete
  source record
- Navigation is updated only for moved durable files that belong in active
  navigation
- All material operations are logged in `log.md`
- `raw/processed/` is audited for empty folders and anomalies

## Routing Rules

Prefer the vault's existing directory taxonomy. Do not invent new top-level
folders when an existing one fits.

| Source category         | Destination pattern                                                                |
| ----------------------- | ---------------------------------------------------------------------------------- |
| Rough owned idea        | `ideas/fleeting/<idea>/`                                                           |
| Promising project idea  | `ideas/incubating/<idea>/`                                                         |
| Later/someday idea      | `ideas/someday/<idea>/` or the closest existing idea                               |
| Rejected/closed idea    | `ideas/rejected/<idea>/`                                                           |
| Active project material | `projects/active/<project>/`                                                       |
| Durable conceptual note | `notes/concepts/` only when it is itself canonical                                 |
| General durable note    | `notes/<topic>/` or the closest existing note area                                 |
| `external` reference    | Archive source in `raw/processed/YYYY-MM-DD/`; write synthesis to `notes/<topic>/` |
| Asset or binary support | `raw/assets/` or an existing asset folder                                          |
| No clear durable home   | Leave in `raw/sources/` and report the ambiguity                                   |

When an owned/user-authored source clearly belongs with an existing project,
idea, or note, move it there even if the file is messy. Preserve the original
content and filename unless a minimal rename is needed to avoid collision or
clarify the source identity.

## Merge Rules

Prefer a single durable note or folder when multiple captures are clearly about
the same thing. Merge only when the relationship is obvious: same project, same
idea, same source, same canonical concept, or one file is a direct continuation
of another.

- In `report` mode, propose merge target, evidence, confidence, and link
  rewrites.
- In `apply` mode, merge high-confidence captures into the existing durable
  destination.
- Preserve all user-authored content. Move unmatched sections under clear
  headings instead of summarizing them away.
- Keep provenance by retaining source filename, capture date, or a backlink to
  the moved/merged file.
- When confidence is medium or low, route the file beside the likely target and
  report a manual merge decision instead of merging.
- Do not merge merely related but distinct ideas; link them instead.

## Capture Decision

Use `raw/sources/` only for unclassified captures. If the user already
identifies the item as their own idea, route it to `ideas/` directly:

- `ideas/fleeting/`: quick idea, fragment, or unqualified possibility
- `ideas/incubating/`: idea with enough shape to revisit or develop
- `ideas/someday/`: intentionally parked idea
- `ideas/rejected/`: idea explicitly declined but worth retaining as history

External articles, discussions, docs, and market references captured with
Obsidian Note Clipper should carry an `external` tag. That tag tells ingestion
the note came from an outside source and should be synthesized by default while
preserving the complete clipped note.

X bookmark source records are captured by `vault-x-bookmarks`. If the task is to
delete irrelevant, minimal, or low-value bookmark captures from `raw/sources/`,
use `vault-x-bookmarks` prune mode instead of ingest. Ingest routes sources
worth keeping; it does not judge bookmark source value for deletion.

Recognize `external` in either common Obsidian form:

- frontmatter list or scalar: `tags: [external]`, `tags: external`
- inline tag: `#external`

## Copy vs Synthesize Decision

Default to moving or merging owned/user-authored sources intact. Default to
synthesizing tagged `external` sources during apply-mode processing. Synthesize
untagged sources only when the user explicitly asks to summarize/synthesize a
specific source.

Plain copy/move/merge is correct when:

- The file is user-authored, an owned idea, a project draft, a plan, meeting
  note, scratch note, or decision record
- The note's wording, structure, or roughness is itself useful context
- The capture is short enough that summarizing would mainly discard nuance
- The user asks to organize, categorize, move, link, or merge

Synthesis is correct when:

- The note has an `external` tag from Obsidian Note Clipper or another external
  capture path
- The user explicitly asks for synthesis, summary, takeaways, assessment,
  comparison, or research
- Multiple external sources need to be combined into a brief

When synthesis happens, first move the complete source under
`raw/processed/YYYY-MM-DD/`, then write the synthesis with links to those
archived source records. The synthesis should live in the most specific curated
destination, such as `notes/<topic>/`, `projects/.../research/`, or
`ideas/.../research/`. The archived complete source is the immutable citation
target.

## Workflow

1. **Scan** `raw/sources/` for unprocessed captures (skip hidden files)
2. **Classify** each capture:
   - Identify whether it is PORT (`Project`, `Operation`, `Responsibility`,
     `Task`) or ENTP (`Event`, `Note`, `Topic`, `Person`)
   - Assign `status: captured|organized|archived`
   - Identify source origin: owned, external, asset, operational record
   - Identify primary `belongs_to` candidate
   - Identify useful `related_to` candidates
   - Match against existing `projects/`, `ideas/`, `notes/`, and indexed Topic
     objects
   - Mark confidence as high, medium, or low
3. **Plan moves**:
   - Choose the most specific destination path
   - Detect filename collisions and propose minimal safe renames
   - Detect duplicate or continuation captures and propose merge targets
   - Check for the `external` tag and plan archive + synthesis by default
   - Leave low-confidence items in place and list the decision needed
4. **Move, merge, or synthesize** high-confidence sources:
   - Move owned/user-authored sources intact to their destination paths
   - Archive tagged external sources under `raw/processed/YYYY-MM-DD/`
   - Write curated synthesis notes that link to the archived complete sources
5. **Update** navigation and ops trail only as needed:
   - Add moved durable files to `index.md` when they belong in active navigation
   - Rewrite links for merged files when a canonical destination replaces them
   - Append concise operation entry to `log.md`
6. **Audit** processed archives:
   - Scan `raw/processed/YYYY-MM-DD/` for empty date folders
   - Flag non-date folder anomalies
   - Report duplicate filenames across dates
   - Remove empty folders (with confirmation in apply mode)
7. **Execute** by mode:
   - `report`: preview plan only (no changes)
   - `apply`: run full pipeline with confirmation

## Safety

- Never discard files from `raw/sources/` — only move them after successful
  classification
- Treat `raw/processed/` as immutable evidence — never delete processed source
  files
- Do not create summaries, synthesized notes, or rewritten interpretations of
  owned source files during ingest
- Synthesize tagged external sources by default in apply mode, preserving the
  complete source under `raw/processed/YYYY-MM-DD/` first
- Do not synthesize untagged sources unless the user explicitly asks for it
- Do not remove the `external` tag from archived source records
- Non-destructive edits by default — source files are moved, not rewritten
- Merges are additive by default and must preserve provenance
- Confirm before execution unless `--yes`
- Do not mutate file contents under `raw/sources/`, `raw/processed/`, or
  `raw/assets/`
- Do not assume or create an inbox staging layer

## Output

Return:

- discovered captures and classification plan
- Portent type, status, belongs_to, and related_to recommendations for each
  capture
- category, confidence, and destination path for each source
- source files moved and final destination paths
- files merged, merge target, and provenance retained
- synthesized items, archived complete source paths, and links inserted
- source files left in place with ambiguity reason
- captures left unorganized because they lack a useful relationship target
- `index.md` additions
- `log.md` entry appended
- audit findings (empty folders, anomalies)
- fixes applied (if any)
- manual follow-up items