# QQnote-skill

QQnote-skill is a Zotero + Obsidian literature-note tool for Codex. It generates
AI literature notes from Zotero items, writes them as Zotero child notes, audits
missing generated notes, and maintains Obsidian literature-note views.

QQnote is intentionally narrow: it prepares literature-note inputs. It does not
decide manuscript novelty, target-journal positioning, strong/weak related-paper
status, reviewer risk, or citation necessity. Those decisions belong to QQsci
when QQnote is used inside the QQsci workflow.

## Core Workflows

### Initialize Private Config

Use local-only config for Zotero and DeepSeek/AwesomeGPT keys:

```powershell
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\init_private_config.py"
```

The committed template is:

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

The real local file is:

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

Do not commit `config/config.local.json`, print secrets, or paste API keys into
chat.

### Generate Zotero Child Notes

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

Use this when a Zotero item needs an AI-generated child note. For long runs,
prefer small batches and rerun with `--skip-existing` after interruptions.

For deeper notes, use the full-detail mode supported by the installed script,
for example:

```powershell
py "$env:USERPROFILE\.codex\skills\QQnote-skill\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --mode deep --fulltext-chars 80000 --max-tokens 12000 --replace-existing
```

### Audit Missing Generated Notes

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

Use deterministic audit scripts for library state. Do not ask DeepSeek to decide
which Zotero items are missing notes.

## Relationship With QQsci

When used by QQsci:

1. QQsci identifies which literature inputs are needed.
2. QQnote generates or refreshes Zotero child notes.
3. QQsci performs keyword extraction, strong/weak related-paper screening,
   target-journal positioning, comparative audit, manuscript revision, and Word
   DOI-only citation comments.

QQnote should not decide whether a paper is strongly related, weakly related,
required for citation, or sufficient as reviewer evidence.

QQsci may call QQnote through a wrapper that injects QQsci-level DeepSeek and
Zotero configuration into QQnote's expected environment variables.

## Standalone Configuration

QQnote must also remain usable independently. In standalone mode it reads:

- process environment variables
- local private config
- vault `.env`, if supported by the installed script
- AwesomeGPT/Zotero profile preferences

Expected environment variables include:

- `AWESOMEGPT_API_KEY`
- `AWESOMEGPT_BASE_URL`
- `AWESOMEGPT_MODEL`
- `ZOTERO_API_KEY` for Zotero Web API writes
- `ZOTERO_USER_ID` when needed

Never store API keys in `SKILL.md`, references, committed files, zip files,
terminal output, or chat. If keys appear in chat or logs, rotate them.

## Obsidian Notes

Read these references before modifying Obsidian behavior:

- `references/obsidian-integration.md`
- `references/obsidian-literature-maintenance.md`

Default vault:

```text
C:\Users\qyh15\Documents\Obsidian Vault
```

Default organization includes:

- `00 Templater`: source templates, prompts, and audit cache
- literature-note folders exported or linked from Zotero
- Dataview dashboards for browsing literature

## Repository Contents

```text
.
|-- SKILL.md
|-- README.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
```

## Installed Location

For Codex discovery, install under:

```text
C:\Users\qyh15\.codex\skills\QQnote-skill
```

Keep source and installed copies synchronized when updating scripts or
documentation.