From d4c64e02e5d2b0c40d718e67f76a7e1c25967f75 Mon Sep 17 00:00:00 2001
From: qyh15 <qyh15@local>
Date: Wed, 20 May 2026 15:47:10 +0800
Subject: [PATCH] Add README for Zotero Obsidian skill

---
 README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c741475
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+# 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
+```