vault-ingest

What this skill does

# 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 collisio