bitsofchris_openaugi-obsidian-plugin/CLAUDE.md

# OpenAugi Obsidian Plugin - Technical Overview

## Project Purpose
OpenAugi is an Obsidian plugin that transforms voice notes and linked notes into organized, atomic notes using AI. It helps users process unstructured thoughts into a structured "second brain" by breaking down content into self-contained ideas.

The goal is to help humans process information faster.

Read the docs/CODEBASE_MAP.md to understand the project at a high level. Be sure to update this map as we make any siginficant changes.

## Architecture Overview

### Project Structure
```
/
├── src/
│   ├── main.ts                 # Plugin entry point, command registration
│   ├── services/
│   │   ├── openai.service.ts   # AI processing logic
│   │   ├── file.service.ts     # File operations, output management
│   │   └── distill.service.ts  # Linked note extraction, content aggregation
│   ├── ui/
│   │   └── settings.ts         # Settings tab UI component
│   └── utils/
│       └── filename.utils.ts   # Filename sanitization, backlink mapping
├── manifest.json               # Obsidian plugin metadata
├── package.json                # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
└── esbuild.config.mjs         # Build configuration
```

## Key Features

### 1. Voice Transcript Parsing
- Processes voice transcripts into atomic notes (one idea per note)
- Extracts actionable tasks and creates summaries
- Supports "auggie" voice commands for special behaviors
- Estimates token usage before processing

### 2. Linked Notes Distillation
- Analyzes a root note and all its linked notes
- Supports both standard Obsidian links and Dataview queries
- Deduplicates and merges overlapping ideas
- Creates comprehensive summaries with source attribution

### 3. Custom Context Instructions
- Users can add `context:` sections to notes for focused extraction
- Context instructions guide AI processing behavior

## Development Guidelines

### Build Commands

**Important:** `npm` is not on the default PATH in this environment. Source nvm first:
```bash
export PATH="$HOME/.nvm/versions/node/$(ls $HOME/.nvm/versions/node/ | head -1)/bin:$PATH"
```

Then run commands as normal:
```bash
# Development build with hot reload
npm run dev

# Production build (includes typecheck)
npm run build
```

There is no standalone `typecheck` script — `npm run build` runs `tsc -noEmit -skipLibCheck` before bundling.

### Code Standards
- TypeScript with strict mode enabled
- ESLint configuration for code quality
- No external runtime dependencies (only Obsidian API)

### Testing

Automated test suite using Vitest with a mock Obsidian API. See [docs/TESTING.md](docs/TESTING.md) for full details.

```bash
# Run all tests
npm test

# Watch mode
npm run test:watch
```

Tests cover: filename utils, OpenAI prompt building, link extraction, BFS traversal, content aggregation, file output, journal filtering, backlink discovery. New features should include test coverage.

## API Integration

### OpenAI Service
- Model: GPT-4.1-2025-04-14
- Temperature: 0.7 for parsing, 0.3 for distilling
- Structured output using JSON schema
- Token estimation before API calls

### File Operations
- Creates atomic notes in configurable folders
- Generates summaries with backlinks
- Handles special characters in filenames
- Maintains backlink mappings for navigation

## Configuration

### User Settings
- `openaiApiKey`: Required for AI processing
- `summaryFolderPath`: Default "OpenAugi/Summaries"
- `notesFolderPath`: Default "OpenAugi/Notes"
- `useDataview`: Enable/disable Dataview integration

### Build Configuration
- Target: ES2018/ES6
- Platform: Browser (Electron)
- External: Obsidian modules
- Sourcemaps enabled for development

## Output Structure

### Summary Files
- Format: `[original-name] - summary.md` or `[original-name] - distilled.md`
- Contains: Summary, atomic note links, extracted tasks
- For distilled notes: Shows source note references

### Atomic Notes
- Self-contained ideas with context
- Includes relevant backlinks
- Organized by timestamp or topic

## Common Development Tasks

### Adding New Features
1. Extend services in `/src/services/`
2. Update command registration in `main.ts`
3. Add settings if needed in `settings.ts`

### Debugging
- Use Obsidian's developer console (Ctrl+Shift+I)
- Check console for error messages
- Enable verbose logging in development

### Publishing
See [docs/PUBLISHING.md](docs/PUBLISHING.md) for the complete release process,
including community-store listing health and how to relist if de-listed.

**Just run the script** (it bumps all three version files, publishes, and verifies):
```bash
# write docs/release-notes/X.Y.Z.md first, then:
./scripts/release.sh X.Y.Z
```

**Non-negotiables** (the guard test `tests/version-consistency.test.ts` enforces these):
- Bump **all THREE** version files together: `manifest.json`, `package.json`, **and `versions.json`** (add `"X.Y.Z": "<minAppVersion>"`). Forgetting `versions.json` is the classic mistake.
- Tag == `manifest.version`, no `v` prefix.
- **Publish the draft immediately** after CI — never leave the repo advertising a version with no published release (that inconsistency can get the plugin auto-removed from the store).

## Important Considerations

- Always handle API errors gracefully
- Respect rate limits and token usage
- Sanitize filenames to prevent filesystem issues
- Maintain backwards compatibility with existing notes
- Test with various note structures and edge cases

# Testing

My local testing vault is in: /Users/chris/zk-for-testing

Add any notes to /Users/chris/Documents/DEV-TESTING/Test to capture edge cases when relevant.