# AGENTS.md - Project Guidance for Coding Agents

## Project Overview
LinkdingSync is a Firefox browser extension that synchronizes bookmarks with a self-hosted Linkding instance. It provides bi-directional sync, folder structure preservation, and optional auto-tag generation.

## Setup & Build Commands
```bash
# Install project dependencies
npm install

# Start development server
npm run dev

# Run unit tests
npm test

# Run linting
npm run lint

# Build production bundle
npm run build
```

## Architecture Notes
- **Extension Manifest**: `manifest.json` - Firefox extension configuration
- **Popup UI**: `popup.html` + `popup.css` + `popup.js` - User interface
- **Background Service**: `background.js` - Service worker for sync logic
- **Utils**: `utils/` folder - Bookmark manipulation, sync logic, conflict resolution
- **API Integration**: Uses Linkding REST API for bookmark operations

## Testing
- **Unit tests**: `npm test` - Test individual utility functions
- **E2E tests**: `npx playwright test` - Browser automation tests (if Playwright configured)
- **Coverage target**: 80%
- **Browser tests**: Use Playwright to simulate user interactions

## Conventions
- **File naming**: PascalCase for components, kebab-case for CSS classes
- **Error handling**: Try/catch with async/await, error boundaries
- **API patterns**: Restful endpoints with token-based authentication
- **Do not modify**: `manifest.json` requires Firefox extension signing (unless in development mode)
- **Secrets**: API tokens stored in browser storage (client-side only)

## Session Logging
- **Auto-saved to**: `@LinkdingSync\chatlog.md`
- **Review via**: File explorer (not IDE working set)
- **Archived to**: `../docs\session-YYYYMMDD.md`

## Known Issues
- Firefox extension requires signing for distribution (not in dev mode)
- API token storage is client-side only (user must protect token)
- Browser compatibility limited to Firefox (extension format)

## Project Tools
- **OpenCode**: Main agent for iterative test development
- **Playwright**: For browser automation and E2E testing
- **API Endpoint**: `https://api.links.blabber1565.com` (example - adjust as needed)

## Notes Structure Example
Bookmarks in Linkding use this notes format:
```json
{
  "path": "Work/Resources/Development",
  "userNotes": "Development resources folder",
  "autoTags": [
    {"name": "Work"},
    {"name": "Resources"},
    {"name": "Development"}
  ]
}