Add Obsidian integration guidance

SKILL.md

@@ -7,6 +7,8 @@ description: Generate, resume, audit, and maintain AI-generated Zotero child-not
 
 Use this skill to create Zotero child notes from local Zotero items with the user's literature-note templates.
 
+This skill is also Obsidian-aware: templates, prompts, and the local audit cache live in the user's Obsidian vault, so preserve Obsidian Flavored Markdown conventions when reading or adapting those materials. Read [references/obsidian-integration.md](references/obsidian-integration.md) before changing template handling, adding vault-facing files, or generating Markdown meant to round-trip through Obsidian. Read [references/upstream-obsidian-skills.md](references/upstream-obsidian-skills.md) before pulling in more ideas from `kepano/obsidian-skills`.
+
 Core script:
 
 ```powershell
@@ -33,6 +35,14 @@ py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\audit_zotero_ai_notes
 
 Never store API keys in the skill. If keys appear in chat or logs, tell the user to rotate them.
 
+## Obsidian-Aware Template Rules
+
+- Treat `00 Templater` as the source of truth for note structure. Do not rewrite the user's templates unless asked.
+- Preserve Obsidian syntax from templates, including wikilinks, callouts, tags, math, highlights, comments, and YAML frontmatter.
+- Zotero child notes should remain clean Markdown/HTML note content; do not insert visible AI banners such as `AI Literature Note` or `AI文献笔记`.
+- If generating any auxiliary `.md` file in the vault, use valid Obsidian properties and internal links as described in [references/obsidian-integration.md](references/obsidian-integration.md).
+- Keep operational artifacts hidden or clearly tool-scoped: cache/index files should stay under `00 Templater` and begin with a dot when practical.
+
 ## Common Workflows
 
 ### Single item
@@ -91,3 +101,7 @@ The cache lives at `<vault>\00 Templater\.zotero-ai-notes-index.json`. Use `--re
 ## Upgrade Points
 
 Read [references/upgrade-plan.md](references/upgrade-plan.md) before changing behavior, adding cleanup, adding collection targeting, or improving note quality.
+
+Read [references/obsidian-integration.md](references/obsidian-integration.md) before adding Obsidian vault exports, Bases views, markdown normalization, or Obsidian CLI integration.
+
+Read [references/upstream-obsidian-skills.md](references/upstream-obsidian-skills.md) before doing another merge from `kepano/obsidian-skills`.

references/obsidian-integration.md

@@ -0,0 +1,84 @@
+# 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.

references/upstream-obsidian-skills.md

@@ -0,0 +1,33 @@
+# Upstream Obsidian Skills Notes
+
+Source reviewed:
+
+```text
+https://github.com/kepano/obsidian-skills.git
+```
+
+Reviewed modules:
+
+- `skills/obsidian-markdown`: Obsidian Flavored Markdown, wikilinks, embeds, callouts, properties, tags, comments, math, Mermaid.
+- `skills/obsidian-cli`: vault targeting, file targeting, note read/create/search patterns, plugin-development commands.
+- `skills/obsidian-bases`: Bases schema and view/filter concepts that could later support literature-note dashboards.
+
+What was merged into this skill:
+
+- Obsidian-aware template rules in `SKILL.md`.
+- `references/obsidian-integration.md` with Markdown compatibility, properties, template round-trip rules, audit cache rules, and upgrade hooks.
+- A future path for optional vault exports, Obsidian Bases views, and Obsidian CLI integration.
+
+What was intentionally not merged:
+
+- Full Obsidian CLI command catalog. This Zotero workflow should not require Obsidian to be open.
+- JSON Canvas support. It is unrelated to Zotero literature-note generation.
+- Defuddle/web extraction behavior. Zotero metadata, attachments, and templates are the source path for this skill.
+- Full Obsidian Bases schema. Keep it deferred until the user asks for a dashboard or literature database view.
+
+Maintenance guidance:
+
+- Keep the default workflow Zotero-first and deterministic.
+- Add Obsidian features as optional exports or helpers, not as prerequisites for generating Zotero child notes.
+- Preserve the user's `00 Templater` files as the source of truth.
+- If copying substantial upstream text or code in the future, preserve the upstream license and attribution in the repository.