# 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:

```yaml
---
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:

```text
<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.