Skip to content

Add and validate a paper

Use the paper command to register a DOI, create a summary stub, and optionally upload a local PDF to the configured Drive folder.

Execution status

Documentation CI strictly builds this page, but it does not execute the Crossref request, repository-writing command, or optional Drive upload. Run the procedure manually, verify the returned metadata, and inspect all local and external changes before committing.

Preview the record

Choose one of the repository's supported categories and run a dry run:

uv run cortex-add \
  --doi 10.1037/rev0000349 \
  --category lan-methodology \
  --dry-run

The command requests DOI metadata from Crossref and shows the proposed title, authors, year, slug, and category. A dry run writes neither the summary nor the paper index.

Create the stub

Run the command again without --dry-run:

uv run cortex-add \
  --doi 10.1037/rev0000349 \
  --category lan-methodology

This creates a Markdown template under papers/<category>/ and appends a stub entry to papers/index.yaml. If the DOI is already registered, the command exits without creating a second record.

To upload a PDF at the same time, configure CORTEX_DRIVE_ACCOUNT and CORTEX_DRIVE_FOLDER_ID, authenticate the gog Drive CLI, and pass an existing file:

uv run cortex-add \
  --doi 10.1037/rev0000349 \
  --category lan-methodology \
  --pdf /absolute/path/to/paper.pdf

Review the content

Fill the generated summary using schema/paper-template.md as the contract. In particular:

  1. verify bibliographic fields against the source;
  2. write the summary, contributions, relevance, limitations, and relationships;
  3. keep uncertain graph fields empty instead of guessing; and
  4. change status in both the summary and index only when the repository's review state changes.

stub and draft content is tracked for collaboration but is not presented as reviewed guidance on the public documentation site.

Validate before review

uv run cortex-validate

The validator checks index fields, DOI shape, status values, summary paths, frontmatter, categories, and orphaned summaries. For a publication-quality gate in which warnings also fail, run:

uv run cortex-validate --strict

Inspect the diff before committing. Adding a paper may change the index, a summary, and—when a PDF is supplied—external Drive state.