generated from coulomb/repo-seed
tegwick
9a42001972
- Add INTENT.md (purpose and inviolable principles) and SCOPE.md (current operational boundary), matching the binect-js house style. - Reconcile the PRD with the shipped document-lifecycle scope: add ordering/server-sync requirements (4.3a), split the proxy queue vs. tracking-log caps (4.6.3), and update the solution summary/closing. - Rename computeMD5 -> computeContentFingerprint to be honest: it is a fast sampled non-cryptographic fingerprint for dedup, not MD5. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
78 lines
6.3 KiB
Markdown
78 lines
6.3 KiB
Markdown
# 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
|