/ingest

name: ingest
description: "Turn whatever the human has — a PDF, a link, a DOI, a screenshot of a citation — into raw/ sources this project can compile."
commands:
  ingest: "Ingest papers, articles and notes into raw/."
origin: magi

ingest

When to use

Anything new is arriving: files in `inbox/`, a link or DOI in the chat, a citation the human read out.

Method

1. Files already in `inbox/`, or a path you were given: `magi ingest auto` — it routes by type and finalizes. Stop here unless it refuses. (A run that skipped cleanup: `magi ingest finalize <the file> --project-dir .`.) 2. A link, DOI, arXiv id or citation: identify it first — that is the step that needs you, not the pipeline. An id you typed from memory goes in as `magi ingest url "<id>" --expect "<title fragment>"`; then `magi ingest batch-run`. 3. `magi ingest review` lists what is waiting. Show its findings to the human before committing — surface `identity-mismatch`, `figure-count-mismatch` and `image-path-not-portable` every time: the file is not what its name says. `math-damage` counts formulas that will fail `magi math check`: say the number. 4. Once the human has seen the list: `magi ingest review --approve-all` (or `--item <id> --decision approve` per row), then `magi ingest review --commit`. 5. After a batch: `magi math check --json` — a `$$` that lost its pair swallows the paragraph after it and is still valid LaTeX. Work the list with `tidy`; papers from an older arXiv-HTML ingest first get `magi math repair --dry-run`.

Rules

• **Never** transcribe pages through vision because a converter failed: it costs

one sub-agent call per page. Not until a person has said yes; 10 at once.

• **Never** commit a batch the human has not seen the findings for.
• A converter that exits non-zero: report its stderr and stop. An unreadable

file: name it and carry on. Report **partial** work as partial — "9 of 12".

• Which project a source belongs to is never your guess: when it is

ambiguous, stop and ask. Collect the questions the work you delegated could not ask (Invariant 4) and put them all at once.