obsidian-gemini: Instructions file for Codex

Repository Guidelines

Project Overview

Obsidian Gemini Scribe is an Obsidian plugin that integrates Google's Gemini AI models for AI-driven assistance within Obsidian. It provides context-aware chat, document summarization, text rewriting, and IDE-style completions.

Project Structure & Module Organization

• src/ contains TypeScript plugin code; src/main.ts is the entry point with domain folders such as agent/, api/, tools/, ui/, and services/, plus shared utilities in utils/.
• docs/ hosts user and operator guides; prompts/ ships default agent prompts; evals/ holds the agent eval harness (task fixtures, runner, baselines).
• Unit tests live in the test/ directory mirroring src/ structure as *.test.ts; generated artifacts (main.js, manifest.json, styles.css) stay in the repo root for Obsidian.

Commands

Development

npm install          # Install dependencies
npm run dev          # Development build with watch mode
npm run build        # Production build (generates refs, runs TypeScript check, then bundles)
npm run generate-refs # Regenerate help references from docs/ (runs automatically in build/dev)
npm test             # Run Vitest tests
npm run format       # Format code with Prettier
npm run format-check # Check formatting without changes
npm run lint         # Lint with ESLint (eslint-plugin-obsidianmd recommended preset)
npm run lint:fix     # Auto-fix ESLint violations where possible
npm run lint:cycles  # Fail on circular imports (madge --circular over src/; baseline is 0 and CI's lint workflow enforces it)
npm run check:fields   # Advisory unread-field scan (per-field reachability over src/ interface and type-alias fields; #1469). Always exits 0 — the report lands in the Unread-field workflow artifact. Suppress a genuinely write-only field with 'wiring:keep' on its declaration line. Flip to blocking after the noise rate has been measured for a release.
npm run knip         # Detect unused files, exports, types, and dependencies (configured in knip.json; CI's knip workflow enforces it, so a newly-dead export fails the PR — put intentional public surface in knip.json rather than re-arguing it per PR; every knip.json ignore carries its justification written next to it; nothing may mark an export reachable except a real caller — not an entry-point declaration, not a test-only import, not a JSDoc @public/@beta/@alias tag, which the no-tags-as-reachability ESLint rule fails (#1525))
npm test             # Vitest suite — includes the provider-docs-sync guard (test/api/provider-docs-sync.test.ts): the provider pipeline diagram in AGENTS.md and .claude/guidelines/invariants.md must name exactly the ModelProvider union from src/api/providers/registry.ts, so adding a provider fails the PR until the diagrams are updated (#1567)
npm run install:test-vault # Copy built artifacts into test vault. Target precedence: TEST_VAULT_PLUGIN_DIR (exact plugin folder, validated by id) > TEST_VAULT_DIR (vault root, scanned by id) > default ~/Obsidian/Test Vault
npm run translate    # Regenerate AI translations in src/i18n/ (needs GOOGLE_API_KEY; not part of build/test — runs in its own `Update UI translations` workflow on en.ts changes, or manually)