Add INTENT.md and SCOPE.md governance documents

INTENT.md captures the project's core intent and inviolable principles;
SCOPE.md draws the concrete operational boundary (in/out of scope,
boundary cases, scope-change process). Both cross-link to the PRD and ADRs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

INTENT.md

@@ -0,0 +1,74 @@
+# INTENT.md
+
+> The purpose of this document is to capture **why this project exists and what it must remain**, independent of any specific line of code. Where the README explains *how to use* Binect-JS and the ADRs explain *how decisions were made*, this file records the **intent** that all of those serve. If a future change conflicts with what is written here, the change is suspect — not the intent.
+
+## 1. Core Intent
+
+> **Enable safe, intuitive JavaScript access to the Binect API for document-based physical mail workflows — without changing, hiding, or reinterpreting what the Binect service actually does.**
+
+Binect-JS exists to **lower the cognitive, technical, and experiential barrier** for developers who need to send PDF documents as physical mail through the [Binect REST API](https://app.binect.de/index.jsp?id=api). It does this by providing a thin, transparent adaptation layer — never by becoming a framework, a backend, or a reinterpretation of the underlying API.
+
+## 2. What Problem This Solves
+
+The Binect API is comprehensive but low-level and REST-centric. Developers integrating it directly must manually handle authentication, base64 encoding, document lifecycle states, and error interpretation. There is no official JavaScript abstraction and no exploratory tooling for learning, testing, and safe experimentation.
+
+This causes:
+- High onboarding friction
+- Frequent implementation errors
+- Duplicated integration effort across projects
+
+Binect-JS targets exactly these frictions — and nothing beyond them.
+
+## 3. The Two Artifacts
+
+1. **Binect-JS SDK (`@binect/js`)** — a thin, type-safe API wrapper (`src/`). Its sub-clients (`documents`, `attachments`, `sendings`, `accounts`, `invoices`) mirror the API's own vocabulary with a 1:1 semantic mapping to REST endpoints.
+2. **Binect Explorer** — a standalone, browser-based interactive tool (`explorer/index.html`) for learning the API, testing uploads and dispatch, and managing reusable use-case profiles. It is a learning surface, not just a test harness.
+
+## 4. Inviolable Principles
+
+These are the constraints that define the project. They are not preferences; they are the boundary conditions that keep Binect-JS *Binect-JS*.
+
+| Principle | Meaning | Consequence |
+|-----------|---------|-------------|
+| **No semantic reinterpretation** | The wrapper must never alter the business meaning or outcome of an API call. | A method that merges, filters, or invents behavior the API doesn't expose does not belong here (see [ADR: no `listAll()`](docs/adr/001-no-listall-method.md)). |
+| **Transparency over abstraction** | Developers must always be able to reason about the actual API calls being made. | No hidden multi-call methods, no magic. |
+| **Thin core, optional convenience** | The Core API Layer is authoritative and 1:1 with REST. The Convenience Layer (`src/helpers.ts`) is additive and **never the only way** to perform an action. | Helpers like `isShippable`, `waitForShippable`, `fetchAllPages` are conveniences, not requirements. |
+| **No runtime dependencies** | Native `fetch` only; works in browsers and Node.js ≥ 18. | No dependency may be added to the SDK runtime. |
+| **No default retries / no hidden network behavior** | All network behavior is explicit and opt-in. | Polling and pagination helpers exist but must be invoked deliberately. |
+| **Ephemeral credentials** | HTTP Basic Auth; credentials are passed per client instance and never stored, cached, or transmitted anywhere but to Binect. | No telemetry, no persistence of secrets. |
+| **No server-side component** | The product must operate without a backend, usable as a local tool or hosted static app. | Explorer runs entirely in the browser. |
+| **Safety against accidental dispatch** | Sending physical mail costs money and is irreversible. | Preview-first workflows and explicit confirmation for destructive actions (send, cancel, delete). |
+
+## 5. Explicitly Out of Scope
+
+Binect-JS is deliberately **not**:
+- A redesign or modification of the Binect backend API
+- A replacement for enterprise backend integrations or workflows
+- A PDF generation, editing, or layout tool
+- A scheduling, batching, or business-process orchestration engine
+- Committed to any specific UI framework or architectural pattern
+
+When a feature request can only be satisfied by crossing one of these lines, the correct answer is to decline and document why — as was done for `listAll()`.
+
+## 6. Success Looks Like
+
+- A developer completes a "send physical mail" workflow **without consulting the raw API documentation**.
+- A first-time user validates and previews a document before sending.
+- API errors are surfaced as structured, understandable, actionable `BinectApiError` / `BinectAuthError`.
+- The wrapper is reused across multiple projects rather than re-implemented.
+- The Explorer is adopted during onboarding and demos.
+
+## 7. How to Use This Document
+
+- **Before adding a feature:** confirm it serves Section 1 and violates none of Section 4. If it requires inventing behavior the API doesn't expose, it belongs in user code or not at all.
+- **When the Binect API evolves:** this wrapper is the single adaptation layer. Update the mapping; preserve the intent. Product intent (this file) should remain stable even as API details change.
+- **When in doubt:** any architectural or technical decision must be explainable as a direct consequence of the Core Intent in Section 1.
+
+## 8. Related Documents
+
+- `ProductRequirementsDocument.md` — the full PRD this intent distills
+- `TechnicalSpecificationDocument.md` — technical orientation
+- `architecture/ADR-00{1,2,3}-*.md` — SDK architecture, no-dependencies, Explorer architecture
+- `docs/adr/001-no-listall-method.md` — a worked example of intent enforced against a feature request
+- `CLAUDE.md` / `AGENTS.md` — operating instructions for human and AI contributors
+- `README.md` — usage and API reference

SCOPE.md

@@ -0,0 +1,94 @@
+# SCOPE.md
+
+> This document defines **what Binect-JS does and does not cover**, concretely. Where [`INTENT.md`](INTENT.md) records *why* the project exists and the principles it must uphold, this file draws the **operational boundary**: which capabilities are in scope, which are explicitly excluded, and where the edges are. A feature request is answered first by checking it against this document.
+
+## 1. Scope Statement
+
+Binect-JS covers **JavaScript/TypeScript access to the Binect REST API for sending PDF documents as physical mail**, plus a browser-based tool for exploring that API. It covers the API surface 1:1 and a small, optional convenience layer on top. It covers nothing on the server, nothing about document creation, and nothing about business process orchestration.
+
+## 2. In Scope
+
+### 2.1 SDK — Core API Coverage (`src/`)
+
+The SDK provides 1:1 semantic mapping to the Binect REST endpoints, organized into domain sub-clients:
+
+| Sub-client | In-scope capabilities |
+|------------|----------------------|
+| `client.documents` | upload (base64 PDF), get, list (shippable), listErrors, delete, getPdf / getPng preview, get/set attributes, applyTransformation (scaling/offset), addCoverPage |
+| `client.sendings` | announce, list, send, cancel, getStatus (batch) |
+| `client.attachments` | upload, list, get, delete, attachToDocuments |
+| `client.accounts` | get (balance/credit), get/update personal data, get/update default print options, getJournal |
+| `client.invoices` | list, get, getPdf |
+
+### 2.2 SDK — Convenience Layer (`src/helpers.ts`, optional, additive)
+
+In scope but **never the only way** to perform an action:
+- Status predicates: `isShippable`, `isErroneous`, `isSent`, `isTerminal`, `isCancelable`, `hasErrors`, `hasWarnings`
+- Extractors / descriptions: `getErrors`, `getStatusDescription`
+- Opt-in polling: `waitForShippable`
+- Explicit pagination: `fetchAllPages`
+- Encoding: `fileToBase64`
+
+### 2.3 SDK — Cross-cutting
+
+- HTTP Basic Authentication (ephemeral, per-client credentials)
+- Native `fetch` transport (`src/http.ts`), browser + Node.js ≥ 18
+- Structured errors: `BinectApiError`, `BinectAuthError`
+- Full TypeScript types and enums (`src/types.ts`) for requests, responses, status/envelope/franking values
+
+### 2.4 Explorer (`explorer/index.html`)
+
+- Browser-based, no backend, runs from a local file or static host
+- Credential input and safe execution of API calls
+- Structured and raw presentation of responses
+- Preview-first workflows before dispatch
+- Reusable, named "use case profiles"
+
+### 2.5 Supporting Material
+
+- Tests (`tests/`), including opt-in e2e tests gated on real credentials
+- Architecture Decision Records (`architecture/`, `docs/adr/`)
+- Research notes on the API (`research/`)
+- Example documents (`examples/`)
+- Contributor instructions (`CLAUDE.md`, `AGENTS.md`)
+
+## 3. Out of Scope
+
+These are excluded by design. A request that requires any of them is a request for a *different* product.
+
+| Excluded | Reason |
+|----------|--------|
+| Modifying or redesigning the Binect backend API | Binect-JS is an adaptation layer, not the service. |
+| Server-side components / hosted backend | The product must operate without server infrastructure ([INTENT §4](INTENT.md)). |
+| PDF generation, editing, or layout tooling | Developers bring PDFs already prepared for sending. |
+| Scheduling, batching, or business-process orchestration | Workflow logic belongs in the consuming application. |
+| Methods that aggregate or reinterpret API behavior (e.g. `listAll()`) | Violates 1:1 mapping and transparency (see [ADR](docs/adr/001-no-listall-method.md)). |
+| Client-side filtering semantics the API doesn't expose | Would invent behavior with no API backing. |
+| Default retries, timeouts, or hidden network behavior | All network behavior must be explicit and opt-in. |
+| Credential storage, caching, or telemetry | Credentials are ephemeral; no hidden data transmission. |
+| Runtime dependencies | Native `fetch` only. |
+| Commitment to a specific UI framework | Explorer stays framework-agnostic. |
+
+## 4. Boundary Cases & Known Edges
+
+- **Document statuses without list endpoints.** The API only lists shippable (status 2) and erroneous (status 7) documents. Statuses 1, 3, 4, 5, 6 (IN_PREPARATION, PRODUCTION_QUEUE, PRINTING, SENT, CANCELED) have no list endpoint — so the SDK cannot and will not offer "list all documents." Retrieval of those statuses is only possible per-document via `get`.
+- **Combining shippable + erroneous lists.** Supported, but only via explicit composition (`fetchAllPages` over each endpoint in parallel), never via a single hidden method.
+- **CORS / direct browser access.** Assumed permitted by Binect. If Binect restricts browser-origin requests, that is an upstream constraint, not something the Explorer works around with a proxy (a proxy would be a server-side component — out of scope).
+- **Large uploads.** PDFs are base64-encoded with a 12 MB ceiling per the API; the SDK surfaces the API's response rather than chunking or pre-validating size beyond what the API enforces.
+
+## 5. Scope Change Process
+
+In scope is defined by what the Binect API exposes plus the thin convenience layer. To change scope:
+
+1. Confirm the change does not violate any principle in [`INTENT.md §4`](INTENT.md).
+2. If it adds API coverage that Binect actually exposes 1:1 → in scope, add it to the relevant sub-client.
+3. If it aggregates, reinterprets, or invents behavior → out of scope; document the decision as an ADR (as was done for `listAll()`).
+4. Update this file and `INTENT.md` together when the boundary genuinely moves.
+
+## 6. Related Documents
+
+- [`INTENT.md`](INTENT.md) — why the project exists and its inviolable principles
+- `ProductRequirementsDocument.md` — full PRD (§4 Scope, §4.2 Non-Scope)
+- `architecture/ADR-00{1,2,3}-*.md` — SDK, no-dependencies, Explorer architecture
+- `docs/adr/001-no-listall-method.md` — a scope boundary enforced against a feature request
+- `README.md` — usage and full API reference