vault-normalizer

Vault Normalizer

Goal

Convert an existing research directory into an Agentero-compatible Vault without losing user-written notes or original files.

Safety rules

• Inspect first; do not move, rename, delete, or overwrite files until the user approves a concrete migration plan.
• Preserve user-written Markdown, PDFs, TeX/source archives, annotations, Obsidian [[wikilinks]], and any existing AGENTS.md content.
• If a directory already has AGENTS.md, read it as local instructions and do not replace it; only propose an append/merge draft when the user asks.
• Prefer copying or staged moves when the source directory is not already a Vault.
• Never treat .agentero/catalog.sqlite as disposable cache; it is the authoritative paper collection and metadata store.
• Do not make root PAPERS.md, library.bib, or per-paper metadata.json the source of truth. They are optional exports or projections.
• Treat link repair as a separate, reviewable change. Do not invent missing notes, select an ambiguous candidate, or rewrite a user-authored link without approval.

Target layout

agentero-vault/
├── AGENTS.md
├── papers/
│   ├── <paper-id-or-citekey>/
│   │   ├── NOTES.md
│   │   ├── <id>.pdf
│   │   ├── PAPER.md        # optional derived readable body
│   │   ├── marks/          # optional JSON highlights / asks / translations
│   │   ├── source/         # optional original TeX / e-print
│   │   ├── assets/         # optional note images or derived figures
│   │   └── attachments/    # optional extras: supplement PDFs, slides, code repos
│   └── <topic>/.../<paper-id-or-citekey>/
├── notes/
├── plans/
├── assets/                 # optional non-paper media
├── .agents/
│   └── skills/
└── .agentero/
    ├── catalog.sqlite
    ├── config.json
    └── .trash/

Directory rules

• papers/ contains all cataloged papers. Topic folders are allowed at any depth.
• A paper folder is the smallest paper unit and is recognized by direct children such as NOTES.md, PAPER.md, marks/, source/, assets/, or transitional metadata.json.
• A topic folder under papers/ is not a paper unless it directly contains a paper marker.
• Catalog identity is the Vault-relative paper folder path, e.g. papers/nlp/transformers/1706.03762, not just the leaf directory name.
• Local PDFs for a paper should live at the paper folder root, not inside source/. Extra PDFs (supplement, slides, reviews) belong in {paper}/attachments/, not the paper root.
• TeX, arXiv e-print contents, and original source archives belong in {paper}/source/. Do not put user extras there.
• Supporting materials (code repos, datasets, extra PDFs) belong in {paper}/attachments/. Create that directory only when adding files; do not create empty attachments/ folders. attachments/ is not a paper-identity marker.
• User notes about one paper belong in {paper}/NOTES.md.
• For new organization, prefer notes/ for concept notes and cross-paper notes, and plans/ for research plans, TODOs, and drafts; do not force-move existing folders that already work for the user.
• Markdown-embedded images belong beside the Markdown file in ./assets/ and should use relative links like ![alt](./assets/file.png).
• PDF selection artifacts belong in {paper}/marks/*.json; do not write them into the PDF binary or catalog body.
• .agentero/ is application state and should not be shown or edited as ordinary notes.