Add roadmap and an implementation plan for HTTP API upgrades

README.md

@@ -10,11 +10,12 @@ Run the maintained local example:
 go run ./cmd/distributor run --config examples/local-publish.yml
 ```
 
-Go producers can use `gitea.maximumdirect.net/eric/distributor/pkg/bundle` to build, write, parse, and validate local source bundles with the same manifest contract used by the CLI. They can use `gitea.maximumdirect.net/eric/distributor/pkg/upload` to build or validate a bundle and submit it to `distributor serve` with bearer authentication and idempotency keys. See [Source bundle contract](docs/integrations/source-bundle.md) and [HTTP upload contract](docs/integrations/http-upload.md).
+Go producers can use `gitea.maximumdirect.net/eric/distributor/pkg/upload` and `gitea.maximumdirect.net/eric/distributor/pkg/bundle` to submit compatible bundles to `distributor serve`. See [Upstream producer integration](docs/consumers/api.md).
 
 - [CLI reference](docs/cli.md)
 - [Configuration reference](docs/config.md)
 - [Operations guide](docs/operations.md)
+- [Consumer API guide](docs/consumers/api.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Integration contracts](docs/integrations/source-bundle.md)
 - [Development architecture](docs/policy/architecture.md)

docs/consumers/api.md

@@ -0,0 +1,132 @@
+# Upstream Producer Integration
+
+Audience: developers and LLM coding agents adding `distributor` support to an upstream Go producer application.
+
+This document is the copyable implementation guide for submitting producer outputs to a `distributor` pipeline whose source backend is `http_upload`.
+
+## Required Inputs
+
+The upstream application needs these values from deployment or operator configuration:
+
+- distributor endpoint: the HTTP server base URL, such as `https://distributor.example.com`;
+- upload token: bearer token for exactly one configured `http_upload` pipeline;
+- generated files: regular local files to include in the source bundle;
+- bundle id: stable identifier for the logical report stream or artifact;
+- idempotency key: unique key for one producer run, reused only when retrying that same run.
+
+Do not put destination routing, public URLs, transform settings, or credentials in the source manifest. Those belong in the `distributor` pipeline configuration.
+
+The bundle id and idempotency key have different jobs. The bundle id tells `distributor` whether a new upload is a newer version of the same source; keep it stable across runs that should replace the same managed destination artifact. The idempotency key tells `distributor` whether an upload request is a retry; change it for each distinct producer run so new content is enqueued.
+
+## Recommended Workflow
+
+Use `gitea.maximumdirect.net/eric/distributor/pkg/upload`.
+
+For most producers, use `UploadFiles`. It accepts producer-generated files, builds a temporary valid source bundle with `pkg/bundle`, uploads a gzip-compressed tar archive, and removes temporary files when the call returns.
+
+Use `UploadBundle` only when the producer already assembled a complete bundle directory containing `manifest.json`.
+
+Add the dependency from the upstream application:
+
+```sh
+go get gitea.maximumdirect.net/eric/distributor
+```
+
+## Minimal Go Example
+
+```go
+package reports
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/pkg/bundle"
+	"gitea.maximumdirect.net/eric/distributor/pkg/upload"
+)
+
+func SubmitReport(reportPath, summaryPath string) error {
+	endpoint := os.Getenv("DISTRIBUTOR_UPLOAD_ENDPOINT")
+	token := os.Getenv("DISTRIBUTOR_UPLOAD_TOKEN")
+	if endpoint == "" || token == "" {
+		return fmt.Errorf("distributor endpoint and token are required")
+	}
+
+	reportID := "weather.hourly.brentwood"
+	runID := time.Now().UTC().Format("20060102T150405.000000000Z")
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	client, err := upload.NewClient(upload.ClientOptions{
+		Endpoint: endpoint,
+		Token:    token,
+	})
+	if err != nil {
+		return err
+	}
+
+	result, err := client.UploadFiles(ctx, upload.UploadFilesOptions{
+		ID:             reportID,
+		IdempotencyKey: reportID + "." + runID,
+		Files: []bundle.BundleFile{
+			{SourcePath: reportPath, Path: "report.md"},
+			{SourcePath: summaryPath, Path: "summary.txt"},
+		},
+	})
+	if err != nil {
+		var conflict *upload.IdempotencyConflictError
+		if errors.As(err, &conflict) {
+			return fmt.Errorf("idempotency key was reused for different bundle content: %w", err)
+		}
+		return err
+	}
+
+	fmt.Printf("distributor accepted run %s\n", result.RunID)
+	return nil
+}
+```
+
+## Producer Responsibilities
+
+- Use a stable bundle id for the logical producer output that should replace the same destination artifact, such as `weather.hourly.brentwood`.
+- Do not include per-run timestamps, random values, or job ids in the bundle id unless each run should be treated as a different source.
+- Use an idempotency key that changes for every distinct producer run, such as `<bundle-id>.<run-id>`.
+- Reuse the same idempotency key only when retrying the exact same producer run with the same source manifest.
+- Map each generated file to a clean slash-separated bundle path, such as `report.md` or `assets/chart.png`.
+- Include only regular files. Symlinks, directories as files, devices, FIFOs, and sockets are rejected.
+- Keep file contents stable after upload inputs are selected. Bundle digests are calculated from file bytes.
+- Treat upload success as admission only. `UploadFiles` and `UploadBundle` return after the server accepts and validates the upload, not after all destinations publish.
+
+Valid bundle paths are relative slash paths. They must not be empty, absolute, contain backslashes, contain `.` or `..` path segments, contain empty path segments, or use reserved basenames `manifest.json` or `.distributor.json`.
+
+## Idempotency And Status
+
+`pkg/upload` sends `Idempotency-Key` on every upload. If the caller omits one, the package generates a random key for that call and reuses it for in-process retries. That is enough for transient network retry within one process, but it does not give cross-process retry identity.
+
+For producer jobs that may retry after process restart, supply a key derived from the producer run, such as `<bundle-id>.<run-id>`. Reusing the same key with the same normalized source manifest returns the original accepted run. Reusing the same key with different source content returns a conflict. Reusing one key across multiple distinct report generations prevents those generations from being treated as new uploads.
+
+`Status` polls `/runs/<run-id>` while the distributor server retains the in-memory status record. Status values are `accepted`, `queued`, `running`, `succeeded`, and `failed`. Completed records expire according to the server's `server.http.retention` setting, and server restart clears status and idempotency records.
+
+Optional status check:
+
+```go
+status, err := client.Status(ctx, result.RunID)
+if err != nil {
+	return err
+}
+if status.Status == "failed" {
+	return fmt.Errorf("distributor run failed: %s", status.Error)
+}
+```
+
+## References
+
+In the `distributor` source tree:
+
+- `docs/consumers/pkg-upload.md`: Go upload package workflow.
+- `docs/consumers/pkg-bundle.md`: Go bundle package workflow.
+- `docs/integrations/http-upload.md`: canonical HTTP upload wire contract.
+- `docs/integrations/source-bundle.md`: canonical source bundle file-format contract.

docs/consumers/pkg-bundle.md

@@ -0,0 +1,90 @@
+# `pkg/bundle`
+
+Audience: upstream Go producer developers and LLM coding agents using `distributor` source bundle helpers.
+
+Import path:
+
+```go
+import "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
+```
+
+`pkg/bundle` builds, writes, parses, and validates local source bundles. Use it directly when a producer writes bundles for `distributor` to discover, or when a producer wants to assemble and validate a bundle before using another transport.
+
+The canonical source bundle file-format contract is [Source Bundle Contract](../integrations/source-bundle.md).
+
+## Preferred Complete-Bundle Workflow
+
+Use `WriteBundle` when producer-generated files live outside the final bundle root.
+
+```go
+manifest, err := bundle.WriteBundle(bundle.WriteBundleOptions{
+	Root: "/var/spool/distributor/weather/hourly-2026-06-07T15",
+	ID:   "weather.hourly.brentwood",
+	Files: []bundle.BundleFile{
+		{SourcePath: "/tmp/weather/report.md", Path: "report.md"},
+		{SourcePath: "/tmp/weather/summary.txt", Path: "summary.txt"},
+	},
+})
+if err != nil {
+	return err
+}
+_ = manifest
+```
+
+`WriteBundle` copies each source file into a staged bundle root, writes `manifest.json`, validates the staged bundle, and promotes it into place. Set `Overwrite: true` only when the producer intentionally replaces an existing bundle root.
+
+## Existing Bundle Root Workflow
+
+Use `BuildManifest` and `WriteManifest` when files are already staged under the final bundle root.
+
+```go
+root := "/var/spool/distributor/weather/hourly-2026-06-07T15"
+manifest, err := bundle.BuildManifest(bundle.BuildOptions{
+	Root:  root,
+	ID:    "weather.hourly.brentwood",
+	Files: []string{"report.md", "summary.txt"},
+})
+if err != nil {
+	return err
+}
+if err := bundle.WriteManifest(root, manifest, bundle.WriteManifestOptions{}); err != nil {
+	return err
+}
+if err := bundle.ValidateBundle(root, manifest); err != nil {
+	return err
+}
+```
+
+Use `Scan: true` instead of `Files` only when every valid regular file under the root should be included. Scan mode includes dotfiles, skips reserved metadata files, rejects symlinks, and sorts paths lexically.
+
+## Paths And Ordering
+
+Bundle paths are slash-separated paths relative to the bundle root.
+
+Invalid paths include:
+
+- empty paths;
+- absolute paths;
+- paths containing backslashes;
+- `.` or `..` path segments;
+- empty path segments;
+- any basename of `manifest.json` or `.distributor.json`.
+
+Explicit file lists preserve caller order. File order is part of the bundle digest, so producers should choose it deliberately and keep it stable.
+
+The manifest `ID` is the logical source identity used by `distributor` destination comparison. Keep it stable for runs that should replace the same managed destination artifact. If every run uses a different manifest `ID`, `distributor` treats those runs as different sources and may report a destination conflict instead of replacing older output.
+
+## Validation And Digest Helpers
+
+Use `ValidateBundle` before handing an existing local bundle to another process. It verifies manifest semantics, file existence, regular-file type, file size, per-file SHA-256 digests, and bundle digest.
+
+Useful helpers:
+
+- `LoadManifest`: read `manifest.json` from a bundle root.
+- `ParseManifest` and `MarshalManifest`: parse or write manifest bytes.
+- `ValidateManifest`: validate manifest-only semantics.
+- `FileDigest`, `BundleDigest`, and `ValidateDigest`: digest helpers for diagnostics and tests.
+
+## Boundaries
+
+`pkg/bundle` does not upload bundles, publish destinations, transform Markdown, select pipelines, configure credentials, or write destination state. Those concerns belong to `pkg/upload` or the `distributor` application.

docs/consumers/pkg-upload.md

@@ -0,0 +1,120 @@
+# `pkg/upload`
+
+Audience: upstream Go producer developers and LLM coding agents submitting bundles to `distributor serve`.
+
+Import path:
+
+```go
+import "gitea.maximumdirect.net/eric/distributor/pkg/upload"
+```
+
+`pkg/upload` is the producer-facing HTTP upload client. It builds on `pkg/bundle`, packages valid source bundles as gzip-compressed tar archives, sends bearer authentication, includes idempotency keys, and exposes a status polling helper.
+
+`UploadFiles` examples also use:
+
+```go
+import "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
+```
+
+The canonical HTTP wire contract is [HTTP Upload API Contract](../integrations/http-upload.md).
+
+## Client Construction
+
+```go
+client, err := upload.NewClient(upload.ClientOptions{
+	Endpoint: "https://distributor.example.com",
+	Token:    token,
+})
+if err != nil {
+	return err
+}
+```
+
+`Endpoint` is the distributor server base URL. The client derives `/upload` and `/runs/<run-id>`. `Token` is required and is sent as `Authorization: Bearer <token>`. Token values are redacted from client errors.
+
+`HTTPClient` and `Retry` are optional. Defaults use a 30 second HTTP timeout and safe retry settings.
+
+## Upload Producer Files
+
+Use `UploadFiles` when the producer has generated output files but has not assembled a bundle directory.
+
+```go
+result, err := client.UploadFiles(ctx, upload.UploadFilesOptions{
+	ID:             "weather.hourly.brentwood",
+	IdempotencyKey: "weather.hourly.brentwood.20260607T150000Z",
+	Files: []bundle.BundleFile{
+		{SourcePath: "/tmp/weather/report.md", Path: "report.md"},
+		{SourcePath: "/tmp/weather/summary.txt", Path: "summary.txt"},
+	},
+})
+if err != nil {
+	return err
+}
+_ = result.RunID
+```
+
+`UploadFiles` creates a temporary bundle, writes and validates a manifest, uploads the archive, and removes temporary files when the call returns. It does not write into producer source directories.
+
+## Upload An Existing Bundle
+
+Use `UploadBundle` when the producer already has a complete local bundle root containing `manifest.json`.
+
+```go
+result, err := client.UploadBundle(ctx, upload.UploadBundleOptions{
+	Root:           "/var/spool/weather/hourly-2026-06-07T15",
+	IdempotencyKey: "weather.hourly.brentwood.20260607T150000Z",
+})
+if err != nil {
+	return err
+}
+_ = result.RunID
+```
+
+`UploadBundle` validates the local bundle by default and uploads only `manifest.json` plus manifest-listed files. Unlisted files are not uploaded.
+
+## Result And Status
+
+Upload success means the server returned `202 Accepted` after staging and validating the upload. It does not mean all configured destinations have published.
+
+Poll status while the server retains the in-memory run record:
+
+```go
+status, err := client.Status(ctx, result.RunID)
+if err != nil {
+	return err
+}
+if status.Status == "failed" {
+	return fmt.Errorf("distributor run failed: %s", status.Error)
+}
+```
+
+Status values are `accepted`, `queued`, `running`, `succeeded`, and `failed`. Completed records expire according to `server.http.retention`; server restart clears run status and idempotency records.
+
+## Idempotency And Retry
+
+Every upload request includes `Idempotency-Key`.
+
+If `IdempotencyKey` is omitted, the client generates a random 128-bit lowercase hexadecimal key for that upload operation and reuses it for retries within the same call. For cross-process retry safety, producers should pass a key derived from the producer run, such as `<bundle-id>.<run-id>`.
+
+Do not reuse the same idempotency key for multiple distinct report generations. Reuse it only when retrying the exact same run with the same source manifest. A repeated key with the same manifest returns the original accepted run instead of enqueueing another run; a repeated key with different content returns an idempotency conflict.
+
+The client retries only safe cases:
+
+- `503 Service Unavailable`;
+- temporary network errors;
+- ambiguous mid-upload failures.
+
+It does not retry after `202 Accepted` and does not retry `400`, `401`, `409`, `413`, or `415`.
+
+Detect conflicting key reuse with `errors.As`:
+
+```go
+var conflict *upload.IdempotencyConflictError
+if errors.As(err, &conflict) {
+	return fmt.Errorf("idempotency key was reused for different bundle content: %w", err)
+}
+```
+
+## Boundaries
+
+`pkg/upload` does not configure server pipelines, choose destinations, wait for publication completion automatically, persist client queues, provide durable idempotency across server restarts, or expose destination state. It submits complete source bundles to the configured HTTP upload API.

docs/integrations/http-upload.md

@@ -71,7 +71,7 @@ Retryable idempotency conflicts include:
 {"error":"upload idempotency key is already being processed","retryable":true}
 ```
 
-When `Idempotency-Key` is omitted, upload admission preserves the raw HTTP behavior: every valid accepted upload receives its own run id. When a key is supplied, the server records the accepted run after archive staging and source bundle validation succeed. Reusing the same key for the same authenticated pipeline and the same normalized source manifest returns the original `202 Accepted` response and does not enqueue another run. Reusing the same key for a different normalized source manifest returns `409 Conflict`.
+When `Idempotency-Key` is omitted, upload admission preserves the raw HTTP behavior: every valid accepted upload receives its own run id. When a key is supplied, the server records the accepted run after archive staging and source bundle validation succeed. Reusing the same key for the same authenticated pipeline and the same normalized source manifest returns the original `202 Accepted` response and does not enqueue another run. Reusing the same key for a different normalized source manifest returns `409 Conflict`. Producers should use a fresh key for each distinct producer run and reuse a key only for retries of that same run.
 
 ### `GET /runs/<run-id>`
 
@@ -108,7 +108,7 @@ The uploaded archive size and extracted bundle size are bounded by the selected
 
 ## Go Producer Helper
 
-Go producers can use `gitea.maximumdirect.net/eric/distributor/pkg/upload` to build or validate source bundles, package them as gzip-compressed tar archives, and submit them to this API:
+Go producers can use `gitea.maximumdirect.net/eric/distributor/pkg/upload` to build or validate source bundles, package them as gzip-compressed tar archives, and submit them to this API. See [Upstream Producer Integration](../consumers/api.md) for the copyable upstream implementation guide and [`pkg/upload`](../consumers/pkg-upload.md) for package-specific workflow guidance.
 
 ```go
 client, err := upload.NewClient(upload.ClientOptions{

docs/integrations/source-bundle.md

@@ -27,7 +27,7 @@ Current schema version: `1`.
 Required manifest fields:
 
 - `schema_version`: must be `1`.
-- `id`: non-empty bundle identifier.
+- `id`: non-empty bundle identifier. For replacement workflows, keep this stable for the logical source that should update the same managed destination artifact.
 - `digest`: lowercase `sha256:<64 hex>` digest of the ordered `files` list.
 - `created`: RFC3339 timestamp.
 - `files`: non-empty ordered list of file records.
@@ -60,7 +60,7 @@ File order is significant. Explicit file lists preserve caller order. Scan mode
 
 ## Producer APIs
 
-Go producers can use `gitea.maximumdirect.net/eric/distributor/pkg/bundle` to build and validate this contract:
+Go producers can use `gitea.maximumdirect.net/eric/distributor/pkg/bundle` to build and validate this contract. See [`pkg/bundle`](../consumers/pkg-bundle.md) for producer workflow guidance.
 
 - `BuildManifest`: builds a manifest from explicit file paths or scan mode.
 - `WriteManifest`: writes `manifest.json`, optionally replacing an existing manifest.
@@ -68,7 +68,7 @@ Go producers can use `gitea.maximumdirect.net/eric/distributor/pkg/bundle` to bu
 - `LoadManifest`, `ParseManifest`, `ValidateManifest`, and `ValidateBundle`: parse and validate local bundles.
 - `FileDigest`, `BundleDigest`, and `ValidateDigest`: digest helpers.
 
-Go producers that submit bundles to `distributor serve` can use `gitea.maximumdirect.net/eric/distributor/pkg/upload`. It builds on `pkg/bundle`, packages valid bundles as gzip-compressed tar uploads, sends bearer authentication, and includes idempotency keys for safe retry behavior. See [HTTP Upload API Contract](http-upload.md).
+Go producers that submit bundles to `distributor serve` can use `gitea.maximumdirect.net/eric/distributor/pkg/upload`. See [Upstream Producer Integration](../consumers/api.md) and [HTTP Upload API Contract](http-upload.md).
 
 CLI producers can use:
 

docs/operations.md

@@ -138,7 +138,7 @@ curl -X POST http://127.0.0.1:8080/upload \
   --data-binary @bundle.tar.gz
 ```
 
-For safe producer retries, include an idempotency key that is stable for the producer operation:
+For safe producer retries, include an idempotency key that is stable for the same producer run and different for each distinct run:
 
 ```sh
 curl -X POST http://127.0.0.1:8080/upload \
@@ -148,20 +148,9 @@ curl -X POST http://127.0.0.1:8080/upload \
   --data-binary @bundle.tar.gz
 ```
 
-Go producer applications can use `pkg/upload` instead of constructing archives and HTTP requests directly. The package sends `Idempotency-Key` on every upload, derives `/upload` from the configured endpoint, and reuses the same key and replayable request body for safe retries:
+Go producer applications can use `pkg/upload` instead of constructing archives and HTTP requests directly. See [Upstream Producer Integration](consumers/api.md) for the copyable producer implementation guide.
 
-```go
+The maintained example client uses the local upload server and reads the token from `DISTRIBUTOR_EXAMPLE_UPLOAD_TOKEN`. It generates an idempotency key by default; set `DISTRIBUTOR_EXAMPLE_UPLOAD_IDEMPOTENCY_KEY` when retrying the same producer run across separate process runs.
-client, err := upload.NewClient(upload.ClientOptions{
-	Endpoint: "http://127.0.0.1:8080",
-	Token:    token,
-})
-result, err := client.UploadBundle(ctx, upload.UploadBundleOptions{
-	Root:           "examples/source-bundle",
-	IdempotencyKey: "producer.run.20260604T120000Z",
-})
-```
-
-The maintained example client uses the local upload server and reads the token from `DISTRIBUTOR_EXAMPLE_UPLOAD_TOKEN`. It generates an idempotency key by default; set `DISTRIBUTOR_EXAMPLE_UPLOAD_IDEMPOTENCY_KEY` when a retry must be stable across separate process runs.
 
 ```sh
 go run ./examples/upload-client

docs/policy/architecture.md

@@ -197,6 +197,7 @@ Use this current layout unless the project has a documented reason to differ:
 
 - `cmd/distributor`: application entrypoint only.
 - `pkg/bundle`: public producer-facing source manifest model, digest logic, parsing, manifest building, complete local bundle writing, and local validation helpers.
+- `pkg/upload`: public producer-facing HTTP upload client built on `pkg/bundle`.
 - `internal/app`: application orchestration and top-level use cases.
 - `internal/cli`: CLI command definitions, flags, argument parsing, and command wiring.
 - `internal/config`: configuration structs, defaults, loading, precedence, and validation.
@@ -323,9 +324,9 @@ Important tests include:
 
 Documentation should follow the project documentation policy. Keep user docs focused on implemented behavior. Put future, planned, or aspirational work only under `docs/roadmap/`.
 
-When changing architecture, config, CLI behavior, adapters, manifest/state contracts, transform behavior, publish behavior, or component contracts, update the relevant docs and examples in the same change.
+When changing architecture, config, CLI behavior, adapters, manifest/state contracts, transform behavior, publish behavior, public package/API behavior, or component contracts, update the relevant docs and examples in the same change.
 
-The source manifest and destination `.distributor.json` schemas should have canonical documentation once implemented. Example configs should be valid and load-tested where practical.
+The source manifest and destination `.distributor.json` schemas should have canonical documentation once implemented. Producer-facing package and API workflows belong under `docs/consumers/`. Example configs should be valid and load-tested where practical.
 
 ## Non-Goals
 

docs/policy/development.md

@@ -23,7 +23,7 @@ Use it with `docs/policy/architecture.md` and `docs/policy/documentation.md`.
 - `internal/transform/markdown`: Markdown-to-HTML transform.
 - `internal/notify`: notification interface and current no-op notifier.
 - `internal/testutil`: shared test fixtures. Production code must not import this package.
-- `docs`: current user, operator, policy, internal, and roadmap documentation.
+- `docs`: current user, operator, consumer, integration, policy, internal, and roadmap documentation.
 - `examples`: copyable example configs and source bundles.
 
 Do not create new top-level package families such as public `pkg/...` packages
@@ -211,5 +211,7 @@ Follow `docs/policy/documentation.md`.
 - Keep `docs/config.md` canonical for user-facing config reference.
 - Keep `docs/cli.md` canonical for command syntax and workflows.
 - Keep `docs/operations.md` canonical for operational and recovery behavior.
+- Keep `docs/consumers/` canonical for public package and consumer API workflows.
+- Keep `docs/integrations/` canonical for external file-format and wire-protocol contracts.
 - Keep `docs/internal/` focused on implemented package contracts.
-- Update docs in the same change as behavior when public behavior, config, CLI, examples, or internal contracts change.
+- Update docs in the same change as behavior when public behavior, public packages/APIs, config, CLI, examples, or internal contracts change.

docs/policy/documentation.md

@@ -2,12 +2,13 @@
 
 ## Purpose
 
-Project documentation must help four audiences:
+Project documentation must help five audiences:
 
 1. users who need to run the application;
 2. administrators/operators who need to configure and operate it;
 3. developers who need to understand and change it safely;
-4. LLM coding agents that need clear scope, boundaries, and invariants.
+4. LLM coding agents that need clear scope, boundaries, and invariants;
+5. developers and LLM coding agents integrating this project from another codebase.
 
 Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
 
@@ -46,7 +47,9 @@ Canonical homes:
 - CLI reference: `docs/cli.md`
 - operations and recovery: `docs/operations.md`
 - troubleshooting: `docs/troubleshooting.md`
+- public API/package consumer guidance: `docs/consumers/`
 - implemented internals: `docs/internal/`
+- external protocol, service, and file-format contracts: `docs/integrations/`
 - future work: `docs/roadmap/`
 - contributor workflow: `docs/policy/development.md`
 - copyable examples: `examples/`
@@ -119,6 +122,15 @@ Recommended:
 - `docs/troubleshooting.md`
 - validated examples under `examples/`
 
+### Project with public packages or consumer APIs
+
+Required:
+- `docs/consumers/api.md`
+- one `docs/consumers/pkg-<name>.md` file per public package, if public packages exist
+
+Recommended:
+- copyable consumer examples under `examples/`, if practical
+
 ## Required Documents
 
 ### README.md
@@ -244,6 +256,33 @@ Each entry should include:
 - safe fix;
 - relevant links.
 
+### docs/consumers/
+
+**Audience:** developers and LLM coding agents integrating this project from another codebase
+
+Required for projects with public packages, SDKs, client APIs, plugin APIs, or other application-facing integration surfaces.
+
+This directory describes how an external codebase should consume the project's public API. It should be task-oriented and copyable where useful. It is not the place for internal implementation details or operator procedures.
+
+`docs/consumers/api.md` should provide the consumer-facing overview and primary implementation workflow. It should include:
+
+1. intended consumer audience and use cases;
+2. required inputs supplied by operators or deployment configuration;
+3. recommended public package or API workflow;
+4. minimal copyable example;
+5. consumer responsibilities and boundaries;
+6. retry, idempotency, or status behavior, if applicable;
+7. links to package-specific docs and canonical integration contracts.
+
+Package-specific docs should be named `pkg-<name>.md` and should include:
+
+1. import path;
+2. intended use cases;
+3. primary types and functions needed by consumers;
+4. minimal examples;
+5. validation, error, retry, and boundary behavior;
+6. links to canonical file-format or wire-protocol contracts.
+
 ### docs/internal/
 
 **Audience:** developers, LLM coding agents
@@ -289,7 +328,7 @@ Roadmap docs should not be confused with current behavior.
 
 Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
 
-This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
+This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses or exposes.
 
 Use one file per integration where useful.
 
@@ -348,6 +387,7 @@ Before merging documentation changes, verify:
 - `docs/policy/architecture.md` describes development principles.
 - Future work appears only under `docs/roadmap/`.
 - User-facing docs avoid unnecessary internals.
+- Consumer-facing docs explain public APIs without duplicating integration contracts.
 - Developer-facing docs preserve boundaries and invariants.
 - Config examples match the schema.
 - CLI examples match real commands and flags.

docs/roadmap/api.md

@@ -0,0 +1,172 @@
+# API Roadmap
+
+This document records planned API work that is not part of the current
+implementation. Current HTTP upload behavior is documented in
+`docs/integrations/http-upload.md` and current producer package usage is
+documented under `docs/consumers/`.
+
+## Pipeline-Scoped HTTP Upload API
+
+Current `http_upload` behavior uses one bearer token to both authenticate a
+producer and select exactly one pipeline. That is simple, but it does not scale
+well for producer applications that generate multiple report types on different
+schedules.
+
+Planned work:
+
+- Separate upload authentication from pipeline routing.
+- Add token records that can authorize one producer/client for one or more
+  upload pipelines.
+- Add a pipeline-scoped upload endpoint:
+
+```text
+POST /v1/pipelines/{pipeline_id}/upload
+```
+
+- Keep the source manifest free of routing, destination, transform, and
+  credential data.
+- Keep `http_upload` source-only. A selected pipeline still owns destination
+  configuration, transforms, links, transfer policy, and publication behavior.
+
+## Proposed Configuration Shape
+
+Move bearer token configuration out of individual pipeline sources and into a
+top-level upload token list:
+
+```yaml
+upload_tokens:
+  - id: weatherreporter-prod
+    token_env: WEATHERREPORTER_UPLOAD_TOKEN
+    allow_pipelines:
+      - weather.morning
+      - weather.weekend
+      - weather.next_6_hours
+      - weather.storm
+      - weather.event
+```
+
+Pipeline sources would continue to use `http_upload`, but would no longer need
+one unique token per pipeline:
+
+```yaml
+pipelines:
+  - id: weather.morning
+    source:
+      backend: http_upload
+    destinations:
+      - id: archive
+        backend: s3
+        bucket: reports
+        prefix: weather/morning/archive
+      - id: latest
+        backend: s3
+        bucket: reports
+        prefix: weather/morning/latest
+        path_mapping:
+          mode: fixed
+```
+
+Per-pipeline upload settings such as `staging_path` and `max_upload_size` should
+remain on the `http_upload` source.
+
+## Authorization Semantics
+
+- Missing, malformed, or unknown bearer tokens should return `401 Unauthorized`.
+- Valid tokens that are not allowed for the requested pipeline should return
+  `403 Forbidden`.
+- Requested pipeline ids must name configured pipelines whose source backend is
+  `http_upload`.
+- Multiple upload tokens may authorize the same pipeline.
+- One upload token may authorize multiple pipelines.
+- Token values must continue to resolve through the process environment or
+  `secrets.directory`, not YAML literal values.
+
+Idempotency records should be scoped by token id, pipeline id, and idempotency
+key. This avoids collisions when multiple authorized producers submit to the
+same pipeline.
+
+## Producer Package Changes
+
+Add `PipelineID` to producer upload options:
+
+```go
+result, err := client.UploadFiles(ctx, upload.UploadFilesOptions{
+	PipelineID:     "weather.morning",
+	ID:             "weather.morning.brentwood",
+	IdempotencyKey: "weather.morning.brentwood.20260607T050000Z",
+	Files: []bundle.BundleFile{
+		{SourcePath: reportPath, Path: "report.md"},
+		{SourcePath: dataPath, Path: "data.json"},
+	},
+})
+```
+
+`pkg/upload` should derive `/v1/pipelines/{pipeline_id}/upload` when
+`PipelineID` is set. Status lookup can continue to use run ids returned by the
+server.
+
+The producer contract should remain:
+
+- token identifies and authenticates the producer/client;
+- `PipelineID` selects the configured distributor workflow;
+- source manifest `id` identifies the logical artifact within that workflow;
+- idempotency key identifies one producer run and retry group.
+
+## Compatibility Plan
+
+Prefer a transition period:
+
+- Keep current `POST /upload` behavior for legacy configs where one token maps
+  to exactly one `http_upload` pipeline.
+- Reject legacy `/upload` routing when a token is authorized for multiple
+  pipelines, because routing would be ambiguous.
+- Keep rejecting `pipeline` and `pipeline_id` query parameters.
+- Document `/v1/pipelines/{pipeline_id}/upload` as the preferred endpoint for
+  new clients.
+
+After the transition period, consider deprecating or removing legacy `/upload`
+if the compatibility burden is no longer useful.
+
+## Implementation Work
+
+- Add `upload_tokens` config structs, defaults, validation, and secret
+  resolution.
+- Update upload token resolution to produce token identities and pipeline
+  allowlists instead of a token-to-single-pipeline map.
+- Add the `/v1/pipelines/{pipeline_id}/upload` HTTP route and pipeline id path
+  validation.
+- Preserve `/healthz` and `/runs/<run-id>` behavior.
+- Pass token identity into upload admission so idempotency can be scoped by
+  token id, pipeline id, and key.
+- Add `PipelineID` to `pkg/upload` upload option structs and endpoint
+  construction.
+- Update configuration, operation, integration, consumer, and troubleshooting
+  docs for implemented behavior.
+
+## Tests
+
+Important tests:
+
+- Config loading and validation for `upload_tokens`.
+- Startup failure for missing, empty, duplicated, or invalid upload token
+  records.
+- `401` for missing or unknown bearer token.
+- `403` for valid token not allowed for requested pipeline.
+- Successful upload to two different pipelines with one token.
+- Successful upload to one pipeline from two different authorized tokens.
+- Idempotency isolation across token ids and pipeline ids.
+- Legacy `/upload` compatibility for one-token-one-pipeline routing.
+- Legacy `/upload` rejection when routing is ambiguous.
+- `pkg/upload` endpoint construction with `PipelineID`.
+- Producer package tests for missing or invalid `PipelineID`.
+
+## Boundaries
+
+- Do not add destination selection to producer manifests.
+- Do not let producers specify destination ids, transforms, links, publish
+  policy, or transfer policy through the upload API.
+- Do not add durable upload status or durable idempotency as part of this work;
+  those remain separate roadmap items.
+- Do not add in-app public exposure policy, TLS, or rate limiting as part of
+  this work; those remain deployment-layer concerns unless a future
+  implementation changes that boundary.

docs/roadmap/implementation.md

@@ -0,0 +1,275 @@
+# Pipeline-Scoped Upload API Implementation Plan
+
+This roadmap is for an LLM coding agent implementing the planned API work in
+`docs/roadmap/api.md`. It describes future work only. Do not update
+current-behavior docs outside `docs/roadmap/` until the corresponding stage is
+implemented.
+
+Before implementation, read:
+
+- `docs/policy/architecture.md`
+- `docs/policy/development.md`
+- `docs/policy/documentation.md`
+- `docs/roadmap/api.md`
+
+## Target Behavior
+
+The final implementation is a breaking v1 HTTP upload API change:
+
+- Upload authentication is configured with top-level `upload_tokens`.
+- Pipeline routing is selected by `POST /v1/pipelines/{pipeline_id}/upload`.
+- Producers must set `PipelineID` in `pkg/upload` upload options.
+- Legacy per-source `source.token_env` is removed.
+- Legacy `POST /upload` no longer accepts uploads.
+- Idempotency is scoped by token id, pipeline id, and idempotency key.
+- `/healthz` and `/runs/<run-id>` continue to work.
+
+The producer contract is:
+
+- token authenticates the producer/client;
+- `PipelineID` selects the configured distributor workflow;
+- source manifest `id` identifies the logical artifact within that workflow;
+- idempotency key identifies one producer run and retry group.
+
+## Stage 1: Config Model And Validation
+
+Goal: make the YAML schema express upload authentication separately from
+pipeline source configuration.
+
+Implementation:
+
+- Add `UploadTokens []UploadToken` to `internal/config.Config` with YAML key
+  `upload_tokens`.
+- Add `UploadToken` with fields:
+  - `ID string` as `id`;
+  - `TokenEnv string` as `token_env`;
+  - `AllowPipelines []string` as `allow_pipelines`.
+- Remove `TokenEnv` from `HTTPUpload`; keep `StagingPath` and
+  `MaxUploadSize`.
+- Keep `http_upload` source defaults for `staging_path` and `max_upload_size`.
+- Update validation:
+  - `upload_tokens` is required when any pipeline uses
+    `source.backend: http_upload`.
+  - `upload_tokens` is invalid when it references no configured upload
+    pipelines.
+  - token `id` is required, slug-like, and unique.
+  - token `token_env` is required.
+  - token `allow_pipelines` is required.
+  - each token's `allow_pipelines` entries are unique.
+  - each allowed pipeline id exists and names a pipeline whose source backend
+    is `http_upload`.
+  - every configured `http_upload` pipeline is allowed by at least one token.
+  - `http_upload` sources no longer require `token_env`.
+- Remove tests and fixtures that expect `source.token_env`.
+- Add config load/validation tests for valid multi-pipeline tokens, multiple
+  tokens for one pipeline, missing token list, duplicate token ids, duplicate
+  allowlist entries, unknown allowed pipeline id, non-upload allowed pipeline
+  id, and upload pipeline not allowed by any token.
+
+Acceptance:
+
+- `go test ./internal/config` passes.
+- YAML containing `source.token_env` fails as an unknown field.
+- YAML using top-level `upload_tokens` and `http_upload` sources without
+  `source.token_env` loads and validates.
+
+## Stage 2: Upload Token Resolution And HTTP Routing
+
+Goal: authenticate by bearer token, authorize by token allowlist, and route by
+URL pipeline id.
+
+Implementation:
+
+- Replace the current token-to-single-pipeline map with resolved upload token
+  records containing:
+  - token id;
+  - resolved token value;
+  - allowed pipeline id set.
+- Resolve token values through the existing config environment resolver so
+  process environment and `secrets.directory` behavior remains consistent.
+- Startup must fail when a token env is missing, empty, or resolves to the same
+  token value as another upload token. Error messages may name token ids and
+  env var names, but must not print token values.
+- Change `uploadHTTPHandler` routes:
+  - keep `GET /healthz`;
+  - keep `GET /runs/<run-id>`;
+  - add `POST /v1/pipelines/{pipeline_id}/upload`;
+  - remove legacy `POST /upload`.
+- Path parsing rules:
+  - match exactly `/v1/pipelines/<pipeline-id>/upload`;
+  - reject missing pipeline id, extra path segments, and query-based
+    `pipeline` or `pipeline_id` routing;
+  - validate requested pipeline id using the same slug-like id policy used for
+    configured pipeline ids.
+- Request handling rules:
+  - missing, malformed, or unknown bearer token returns `401`;
+  - valid token not allowed for requested pipeline returns `403`;
+  - requested pipeline must be configured with `source.backend: http_upload`;
+  - content type and idempotency key validation remain unchanged;
+  - successful requests submit the requested pipeline id and token id to the
+    upload coordinator.
+- Update HTTP handler tests for accepted v1 upload, unauthorized upload,
+  forbidden pipeline, invalid pipeline path, removed `/upload`, invalid
+  content type, invalid idempotency key, and no token leakage.
+
+Acceptance:
+
+- `go test ./internal/app` passes for handler tests touched in this stage.
+- `POST /upload` returns not found or another non-accepting error and does not
+  call `Submit`.
+- `POST /v1/pipelines/{pipeline_id}/upload` routes only when token
+  authorization allows that pipeline.
+
+## Stage 3: Coordinator Idempotency Scope
+
+Goal: prevent idempotency collisions between distinct authorized clients and
+between pipelines.
+
+Implementation:
+
+- Add `TokenID string` to `UploadRequest`.
+- Update idempotency scope to include token id, pipeline id, and key.
+- Preserve existing behavior inside one idempotency scope:
+  - same key and same normalized manifest returns the original accepted run;
+  - same key and different normalized manifest returns conflict;
+  - same key while staging returns retryable conflict.
+- Keep requests without idempotency keys unscoped and always admitted according
+  to queue capacity.
+- Update coordinator tests:
+  - same token, same pipeline, same key returns original run;
+  - same token, same pipeline, same key with changed manifest conflicts;
+  - different token ids can use the same key for the same pipeline without
+    collision;
+  - same token id can use the same key for different pipelines without
+    collision;
+  - pending-key retryable conflict still applies only within the same token and
+    pipeline scope.
+
+Acceptance:
+
+- `go test ./internal/app` passes.
+- Existing queueing, retention, status, and same-pipeline serialization behavior
+  remains unchanged.
+
+## Stage 4: Public `pkg/upload` API
+
+Goal: make producer clients route uploads through the v1 pipeline-scoped API.
+
+Implementation:
+
+- Add `PipelineID string` to `UploadFilesOptions`.
+- Add `PipelineID string` to `UploadBundleOptions`.
+- Require non-empty valid `PipelineID` in both upload methods before local
+  bundle staging, validation, archiving, or HTTP requests.
+- Use the same accepted pipeline id syntax as server config ids: starts with an
+  ASCII letter or digit and then contains ASCII letters, digits, `.`, `_`, or
+  `-`.
+- Build upload URLs as
+  `/v1/pipelines/{pipeline_id}/upload`.
+- Keep `Status(ctx, runID)` unchanged.
+- Update package tests:
+  - missing `PipelineID` fails before local file work or HTTP request;
+  - invalid `PipelineID` fails before HTTP request;
+  - `UploadFiles` and `UploadBundle` post to the v1 route;
+  - retry behavior reuses the same idempotency key and v1 route;
+  - token redaction still works.
+- Update `pkg/upload` package documentation to explain the four-part producer
+  contract: token, `PipelineID`, manifest `ID`, idempotency key.
+
+Acceptance:
+
+- `go test ./pkg/upload ./pkg/bundle` passes.
+- Existing `Status` tests pass without endpoint changes.
+
+## Stage 5: Examples And End-To-End App Coverage
+
+Goal: prove the new server and client API work together across realistic upload
+pipelines.
+
+Implementation:
+
+- Update `examples/http-upload-local.yml` to use top-level `upload_tokens`.
+- Update `examples/upload-client` to require or default a pipeline id and pass
+  it to `pkg/upload`.
+- Update app integration tests:
+  - one token authorized for two upload pipelines can upload to both;
+  - two tokens authorized for one upload pipeline can upload to that pipeline;
+  - a valid token rejected for a disallowed pipeline returns `403`;
+  - removed `/upload` endpoint does not enqueue work;
+  - full upload publishes through the selected pipeline and records the
+    selected pipeline id in status/report output.
+- Update helper config builders in tests to use `upload_tokens`.
+
+Acceptance:
+
+- `go test ./internal/app` passes.
+- Example config loading tests pass.
+- `go run ./examples/upload-client` remains documented as an example that
+  targets a configured pipeline.
+
+## Stage 6: Implemented-Behavior Documentation
+
+Goal: move the feature from roadmap-only language into current-behavior docs
+after the code is implemented.
+
+Implementation:
+
+- Update `docs/config.md`:
+  - document top-level `upload_tokens`;
+  - remove `source.token_env`;
+  - document `http_upload` source fields `staging_path` and
+    `max_upload_size`;
+  - document token allowlist semantics.
+- Update `docs/integrations/http-upload.md`:
+  - replace `POST /upload` with
+    `POST /v1/pipelines/{pipeline_id}/upload`;
+  - document `401` versus `403`;
+  - document idempotency scope by token id and pipeline id.
+- Update `docs/consumers/api.md` and `docs/consumers/pkg-upload.md`:
+  - show `PipelineID` in `UploadFiles` and `UploadBundle`;
+  - explain token authentication versus pipeline routing.
+- Update `docs/operations.md` and `docs/troubleshooting.md` for the new curl
+  path, upload token config, and forbidden-pipeline diagnosis.
+- Update `README.md` only if its producer integration links or summary become
+  stale.
+- Revise `docs/roadmap/api.md` so it no longer presents implemented behavior as
+  future work. Either mark the pipeline-scoped upload API as implemented and
+  leave only deferred ideas, or remove implemented sections.
+
+Acceptance:
+
+- `rg -n "POST /upload|source.token_env|token_env.*http_upload|maps each resolved bearer token to exactly one" README.md docs examples`
+  returns no stale current-behavior references outside historical roadmap
+  context.
+- Documentation outside `docs/roadmap/` describes only implemented behavior.
+
+## Final Verification
+
+Run these commands after all stages are implemented:
+
+```sh
+go test ./internal/config
+go test ./internal/app
+go test ./pkg/bundle ./pkg/upload
+go test ./...
+```
+
+Also run:
+
+```sh
+rg -n "POST /upload|source.token_env|/v1/pipelines|upload_tokens|PipelineID" README.md docs examples internal pkg
+```
+
+Review the output for stale references, missing docs, and tests that still
+expect legacy upload routing.
+
+## Non-Goals
+
+- Do not let producers specify destination ids, destination paths, transforms,
+  links, publish policy, transfer policy, or storage backends through upload
+  requests.
+- Do not add durable upload status, durable idempotency, retry endpoints,
+  cancellation endpoints, long polling, or `UploadAndWait`.
+- Do not add in-app TLS, public exposure policy, or rate limiting.
+- Do not introduce new public package families beyond existing `pkg/bundle` and
+  `pkg/upload`.

pkg/bundle/doc.go

@@ -1,9 +1,104 @@
 // Package bundle provides producer-facing helpers for distributor source
-// bundle manifests.
+// bundles.
 //
-// A source bundle is a local directory containing a manifest.json file and the
+// A source bundle is a local directory containing manifest.json and the files
-// files listed by that manifest. This package owns the public manifest model,
+// listed by that manifest. Producer applications use this package when they
-// digest calculation, path validation, manifest parsing, manifest building,
+// need to generate manifests, validate bundles locally, or write complete
-// local bundle writing, and local bundle validation used by Go producer
+// bundle directories for distributor to discover, upload, or publish.
-// applications.
+//
+// # Bundle Contract
+//
+// The source manifest is the producer-to-distributor contract. It is named by
+// ManifestName, currently "manifest.json", and uses SchemaVersion, currently 1.
+// A Manifest contains:
+//
+//   - SchemaVersion: the source manifest schema version.
+//   - ID: the producer's stable bundle identifier.
+//   - Digest: the canonical digest of the ordered file records.
+//   - Created: an RFC3339 timestamp when marshaled to JSON.
+//   - Files: an ordered list of ManifestFile records.
+//
+// Each ManifestFile records a slash-separated bundle-relative Path, a lowercase
+// sha256:<64 hex> SHA256 digest, and a byte Size. File order is significant for
+// the bundle digest and should be chosen deliberately by the producer. Explicit
+// file lists preserve caller order; scan mode sorts by slash-separated path.
+//
+// # Path Rules
+//
+// Public bundle paths are always slash-separated and relative to the bundle
+// root. ValidateSourcePath rejects empty paths, absolute paths, path traversal,
+// dot segments, backslashes, and reserved manifest/state paths. Source files
+// must be regular files; symlinks and other special files are rejected.
+//
+// BuildManifest with Scan true recursively scans Root, includes regular files
+// including dotfiles, excludes manifest.json and .distributor.json, rejects
+// symlinks, and sorts paths lexically. BuildManifest with Files uses exactly
+// the caller-provided paths and preserves their order. Exactly one selection
+// mode must be used.
+//
+// # Manifest Workflows
+//
+// BuildManifest reads existing files under a local root, calculates each
+// ManifestFile, defaults a zero Created value to the current UTC time, calculates
+// the bundle digest, and validates the result. WriteManifest writes
+// manifest.json and fails if it already exists unless WriteManifestOptions has
+// Overwrite set. LoadManifest reads and parses manifest.json. ParseManifest and
+// MarshalManifest are useful when an application stores or transmits manifest
+// bytes directly; MarshalManifest validates before writing deterministic,
+// indented JSON with a trailing newline.
+//
+// ValidateManifest checks manifest-only semantics, including schema version,
+// required fields, path safety, duplicate file paths, digest syntax, file sizes,
+// and bundle digest. ValidateBundle checks a supplied Manifest against local
+// files under a root, including existence, regular-file type, size, SHA-256
+// digest, path safety, and bundle digest.
+//
+// # Complete Bundle Writing
+//
+// WriteBundle is the most convenient producer workflow when source files live
+// outside the final bundle directory. It copies each BundleFile.SourcePath into
+// a staged bundle at BundleFile.Path, builds and writes a compliant manifest,
+// validates the staged bundle, and promotes it to WriteBundleOptions.Root.
+// Overwrite permits replacement of an existing bundle root using a best-effort
+// sibling temporary and backup strategy.
+//
+// # Digest Helpers
+//
+// FileDigest returns the sha256:<64 hex> digest for file bytes. BundleDigest
+// returns the canonical bundle digest for an ordered []ManifestFile.
+// CanonicalFilePayload returns the JSON payload used by BundleDigest, which is
+// mainly useful for tests and diagnostics. ValidateDigest checks digest syntax.
+//
+// Example: build and write a manifest for files already under a bundle root.
+//
+//	root := "/var/lib/reports/daily-2026-06-06"
+//	manifest, err := bundle.BuildManifest(bundle.BuildOptions{
+//		Root:  root,
+//		ID:    "reports.daily.2026-06-06",
+//		Files: []string{"report.md", "summary.txt"},
+//	})
+//	if err != nil {
+//		return err
+//	}
+//	if err := bundle.WriteManifest(root, manifest, bundle.WriteManifestOptions{}); err != nil {
+//		return err
+//	}
+//	if err := bundle.ValidateBundle(root, manifest); err != nil {
+//		return err
+//	}
+//
+// Example: create a complete bundle from producer-generated files.
+//
+//	manifest, err := bundle.WriteBundle(bundle.WriteBundleOptions{
+//		Root: "/var/lib/distributor-source/daily-2026-06-06",
+//		ID:   "reports.daily.2026-06-06",
+//		Files: []bundle.BundleFile{
+//			{SourcePath: "/tmp/report.md", Path: "report.md"},
+//			{SourcePath: "/tmp/summary.txt", Path: "summary.txt"},
+//		},
+//	})
+//	if err != nil {
+//		return err
+//	}
+//	_ = manifest
 package bundle

pkg/upload/doc.go

@@ -0,0 +1,125 @@
+// Package upload provides producer-facing helpers for submitting distributor
+// source bundles to the HTTP upload API.
+//
+// The package is intended for Go producer applications that already create
+// reports or other Markdown bundle contents and want to hand those bundles to a
+// running distributor server. It builds on pkg/bundle for manifest generation,
+// path validation, digest calculation, local bundle writing, and local bundle
+// validation. It does not expose distributor internals, server configuration,
+// storage backends, destination state, or publish behavior.
+//
+// # Client Construction
+//
+// NewClient creates a Client from ClientOptions. Endpoint is required and must
+// be an http or https distributor server base URL without userinfo, query, or
+// fragment. The client derives /upload for submissions and /runs/<run-id> for
+// status checks. Token is required and is sent as Authorization: Bearer <token>.
+// Token values are redacted from errors produced by the client.
+//
+// HTTPClient is optional. When omitted, the package uses a client with a
+// conservative timeout. Retry is optional; zero values select safe defaults.
+// RetryOptions.MaxAttempts, BaseDelay, and MaxDelay must not be negative, and
+// MaxDelay must be greater than or equal to BaseDelay.
+//
+// # Upload Workflows
+//
+// UploadBundle uploads an existing local source bundle root. The root must
+// contain manifest.json. By default, UploadBundle loads the manifest and
+// validates the complete local bundle with pkg/bundle before making any HTTP
+// request. The generated gzip-compressed tar archive contains manifest.json and
+// exactly the manifest-listed files; unlisted files are not uploaded.
+//
+// UploadFiles is the convenience workflow for producer applications that have
+// generated files but have not yet assembled a bundle directory. It uses
+// pkg/bundle to create a temporary complete bundle from explicit
+// bundle.BundleFile values, validates it by default, archives it, uploads it,
+// and removes temporary files when the call returns. UploadFiles does not write
+// into producer source directories. A zero Created timestamp follows
+// pkg/bundle defaulting behavior.
+//
+// Validation is enabled by default. Set DisableValidation when the application
+// has already performed equivalent local validation and wants to skip the
+// package's validation step. Validate and DisableValidation must not both be
+// true.
+//
+// # Idempotency And Retry
+//
+// Every upload request includes Idempotency-Key. If UploadBundleOptions or
+// UploadFilesOptions provides IdempotencyKey, the client validates and uses
+// that value. Otherwise, it generates a random 128-bit lowercase hexadecimal
+// key once for that upload operation and reuses it for all retries from that
+// call.
+//
+// Generated idempotency keys are useful for retrying transient failures within
+// a single process call. Producers that need cross-process retry safety should
+// provide their own stable key, such as a key derived from the producer job id
+// or report id. Valid keys are non-empty ASCII strings up to 128 bytes using
+// letters, digits, '.', '_', '-', and ':'.
+//
+// The client retries only safe cases: 503 Service Unavailable, temporary
+// network errors, and ambiguous mid-upload failures. Retries use the same
+// idempotency key and replayable gzip archive body. The client does not retry
+// 400, 401, 409, 413, 415, or any response after 202 Accepted. Context
+// cancellation is honored before each attempt and while waiting between
+// retries.
+//
+// # Results And Errors
+//
+// Result represents upload admission. A successful UploadBundle or UploadFiles
+// call means the server accepted the upload and returned a run id; it does not
+// mean the asynchronous distribution run has finished successfully.
+//
+// Status fetches the current server status for a run id and returns RunStatus.
+// This is a separate polling helper; upload calls do not wait for publication
+// completion.
+//
+// Non-2xx upload and status responses return *HTTPError when the server status
+// can be represented as an HTTP failure. HTTPError includes the numeric status
+// code, HTTP status string, response message, and server retryable flag when
+// present. A 409 Conflict response is returned as *IdempotencyConflictError,
+// which wraps HTTPError and can be detected with errors.As.
+//
+// Example: upload producer files with a stable idempotency key.
+//
+//	ctx := context.Background()
+//	client, err := upload.NewClient(upload.ClientOptions{
+//		Endpoint: "https://distributor.example.com",
+//		Token:    os.Getenv("DISTRIBUTOR_UPLOAD_TOKEN"),
+//	})
+//	if err != nil {
+//		return err
+//	}
+//
+//	result, err := client.UploadFiles(ctx, upload.UploadFilesOptions{
+//		ID:             "reports.daily.2026-06-06",
+//		IdempotencyKey: "reports.daily.2026-06-06",
+//		Files: []bundle.BundleFile{
+//			{SourcePath: "/tmp/report.md", Path: "report.md"},
+//			{SourcePath: "/tmp/summary.txt", Path: "summary.txt"},
+//		},
+//	})
+//	if err != nil {
+//		var conflict *upload.IdempotencyConflictError
+//		if errors.As(err, &conflict) {
+//			return fmt.Errorf("upload conflicts with an earlier different bundle: %w", err)
+//		}
+//		return err
+//	}
+//
+//	status, err := client.Status(ctx, result.RunID)
+//	if err != nil {
+//		return err
+//	}
+//	_ = status
+//
+// Example: upload an existing bundle root.
+//
+//	result, err := client.UploadBundle(ctx, upload.UploadBundleOptions{
+//		Root:           "/var/lib/reports/daily-2026-06-06",
+//		IdempotencyKey: "reports.daily.2026-06-06",
+//	})
+//	if err != nil {
+//		return err
+//	}
+//	_ = result
+package upload