Vault and annotations

BiblioFetch has two layers of paper management:

1. Project jobs (job.toml) — per-project reference lists that fetch into a local directory. Covered in earlier examples.
2. Vault — a directory of topic TOML files that acts as a canonical, cross-project reference collection. This example covers the vault.

Vault layout

By default the vault lives at ~/.config/bibliofetch/vault/. Each .toml file defines one topic:

# ~/.config/bibliofetch/vault/mps-algorithms.toml
[topic]
name  = "MPS Algorithms"
tags  = ["tensor-network", "dmrg"]
notes = "Core MPS/DMRG references"

[doi]
list = [
  "arxiv:cond-mat/0407066",
  "10.1103/RevModPhys.93.045003",
]

An optional vault.toml in the same directory pins the shared store path and topic order:

# ~/.config/bibliofetch/vault/vault.toml
topics = ["mps-algorithms.toml", "dmrg-foundations.toml"]
store  = "~/papers/vault"

Creating a vault in a tempdir (demo)

The rest of this example creates a self-contained vault under a tempdir so it runs without touching your home directory.

using BiblioFetch

Create a temporary vault directory so this example runs without touching your home directory. Each topic gets its own TOML file.

_vault_demo_dir = mktempdir()

open(joinpath(_vault_demo_dir, "tensor-networks.toml"), "w") do io
    BiblioFetch.TOML.print(
        io,
        Dict(
            "topic" => Dict("name" => "Tensor Networks", "tags" => ["mps", "dmrg"]),
            "doi" => Dict("list" => ["arxiv:cond-mat/0407066"]),
        ),
    )
end

open(joinpath(_vault_demo_dir, "quantum-info.toml"), "w") do io
    BiblioFetch.TOML.print(
        io,
        Dict(
            "topic" => Dict("name" => "Quantum Information"),
            "doi" => Dict("list" => ["arxiv:quant-ph/0301023"]),
        ),
    )
end

Load the index and inspect available topics.

index = load_vault_index(_vault_demo_dir)
topics = list_topics(index)
(length(topics), sort([t.name for t in topics]))

(2, ["Quantum Information", "Tensor Networks"])

list_topics returns one VaultTopic per file found in the directory.

Adding a ref from the shell

bibliofetch vault add arxiv:1706.03762 --topic tensor-networks

Appends the ref to the topic TOML in place without touching other entries.

Fetching

The vault_fetch! function builds a synthetic FetchJob per topic and dispatches to the same fetch pipeline used by BiblioFetch.run:

bibliofetch vault fetch                  # all topics
bibliofetch vault fetch tensor-networks  # one topic

From Julia:

index = load_vault_index()
vault_fetch!(index; verbose=true)

Inheriting vault refs in a project job

A project job.toml can import vault topics without duplicating PDFs:

[vault]
inherit = ["tensor-networks", "quantum-info"]

[doi]
list = ["10.1103/PhysRevB.99.214433"]   # project-specific only

bibliofetch bib then outputs a single .bib covering both vault and project references. The vault PDFs stay in the vault store; only the metadata is merged for BibTeX generation.

BibTeX export

bibliofetch vault bib                    # all topics → vault.bib
bibliofetch vault bib tensor-networks    # one topic
bibliofetch vault bib --out ~/papers/combined.bib

Annotations

Every paper in the store — vault or project — carries editable annotation fields in its .metadata/<safekey>.toml:

tags        = ["mps", "finite-temperature"]
notes       = "Definition 2.3 is the key result."
read_status = "read"    # unread | reading | read | skimmed
starred     = true

The annotate command opens $EDITOR on the metadata file directly:

bibliofetch annotate 10.1103/PhysRevB.99.214433

Filter the listing by annotation field:

bibliofetch ls --tag mps
bibliofetch ls --unread
bibliofetch ls --starred

Searching the vault

Full-text search across all vault topics (delegates to search_entries on the vault store):

bibliofetch vault search "DMRG finite temperature"

From Julia:

index = load_vault_index()
matches = vault_search(index, "DMRG")
for m in matches
    println(m.key, "\t", m.title)
end