# LinkdingSync Browser Extension - STEERING Document

This document provides project-specific guidelines for the LinkdingSync Firefox extension.

## Project Organization

- Project location: `MyWorkspace/Linkding Browser Extension/`
- Extension code: `bookmark-sync/` subfolder
- Documentation: `docs/` subfolder
- Assets: Stored in `MyWorkspace/` to avoid permission prompts

## Resource Storage

All downloaded resources should be stored within the `MyWorkspace` folder:

- **Git repositories:** Clone to `MyWorkspace/linkding/` and `MyWorkspace/linkding-extension/`
- **Extension assets:** Store in `MyWorkspace/Linkding Browser Extension/assets/`
- **Design documents:** Store in `MyWorkspace/Linkding Browser Extension/docs/`
- **Icon files:** Store in `MyWorkspace/Linkding Browser Extension/bookmark-sync/icons/`

## Documentation Practices

### Plan Mode Documentation

Before starting implementation in Plan mode:

1. **Create design documents** in `docs/` folder
2. **Define all architecture decisions** before implementation
3. **Document API specifications** and data structures
4. **Review design document** with user before switching to Act mode

### Documentation Files

- `DESIGN.md` - Main design document with architecture and implementation plan
- `README.md` - Project overview and quick start guide
- `TASKS.md` - Current task checklist and progress tracking

## Development Workflow

1. **Plan Phase (Plan Mode):**
   - Document all design decisions
   - Create detailed implementation plans
   - Store designs in `docs/` folder
   - Present plan to user for approval

2. **Implementation Phase (Act Mode):**
   - Follow approved design document
   - Implement features according to plan
   - Write code with proper documentation
   - Test and verify functionality

## Technology Guidelines

- **Firefox Extension Manifest Version:** 2 (for maximum compatibility)
- **API Client:** Use `fetch()` for API calls
- **Storage:** Use Firefox Web Storage API (`localStorage`, `sessionStorage`)
- **Icons:** SVG format preferred for scalability

## Security Considerations

- Store API tokens in web storage (client-side only)
- Validate all API responses
- Handle authentication errors gracefully
- Never expose API tokens in client-side code

## Testing Strategy

- Test sync scenarios: add, update, delete bookmarks
- Test conflict resolution for bi-directional sync
- Test edge cases: network failures, API rate limits
- Verify bookmark folder structure is preserved