From f75afbfe5863ac9c63b5ea51a1936cd9a82580ea Mon Sep 17 00:00:00 2001
From: mpstaton <mpstaton@gmail.com>
Date: Fri, 14 Nov 2025 14:25:16 +0000
Subject: [PATCH] Add WARP.md documentation for development workflow

---
 WARP.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 WARP.md

diff --git a/WARP.md b/WARP.md
new file mode 100644
index 0000000..7620031
--- /dev/null
+++ b/WARP.md
@@ -0,0 +1,147 @@
+# WARP.md
+
+This file provides guidance to WARP (warp.dev) when working with code in this repository.
+
+## Repository Overview
+
+**Perplexed** is an Obsidian plugin for AI-powered content generation with source citations. It integrates with Perplexity (commercial), Perplexica (self-hosted), and LM Studio (local) to generate research-grade content directly in Obsidian notes.
+
+## Common Commands
+
+### Development
+```bash
+# Install dependencies
+pnpm install
+
+# Development mode with watch (auto-rebuilds on changes)
+pnpm dev
+
+# Production build
+pnpm build
+
+# Type check without emitting
+tsc -noEmit -skipLibCheck
+```
+
+### Testing
+```bash
+# Test Perplexity API (streaming)
+./test-perplexity-api.sh
+
+# Test Perplexity API (non-streaming)
+./test-perplexity-non-streaming.sh
+```
+
+### Version Management
+```bash
+# Bump version (updates manifest.json and versions.json)
+pnpm version
+```
+
+### Obsidian Development Setup
+```bash
+# Create symbolic link to Obsidian plugins folder (macOS/Linux)
+ln -s $(pwd) /path/to/obsidian/vault/.obsidian/plugins/perplexed
+
+# Windows (PowerShell)
+New-Item -ItemType SymbolicLink -Path "C:\path\to\vault\.obsidian\plugins\perplexed" -Target "C:\path\to\perplexed"
+```
+
+## Architecture
+
+### File Structure
+
+**Core Files**:
+- `main.ts` - Plugin entry point with all command registration and API logic (64KB monolithic file)
+- `manifest.json` - Plugin metadata for Obsidian
+- `styles.css` - Plugin UI styles (generated from `src/styles/main.css`)
+
+**Source Organization** (`src/`):
+- `modals/` - Modal UI components for user input
+- `services/` - API integration services (Perplexity, Perplexica, LM Studio)
+- `types/` - TypeScript type definitions
+- `utils/` - Utility functions
+- `styles/` - CSS source files
+- `docs/` - Additional documentation
+
+**Build Configuration**:
+- `esbuild.config.mjs` - Build system (bundles TypeScript → JavaScript)
+- `tsconfig.json` - TypeScript compiler configuration (strict mode)
+- `.eslintrc` - Code quality rules
+
+### Key Patterns
+
+**1. Monolithic Main File**
+The entire plugin logic lives in `main.ts` (64KB). All commands, API calls, modals, and settings are in a single `PerplexedPlugin` class.
+
+**2. Command Registration**
+Three provider-specific command registration methods:
+- `registerPerplexityCommands()` - Perplexity commercial API
+- `registerPerplexicaCommands()` - Self-hosted Perplexica
+- `registerLMStudioCommands()` - Local LM Studio
+
+**3. Modal-Based UI**
+Each command creates an Obsidian Modal with configuration options (model selection, streaming toggle, etc.)
+
+**4. Streaming Responses**
+Uses `fetch` with streaming to display AI responses in real-time via `response.body.getReader()`
+
+**5. Settings Persistence**
+Settings stored via Obsidian's `loadData()`/`saveData()` API
+
+### Build System
+
+**esbuild** configuration:
+- Target: ES2022
+- Format: CommonJS (required by Obsidian)
+- Bundle: Single `main.js` output
+- External: Obsidian API, Electron, CodeMirror
+- CSS: Separate build from `src/styles/main.css` → `styles.css`
+- Dev mode: Watch mode with inline sourcemaps
+- Production: Minified, no sourcemaps
+
+### TypeScript Configuration
+
+Extremely strict TypeScript settings enabled:
+- `strict: true` with all sub-flags
+- `noUnusedLocals`, `noUnusedParameters`
+- `exactOptionalPropertyTypes`
+- `noImplicitReturns`
+- `noUncheckedIndexedAccess`
+
+## API Integrations
+
+### Perplexity
+- Endpoint: `https://api.perplexity.ai/chat/completions`
+- Models: `sonar-pro`, `sonar-small`, `sonar-deep-research`, etc.
+- Features: Citations, images, related questions, recency filters
+- Streaming: Supported via SSE
+
+### Perplexica
+- Default endpoint: `http://localhost:3030/api/search`
+- Focus modes: webSearch, academicSearch, writingAssistant, wolframAlpha, etc.
+- Optimization: speed, balanced, quality
+- Streaming: Supported
+
+### LM Studio
+- Default endpoint: `http://localhost:1234/v1/chat/completions`
+- Local model support (e.g., `ibm/granite-3.2-8b`, `microsoft/phi-4-reasoning-plus`)
+- Custom system prompts, temperature, max tokens
+
+## Development Workflow
+
+1. **Make changes** to `main.ts` or files in `src/`
+2. **Build** (dev watch mode auto-rebuilds): `pnpm dev`
+3. **Test in Obsidian**: Reload plugin or restart Obsidian
+4. **Check console**: `Cmd/Ctrl + Shift + I` for errors
+5. **Iterate**: Edit → auto-rebuild → test
+
+## Important Notes
+
+- **Monolithic architecture**: All logic in `main.ts` - no module splitting
+- **Obsidian API**: External dependency, not bundled
+- **No automated tests**: Manual testing in Obsidian required
+- **Desktop only**: Plugin marked as `isDesktopOnly: true` in manifest
+- **ESLint configured**: Use `eslint` for linting (config in `.eslintrc`)
+- **Strict TypeScript**: Code must satisfy very strict type checking
+- **CSS build**: CSS is built separately then imported as text in main bundle