# Paper Vault

> Create, update, or troubleshoot a local visual Paper Vault for saved research papers. Use when the user wants to import High or Medium papers from a daily literature digest, connect the vault with the daily-literature-digest skill, classify papers into no more than five broad research categories with drill-down subtopics, build a searchable card-style paper dashboard, add bilingual notes, attach local PDF paths, or share a reusable Paper Vault workflow across different research fields.

- Skill: `xuezheng627/paper-vault` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add xuezheng627/paper-vault`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xuezheng627/paper-vault/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: xuezheng627 (https://skillmd.com/u/xuezheng627)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xuezheng627/paper-vault

---


# Paper Vault

## Purpose

Use this skill to turn selected papers from `$daily-literature-digest` into a local static web vault. The daily digest finds and prioritizes papers; Paper Vault keeps the important ones visible, categorized, searchable, and revisitable.

The skill must generalize to any field. Never reuse the creator's example categories unless the user's keywords actually match them.

## Core Workflow

1. Locate the user's digest workspace:
   - Prefer `daily-literature-digest.config.json` in the current workspace.
   - Prefer digest JSON under `daily-literature-digests/data`.
   - Use a user-provided path if they name one.
2. Decide what to import:
   - "High papers" means `priority: High`.
   - "Medium and above" means `priority: High` and `priority: Medium`.
   - Do not import Low unless explicitly requested.
   - Default rule: only import papers after Codex has read an accessible full text, local PDF, or user-provided article text. Papers without accessible full text go to `sources/fulltext-inbox` first.
3. Initialize the vault if needed:
   ```powershell
   python paper-vault\scripts\paper_vault.py init --vault-dir paper-vault-site
   ```
4. Import selected papers:
   ```powershell
   python paper-vault\scripts\paper_vault.py import-high `
     --vault-dir paper-vault-site `
     --digest-data-dir daily-literature-digests\data `
     --config daily-literature-digest.config.json `
     --priority Medium `
     --max-areas 5 `
     --download-arxiv-pdfs
   ```
   This command defaults to `--require-fulltext`. It imports only papers with a local PDF or extracted full-text source file. Use `--no-require-fulltext` only when the user explicitly asks for temporary abstract/title cards.
5. Review the generated site:
   - Broad categories must be no more than 5.
   - Subtopics can be more specific and should sit under a broad category.
   - Paper cards should show title, tags, short summary first; objective, method, result, usefulness, and next step only after expanding details.
   - DOI/arXiv and journal links should be clickable.
   - Local PDFs should display as copyable local paths, not hidden browser downloads.
6. Run locally:
   ```powershell
   cd paper-vault-site
   python -m http.server 8766 --bind 127.0.0.1
   ```
   Open `http://127.0.0.1:8766/index.html`.

## Classification Rules

- Use the user's own keyword groups as the first signal.
- If keyword groups are too granular, merge them into broader research areas.
- Keep at most 5 broad `area` values. If more exist, merge smaller/rare areas into `Other Research`.
- Keep one `primarySubtopic` per paper for counted drill-down filters.
- Keep `subtopics` and `tags` as descriptive secondary labels; they may overlap.
- Primary subtopic counts should add up cleanly within the selected broad category.
- Deduplicate by DOI, arXiv id, source key, URL, then normalized title.

Examples of acceptable broad categories:

- For building research: `Building Energy`, `HVAC Control`, `Low-Carbon Construction`, `Optimization Methods`, `Occupant Comfort`.
- For biomedical research: `Clinical Evidence`, `Molecular Mechanisms`, `Imaging and Diagnostics`, `Therapeutics`, `Data Methods`.
- For social science: `Policy`, `Behavior`, `Institutions`, `Methods`, `Equity`.

These are examples only. Infer categories from the user's papers.

## AI Fields

For each card, maintain:

- `summary`: one skimmable paragraph.
- `objective`: the research problem or question.
- `method`: algorithms, models, data, experiments, or framework.
- `result`: findings explicitly supported by abstract/full text.
- `usefulness`: why this matters for the user's stated research interests.
- `nextAction`: what to read, extract, compare, or reproduce next.

## Full-Text Requirement

Before adding a paper as a normal Paper Vault card:

- Read the full PDF, article HTML, or user-provided full-text file.
- Base `objective`, `method`, `result`, `usefulness`, and `nextAction` on that full text.
- Set `readingStatus` honestly, e.g. `fulltext-read`, `article-page-read`, or `preview-read`.
- Attach `pdfPath` when a local PDF exists, or `fullTextPath`/`sourcePath` when article text was extracted.

If only title, metadata, or abstract is available:

- Do not import it as a normal card by default.
- Write it to `sources/fulltext-inbox/to-download-YYYY-MM-DD.md` with DOI/URL and why it is worth following up.
- Actively tell the user how many High/Medium papers need full text and ask whether they want to log in through the active browser now.
- If the user logs in, use only that explicit current browser session to open the paper pages, download/read the PDF or full article text, then summarize from the full text before importing.
- If the user does not want to log in now, keep the papers in `sources/fulltext-inbox` and do not show them as normal cards.
- Only create a temporary card if the user explicitly says to save it before full-text reading; set `readingStatus: needs-fulltext`, keep limitations visible, and do not infer method or results.

Paywalled access rules:

- Use an active user-logged-in browser session or PDFs the user manually downloads.
- Do not store passwords, cookies, HTML login pages, or institutional session traces.
- Do not create unattended publisher-login download automation.

## Bilingual Notes

The frontend supports bilingual display through `data/paper-bilingual.js`.

- If the user wants bilingual notes, add translations under `window.PAPER_VAULT_BILINGUAL`.
- Preserve UTF-8 encoding.
- Prefer `apply_patch` for manual edits containing Chinese. Do not pipe Chinese source text through PowerShell into Python/Node; Windows console encoding can turn Chinese into `????`.
- If using scripts to write Chinese, keep Chinese in UTF-8 files or JSON inputs, not inline PowerShell heredocs.
- After editing, validate generated HTML/JS/JSON for mojibake and replacement text. Search for `????`, `锟`, `鐮`, `浼`, `寤`, `璁`, `鎽`, `涓`, `娑`, `閻`, `閸`, and `瀵`.
- If mojibake already exists in a user's data file, repair it by mapping known labels/text back to valid UTF-8 or by adding a UTF-8 override file loaded after the damaged data.
## Vault Structure

Generated runtime files belong in the user's workspace, not inside the skill folder:

```text
paper-vault-site/
  index.html
  styles.css
  app.js
  data/
    papers.js
    vault-settings.js
    paper-bilingual.js
  notes/
  pdfs/
  sources/
```

Do not commit generated papers, PDFs, notes, source pages, cookies, or login traces unless the user explicitly wants to publish that vault.

## Script Reference

Use `scripts/paper_vault.py` for deterministic setup and import. Read or patch it only for custom behavior.

Common commands:

```powershell
python paper-vault\scripts\paper_vault.py init --vault-dir paper-vault-site
python paper-vault\scripts\paper_vault.py import-high --vault-dir paper-vault-site --digest-data-dir daily-literature-digests\data --priority High --max-areas 5
python paper-vault\scripts\paper_vault.py import-high --vault-dir paper-vault-site --digest-data-dir daily-literature-digests\data --priority Medium --max-areas 5
python paper-vault\scripts\paper_vault.py import-high --vault-dir paper-vault-site --digest-data-dir daily-literature-digests\data --priority Medium --min-impact-factor 5 --download-arxiv-pdfs
python paper-vault\scripts\paper_vault.py import-high --vault-dir paper-vault-site --digest-data-dir daily-literature-digests\data --priority Medium --no-require-fulltext
```

`--priority Medium` imports Medium and High. `--priority Low` imports all priority levels.

`--min-impact-factor 5` skips numeric peer-reviewed journal IF values below 5 while keeping arXiv/preprints by default. Add `--no-keep-preprints` only if the user wants to exclude preprints too.

`--require-fulltext` is the default. It skips papers that do not already have a local PDF or extracted full-text source and writes them to `sources/fulltext-inbox`. `--no-require-fulltext` is only for explicit temporary abstract/title cards.

## Safety

- Do not store passwords, cookies, or login state in the vault.
- Do not run unattended publisher login/download workflows.
- For paywalled papers, use explicit user-provided PDFs or an active user-logged-in browser session for that batch only.
- Keep institutional-access artifacts out of the shareable skill repository.