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

# 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:

{
  "path": "Work/Resources/Development",
  "userNotes": "Development resources folder",
  "autoTags": [
    {"name": "Work"},
    {"name": "Resources"},
    {"name": "Development"}
  ]
}

2.4 KiB Raw Blame History