QQnote-skill/references/obsidian-integration.md

Obsidian Integration Notes

Use these rules when the Zotero AI notes workflow touches the user's Obsidian vault. They are adapted from the Obsidian skill patterns in kepano/obsidian-skills, but scoped to this Zotero note workflow.

Scope

• The Zotero child note is the primary output.
• The Obsidian vault provides templates, prompts, and local workflow state.
• Vault-facing files should be lightweight. Do not copy PDFs, Zotero attachments, large corpora, or API keys into the skill or vault helper files.

Markdown Compatibility

Preserve Obsidian Flavored Markdown when reading templates or generating vault-facing Markdown:

• Wikilinks: [[Note]], [[Note#Heading]], [[Note|Display Text]]
• Embeds: ![[file.pdf#page=3]], ![[image.png|300]]
• Callouts: > [!note], > [!warning] Custom Title, foldable > [!faq]-
• Tags: #tag, #nested/tag, or YAML tags
• Highlights: ==important text==
• Comments: %%hidden text%%
• Math: $inline$ and $$block$$
• Mermaid code blocks when the template already asks for diagrams

Do not normalize these into plain Markdown if the content is meant to return to Obsidian.

Properties / Frontmatter

If this skill creates auxiliary .md files in the vault, add YAML frontmatter only when it adds real value. Keep it simple and valid:

---
title: Zotero AI Notes Audit
tags:
  - zotero
  - ai-notes
status: generated
---

Use these property conventions when needed:

• title: human-readable note title
• tags: searchable labels such as zotero, ai-notes, literature
• aliases: only for names the user would naturally search
• zotero_key: item key or parent item key when a file represents one Zotero item
• doi: DOI when known
• status: small workflow state such as missing-note, generated, needs-review

Avoid storing secrets, raw API responses, or full prompts in frontmatter.

Template Round-Trip Rules

• 01 ...md is the research-article template.
• 02 ...md is the review-article template.
• 03 ...md is the LLM prompt used to fill literature notes.
• Keep the user's headings and placeholders intact unless the requested task is template redesign.
• If a generated Zotero note looks wrong, inspect the corresponding template before changing Python logic.
• If the template includes Obsidian-only syntax, let it pass through unless Zotero rendering breaks in practice.

Audit And Index Files

The fast audit cache currently lives at:

<vault>\00 Templater\.zotero-ai-notes-index.json

Rules:

• Use the JSON cache for deterministic missing-note checks.
• Do not ask an LLM to compare Zotero library state.
• Rebuild the cache after external note edits or major Zotero changes.
• If a user wants a human-readable vault dashboard later, create a separate Markdown or .base export from the cache instead of replacing the JSON cache.

Future Upgrade Hooks

Good follow-up extensions:

• --export-missing-md: write an Obsidian note listing Zotero items still missing generated notes.
• --export-base: create an Obsidian Bases .base view over generated audit Markdown files.
• --open-vault-note: optionally call Obsidian CLI when installed and Obsidian is already open.
• --template-version: record which template version generated a note, without adding visible banners to Zotero notes.

Keep these as optional features. The default workflow should remain Zotero-first and script-driven.