# AGENTS.md - Developer Guide for Insertr

## Build/Test Commands
- `just dev` - Full-stack development with auto-enhanced demo sites (recommended)
- `just serve` - API server only with multi-site hosting
- `just build` - Build entire project (Go binary + JS library)
- `just build-lib` - Build JS library only
- `just enhance` - CLI enhancement of static sites

For complete command reference, see the justfile.

## Code Style Guidelines

### Go (Backend)
- Use standard Go formatting (`gofmt`)
- Package imports: stdlib → third-party → internal
- Error handling: always check and handle errors
- Naming: camelCase for local vars, PascalCase for exported
- Comments: package-level comments, exported functions documented

### JavaScript (Frontend)
- ES6+ modules, no CommonJS
- camelCase for variables/functions, PascalCase for classes
- Use `const`/`let`, avoid `var`
- Prefer template literals over string concatenation
- Export classes/functions explicitly, avoid default exports when multiple exports exist
- NO COMMENTS unless explicitly asked - keep code clean and self-documenting
- HTML-first approach: preserve element attributes and styling perfectly

### Database
- Use `sqlc` for Go database code generation
- SQL files in `db/queries/`, schemas in `db/{sqlite,postgresql}/setup.sql`
- Version history implemented with full rollback capabilities
- Run `just sqlc` after schema changes
- Multi-database support: SQLite for development, PostgreSQL for production

## Current Architecture

### Frontend (Library)
- **StyleAware Editor**: Rich text editing with automatic style detection
- **HTML Preservation**: Perfect fidelity editing that maintains all element attributes
- **Style Detection Engine**: Automatically generates formatting options from detected CSS
- **Link Management**: Popup-based configuration for complex multi-property elements
- **Zero Dependencies**: No markdown libraries - HTML-first approach

### Backend (Go Binary)
- **Multi-Site Server**: Hosts and auto-enhances multiple static sites
- **Real-Time Enhancement**: Content changes trigger immediate file updates
- **Full REST API**: Complete CRUD operations with version control
- **Authentication**: Mock (dev) + Authentik OIDC (production)
- **Database Layer**: SQLite/PostgreSQL with full version history

### Key Principles
- **HTML-First**: No lossy markdown conversion - perfect attribute preservation
- **Zero Configuration**: Just add `class="insertr"` to any element
- **Style-Aware**: Automatically detect and offer CSS-based formatting options
- **Performance**: Regular visitors get pure static HTML with zero CMS overhead