Initial commit

CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Type
+
+This is an Obsidian community plugin written in TypeScript and bundled to JavaScript using esbuild.
+
+## Build Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Development mode (watch mode, auto-recompiles on changes)
+npm run dev
+
+# Production build (type checks, then bundles with minification)
+npm run build
+
+# Lint code
+npm run lint
+```
+
+## Architecture
+
+### Entry Points & Build Process
+- Source code lives in `src/`
+- Main entry point: `src/main.ts` (plugin lifecycle management)
+- Build target: `main.js` (bundled output at root)
+- Bundler: **esbuild** (configured in `esbuild.config.mjs`)
+- Required release artifacts: `main.js`, `manifest.json`, `styles.css` (if present)
+
+### Code Organization Pattern
+- **Keep `main.ts` minimal**: Only plugin lifecycle (onload, onunload, command registration)
+- Delegate feature logic to separate modules
+- Settings are defined in `src/settings.ts`
+- Organize larger features into subdirectories:
+  - `commands/` for command implementations
+  - `ui/` for modals, views, and UI components
+  - `utils/` for helper functions
+
+### Plugin Architecture
+- Extends `Plugin` class from `obsidian` package
+- Settings are loaded/saved using `this.loadData()` / `this.saveData()`
+- All event listeners, intervals, and DOM events must use `this.register*()` helpers for proper cleanup
+- Commands are registered via `this.addCommand()` with stable IDs
+
+## Key Constraints
+
+### Obsidian-Specific
+- **Bundle everything**: No external runtime dependencies (except `obsidian`, `electron`, CodeMirror packages)
+- **External packages**: Listed in `esbuild.config.mjs` external array; never bundle these
+- **Mobile compatibility**: Avoid Node/Electron APIs unless `isDesktopOnly: true` in manifest
+- **Network requests**: Default to offline; require explicit user consent for any external calls
+- **No remote code execution**: Never fetch/eval scripts or auto-update outside normal releases
+
+### Manifest (`manifest.json`)
+- Never change `id` after initial release
+- Use semantic versioning for `version`
+- Keep `minAppVersion` accurate when using newer Obsidian APIs
+- Update both `manifest.json` and `versions.json` when bumping versions
+
+## Development Workflow
+
+### Testing Locally
+1. Build the plugin: `npm run dev` or `npm run build`
+2. Copy `main.js`, `manifest.json`, `styles.css` to:
+   ```
+   <Vault>/.obsidian/plugins/<plugin-id>/
+   ```
+3. Reload Obsidian and enable plugin in Settings → Community plugins
+
+### Type Checking
+- TypeScript strict mode enabled in `tsconfig.json`
+- Build command runs `tsc -noEmit -skipLibCheck` before bundling
+- Fix type errors before considering build successful
+
+## Important Files
+
+- `src/main.ts` - Plugin class and lifecycle
+- `src/settings.ts` - Settings interface, defaults, and settings tab UI
+- `manifest.json` - Plugin metadata (never commit with wrong version)
+- `esbuild.config.mjs` - Build configuration
+- `eslint.config.mts` - ESLint configuration with Obsidian-specific rules
+- `styles.css` - Optional plugin styles
+
+## Code Quality Guidelines
+
+From AGENTS.md and Obsidian best practices:
+- Split files when they exceed ~200-300 lines
+- Use clear module boundaries (single responsibility per file)
+- Prefer `async/await` over promise chains
+- Register all cleanup via `this.register*()` helpers to prevent memory leaks
+- Keep startup lightweight; defer heavy work until needed
+- Use stable command IDs (don't rename after release)
+- Provide sensible defaults for all settings