# INTENT.md

> The purpose of this document is to capture **why BinectChrome exists and what it must remain**, independent of any specific line of code. Where the [README](README.md) explains *how to use* the extension and [CLAUDE.md](CLAUDE.md) explains *how the code is structured*, this file records the **intent** that all of those serve. The full requirements live in [`specs/ProductRequirementsDocument.md`](specs/ProductRequirementsDocument.md); the concrete delivered surface lives in [`SCOPE.md`](SCOPE.md). If a future change conflicts with what is written here, the change is suspect — not the intent.

## 1. Core Intent

> **Let a user send a PDF produced in *any* cloud application directly to Binect for physical mail — from the browser where they already work, with explicit intent, and without the extension ever holding their documents.**

BinectChrome is a thin, trustworthy bridge between the browser and the [Binect API](https://app.binect.de/index.jsp?id=api). It collapses the manual **download → re-upload** loop into a single deliberate click, and it does so without asking the source application to change anything.

## 2. What Problem This Solves

Users routinely generate PDFs — letters, invoices, notices — in cloud applications that have no connection to a postal-mail service. Today, sending one physically means: download it from application A, upload it to application B (Binect), repeat for every document. This is slow, error-prone, and discouraging at volume.

BinectChrome targets exactly that friction and nothing beyond it: it notices the PDF the user just produced and offers to send it onward for printing and delivery.

## 3. The Core User Journey

This is the path that must always work end-to-end. Everything else is secondary.

1. The user generates or downloads a PDF in some web application.
2. The extension **detects** it and surfaces it — a toolbar badge and a popup entry showing filename, size, source domain, and time.
3. The user opens the popup, reviews the document, and clicks **Send to Binect**.
4. The extension **re-acquires the PDF bytes** (re-fetching from the original URL using the user's session) and **uploads** them to Binect via the official API, showing unambiguous Uploading → Success / Failure states.
5. The transfer is **recorded locally** for transparency; the user can review history, follow the document through its Binect lifecycle, and report issues via feedback.

If this journey breaks, the product is broken.

## 4. Inviolable Principles

These are the boundary conditions that keep BinectChrome *BinectChrome*. They are constraints, not preferences.

| Principle | Meaning | Consequence |
|-----------|---------|-------------|
| **Explicit user intent** | Nothing is ever sent, ordered, or deleted without a deliberate user click. | No automatic or background dispatch, ever. Sending physical mail costs money and is irreversible. |
| **Zero document retention** | The extension never stores or inspects PDF content. | PDF bytes exist in memory only during an active transfer, then are gone. Only technical metadata is tracked. |
| **Local-only data** | Credentials and tracking history live in the browser and nowhere else. | Tracking data leaves the device only when the user explicitly sends a feedback email. No telemetry. |
| **No backend relay** | The extension talks directly to the Binect API. | There is no BinectChrome server, and no server-side state tied to an installation. |
| **Credentials at rest, encrypted and expiring** | Username/password are AES-GCM encrypted at rest, decrypted only in memory, auto-expire after 60 days of inactivity, and are manually wipeable. | "Use" resets the clock; abandonment erases the secret. |
| **Least privilege** | Request only the permissions the journey actually needs, and justify each. | A permission that doesn't serve §3 doesn't belong in the manifest — it is review-cost the user pays for. |
| **Clean removal** | Uninstalling leaves nothing behind. | All state is local, so removal is complete by construction. |
| **Delegate the API, don't reinvent it** | Binect integration goes through the [`@binect/js`](../binect-js) library. | API-shape changes belong upstream; this repo stays a thin wrapper. |

## 5. Explicitly Out of Scope

BinectChrome is deliberately **not**:
- A document store, viewer, editor, or content analyzer.
- A backend relay or any server-side component.
- An automation / RPA tool that drives third-party sites or sends without a click.
- A credential-federation or shared-identity layer.
- A cross-browser product in v1 — Chrome (Chromium-based, Manifest V3) only.
- A telemetry or analytics collector.

When a feature request can only be satisfied by crossing one of these lines, the correct answer is to decline and document why.

## 6. Success Looks Like

- A user sends a freshly generated PDF to physical mail **without leaving the browser or touching a second app**.
- A transfer's progress and outcome are always legible: Uploading, Success, or an actionable Failure.
- A user can see exactly what was sent, where it came from, and what it cost — entirely from local history.
- Credentials are protected at rest and disappear on their own when unused.
- The extension passes Chrome Web Store review on a minimal permission set.
- No privacy or security incident is ever traceable to the extension holding data it shouldn't.

## 7. How to Use This Document

- **Before adding a feature:** confirm it serves §1 and §3 and violates none of §4. If it requires the extension to retain documents, send without intent, or stand up a backend, it does not belong here.
- **When the Binect API evolves:** adapt through `@binect/js`; preserve the intent. Product intent (this file) stays stable even as API details change.
- **When in doubt:** any decision must be explainable as a direct consequence of the Core Intent in §1.

## 8. Related Documents

- [`SCOPE.md`](SCOPE.md) — the concrete, current operational boundary of what is delivered
- [`specs/ProductRequirementsDocument.md`](specs/ProductRequirementsDocument.md) — the full PRD this intent distills
- [`architecture/ADR-001-credential-encryption.md`](architecture/ADR-001-credential-encryption.md) — the credential-encryption decision
- [`CLAUDE.md`](CLAUDE.md) — architecture and operating instructions for contributors
- [`README.md`](README.md) — usage and developer setup