# Zotero Obsidian Literature Skill

Codex skill for managing a Zotero-to-Obsidian literature workflow.

It helps generate Zotero child-note AI reading notes, audit missing generated notes, maintain Obsidian literature notes, and build Dataview dashboards without committing private API keys.

## What It Does

- Generates AI literature notes as Zotero child notes.
- Uses Obsidian templates and prompt files from the target vault.
- Supports one item, selected item keys, or approved whole-library batches.
- Audits Zotero items that are missing generated AI notes.
- Keeps real Zotero and DeepSeek/AwesomeGPT credentials in a local ignored config file.
- Provides Obsidian integration guidance for Dataview and Markdown maintenance.

## Repository Layout

```text
.
|-- SKILL.md
|-- agents/
|   `-- openai.yaml
|-- config/
|   `-- config.template.json
|-- references/
|   |-- obsidian-integration.md
|   |-- obsidian-literature-maintenance.md
|   |-- upgrade-plan.md
|   `-- upstream-obsidian-skills.md
`-- scripts/
    |-- audit_zotero_ai_notes.py
    |-- generate_zotero_ai_note.py
    `-- init_private_config.py
```

## Requirements

- Zotero Desktop is open.
- Zotero Local API is enabled at `http://127.0.0.1:23119`.
- Python launcher `py` is available on Windows.
- The default Obsidian vault is `C:\Users\qyh15\Documents\Obsidian Vault`.
- The vault contains the expected templates under `00 Templater`.
- A Zotero Web API key is available for note writes.
- DeepSeek or another OpenAI-compatible endpoint is configured through AwesomeGPT settings, environment variables, or the local private config.

## Private Config

Do not commit real API keys.

The committed file is only a template:

```text
config/config.template.json
```

Create the local ignored config with:

```powershell
py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\init_private_config.py"
```

This writes:

```text
config/config.local.json
```

`config/config.local.json` is ignored by Git. Do not paste its contents into chat, logs, README files, or committed examples.

## Common Commands

Generate a note for one Zotero item:

```powershell
py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing
```

Generate notes for selected items:

```powershell
py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627 ZCZXGRAM" --limit 0 --skip-existing --fulltext-chars 4000
```

Audit missing generated notes:

```powershell
py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
```

Rebuild the audit cache:

```powershell
py "$env:USERPROFILE\.codex\skills\zotero-obsidian-literature\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --rebuild
```

## Batch Safety

Whole-library generation writes many Zotero child notes. Use it only after explicitly confirming the target library and write scope.

For long runs, prefer batches of 20-30 items and keep `--skip-existing` enabled so interrupted runs can resume without duplicating notes.

## Git

Current remote:

```text
git@git.qyhhh.top:Skills/MYwirte-skill.git
```

Recommended push command in this environment:

```powershell
& "$env:USERPROFILE\.codex\tools\mingit\cmd\git.exe" push
```