binect-chrome/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**BinectChrome** is a Chrome extension (Manifest V3) that enables users to send PDF documents from arbitrary cloud applications directly to Binect for physical printing and postal delivery, eliminating the manual download-upload workflow.

## Core Architecture Principles

### Browser Extension Structure (Manifest V3)
- Service worker-based background script (no persistent background pages)
- Popup UI for user interaction
- Chrome Downloads API for PDF detection
- Chrome Storage API for encrypted credential storage

### Privacy-First Design
- **Zero PDF storage**: PDFs are never stored by the extension
- **Explicit user intent**: No automatic sending; all transfers require user click
- **Metadata minimization**: No content inspection or filename persistence
- **Local-only tracking**: All tracking data stored locally in browser, never transmitted except in support requests

### Authentication & Security
- **Credential storage**: Username/password encrypted at rest in extension storage
- **60-day retention**: Credentials auto-expire after 60 days of inactivity
- **No backend relay**: Extension communicates directly with Binect API
- **Minimal permissions**: Only `downloads`, `storage`, `activeTab`, and Binect API host permission

## Key Functional Components

### 1. PDF Detection System
- **Primary**: Detect completed PDF downloads via Chrome Downloads API
  - Identify by `.pdf` extension or `Content-Type: application/pdf` headers
- **Secondary**: Detect in-browser PDF navigation via `Content-Type: application/pdf`
- **Limitation**: blob URLs and complex JS viewers may not be detectable

### 2. PDF Acquisition & Transfer
- Re-fetch PDF from original URL using user session (preferred)
- Upload to Binect via official API
- Show progress states: Uploading → Success/Failure

### 3. Credential Management
- Encrypt at rest, decrypt only in memory during use
- "Use" = successful authentication or successful send
- Auto-delete after 60 days inactivity
- Manual wipe option always available

### 4. Local Tracking ("Score")
Track locally only:
- Timestamp
- Source domain/URL
- Destination URL
- PDF filesize
- Result (success/failure + error class)

Cap at ~500 entries to prevent unbounded growth.

### 5. User Interface
- **Popup**: Shows last detected PDF (filename, size, timestamp, source domain) + "Send PDF to Binect" button
- **Info/Help ("?")**: Access tracking view with summary counts and chronological transfer list
- **Feedback link**: Opens email to bernd.worsch@binect.de with tracking data as CSV (embedded in body and/or clipboard)

## Technical Constraints

- Chrome Extension Manifest V3 required
- No external backend services
- No cross-browser support in v1 (Chrome only)
- Service worker lifecycle limitations (no persistent background)

## Distribution

- Automated publication via Chrome Web Store
- Must pass Chrome Web Store security review (minimal permissions critical)

## Kaizen Agents

Specialized kaizen agent personas are available on demand via the state-hub MCP —
discover with `list_kaizen_agents()` and load with `get_kaizen_agent("<name>")`,
then read and follow their instructions.

## Contact & Support

Feature requests and bug reports: bernd.worsch@binect.de