binect-chrome/INTENT.md

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 explains how to use the extension and 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; the concrete delivered surface lives in 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. 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 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 — the concrete, current operational boundary of what is delivered
• specs/ProductRequirementsDocument.md — the full PRD this intent distills
• architecture/ADR-001-credential-encryption.md — the credential-encryption decision
• CLAUDE.md — architecture and operating instructions for contributors
• README.md — usage and developer setup