docs: describe the remote publish client and status codes

Author: ken-matsui

docs/architecture.md

@@ -55,6 +55,7 @@ crates/
   cabin-registry-file/ local file-registry layout, atomic writes, lock
   cabin-index-http/  sparse HTTP index client (read-only)
   cabin-credentials/ registry token storage (credentials.toml, -Z remote-registry)
+  cabin-registry-api/ remote registry API client (publish / yank, -Z remote-registry)
   cabin-vendor/      typed VendorPlan + file-registry materialiser
   cabin-test/        test-target plan + sequential runner
   cabin-explain/     typed model for `cabin tree` / `cabin explain`
@@ -338,6 +339,25 @@ normalized index origins, plus the `CABIN_REGISTRY_TOKEN` environment override a
   surfacing a warning (not an error) for an existing group/world-readable file;
 - not perform HTTP; the client crates receive tokens as typed values from the orchestration layer.
 
+### `cabin-registry-api`
+
+Owns the typed HTTP client for the experimental remote-registry *mutations*
+([`remote-registry.md`](remote-registry.md)): `PUT /api/v1/packages/<name>/<version>` with the
+crates.io-style length-prefixed metadata + archive frame, and
+`PATCH /api/v1/packages/<name>/<version>/yank`.  Requests target the API origin a registry's
+`config.json` declares (`api`), carry the caller-supplied bearer token, and map the protocol's
+status codes (`200` no-op, `201` created, `400`, `401`, `403`, `404`, `409`) plus the
+`{"errors":[{"detail":"..."}]}` envelope into typed errors, degrading to the raw status when the
+envelope is malformed.  The crate must:
+
+- not stage, validate, or lint packages - it frames and ships bytes produced by `cabin-package` /
+  `cabin-publish`;
+- not implement read routes; `config.json`, package metadata, and artifact downloads stay in
+  `cabin-index-http`;
+- not resolve credentials itself - it receives an optional typed token from the orchestration
+  layer, refuses cleartext `http` beyond loopback hosts, and never follows redirects;
+- never let token bytes surface through errors or `Debug` output.
+
 ### `cabin-port`
 
 Owns the foundation-port recipe layer: parsing `port.toml`, the checksum-addressed port cache, and
@@ -363,7 +383,10 @@ deps in its validator and `cabin-publish` never archives them.  See
 
 Owns publish-workflow orchestration.  Combines `cabin-package`'s [`stage`] entry point with
 `cabin-registry-file`'s atomic writers to publish a single-package source tree into a local file
-registry.  The crate must:
+registry.  The experimental remote publish path (behind `-Z remote-registry`) reuses the same
+staging step and the shared lint seam (`staged_lint_warnings`) with a baseline fetched over the
+sparse HTTP read path; its transport lives in `cabin-registry-api` and its orchestration in
+`cabin`.  The crate must:
 
 - not implement HTTP / sparse / OCI publish;
 - not implement server-side functionality;
@@ -1315,8 +1338,9 @@ if the recorded arrays differ from the active policy.  `cabin metadata` adds two
 
 Local override policy never enters published artifacts: `cabin-package` rejects manifests with a
 non-empty `[patch]` table; `.cabin/config.toml` (which carries config patches + source replacement)
-is already in `EXCLUDED_DIR_NAMES`.  Git sources, vendoring, registry authentication, HTTP publish,
-new registry protocols, and registry-server work all remain deferred.
+is already in `EXCLUDED_DIR_NAMES`.  Git sources and registry-server work remain deferred; the
+authenticated remote-registry client - reads and publish - is an experimental track behind
+`-Z remote-registry` ([`remote-registry.md`](remote-registry.md)).
 
 Full protocol in [`patch-overrides.md`](patch-overrides.md).
 
@@ -1453,10 +1477,10 @@ The following are *not* part of this repository today:
   [`registry-design.md`](registry-design.md).  Source registries are local file directories or
   sparse HTTP today.
 - **No non-local registry control plane.** Every command that needs an index expects `--index-path
-  <dir>` or `--index-url <url>`.  There is no default remote registry and no package upload over
-  the network.  (An experimental remote-registry *client* is being built behind
-  `-Z remote-registry` - protocol, `cabin login` / `cabin logout`, and authenticated reads; see
-  [`remote-registry.md`](remote-registry.md).)
+  <dir>` or `--index-url <url>`.  There is no default remote registry, and package upload over the
+  network exists only behind the experimental `-Z remote-registry` client - protocol,
+  `cabin login` / `cabin logout`, authenticated reads, and `cabin publish` against an HTTP index
+  source; see [`remote-registry.md`](remote-registry.md).
 - **No account / ownership workflows.** Ownership, signing, package yanking, and restricted package
   access are out of scope.
 - **No administrative policy surfaces.**

docs/package-format.md

@@ -12,7 +12,9 @@
 
 `cabin publish --dry-run` adds a "no registry was modified" report.  The dry-run path is
 **local-only**: nothing is uploaded, no registry mutation happens, and `cabin publish` without
-`--dry-run` exits with a clear error unless a local `--registry-dir` is provided.
+`--dry-run` exits with a clear error unless a local `--registry-dir` is provided or, behind
+`-Z remote-registry`, an HTTP index source is in effect
+([`remote-registry.md`](remote-registry.md)).
 
 ## Source archive format
 
@@ -184,8 +186,11 @@ cabin publish --dry-run \
   [--format human|json]
 ```
 
-Same defaults.  `cabin publish` without `--dry-run` and without `--registry-dir` exits with `actual
-publishing requires --registry-dir, or use --dry-run`.
+Same defaults.  `cabin publish` without `--dry-run`, without `--registry-dir`, and without an
+effective HTTP index source exits with a clear error naming both options.  Behind
+`-Z remote-registry`, an HTTP index source (`--index-url` or the `[registry] index-url` config
+setting) publishes the same staged bytes remotely; see
+[`remote-registry.md`](remote-registry.md).
 
 ## Output layout
 

docs/registry-design.md

@@ -100,6 +100,8 @@ domain model:
 - `cabin-registry-file` owns the local mutable file-registry layout;
 - `cabin-index-http` performs read-only HTTP fetches and hands the
   retrieved JSON to the same typed index model;
+- `cabin-registry-api` owns the experimental authenticated mutation
+  routes (publish / yank, behind `-Z remote-registry`);
 - `cabin-artifact` verifies, caches, and extracts source archives
   without knowing whether bytes came from a file or HTTP.
 
@@ -123,7 +125,14 @@ track:
   issued on the registry web UI at `<origin>/me`;
 - publishing uses `PUT /api/v1/packages/<name>/<version>` with a
   length-prefixed metadata + archive frame, and yanking uses
-  `PATCH /api/v1/packages/<name>/<version>/yank`.
+  `PATCH /api/v1/packages/<name>/<version>/yank`;
+- remote `cabin publish` (an HTTP index source without
+  `--registry-dir`) reuses the local staging pipeline byte-for-byte:
+  the same validation, the same publish lints, and the same
+  deterministic archive plus canonical per-version metadata document
+  as `cabin publish --registry-dir` - only the final write differs,
+  going through the typed `cabin-registry-api` client to the API
+  origin the registry's `config.json` declares.
 
 The registry *service* itself - accounts, token issuance, storage -
 remains outside this repository.

docs/remote-registry.md

@@ -10,10 +10,12 @@ itself - accounts, token issuance, hosted storage - is not part of this reposito
 [`registry-design.md`](registry-design.md).
 
 Client status today: the [`config.json` fields](#registry-configuration) below are recognized
-behind the flag (presence without `-Z remote-registry` fails the index load), and client-side token
+behind the flag (presence without `-Z remote-registry` fails the index load), client-side token
 handling is implemented - `cabin login` / `cabin logout` plus
-[authenticated reads](#client-side-token-handling).  The publish / yank commands land incrementally
-on the same gate.
+[authenticated reads](#client-side-token-handling) - and so is
+[publishing](#publishing-from-the-client) (`cabin publish` against an HTTP index source).  The
+yank *route* has a typed client (`cabin-registry-api`), but a `cabin yank` command has not landed
+yet.
 
 ## Registry configuration
 
@@ -34,7 +36,7 @@ A remote registry serves the same registry-root layout as the sparse HTTP index
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `auth-required` | bool | `false` | When `true`, **every** request to this registry - including `config.json` itself, package metadata, and artifact downloads - must carry `Authorization: Bearer <token>`. |
-| `api` | string | absent | Absolute base URL of the registry web/API origin, e.g. `"https://dev-registry.cabinpkg.com"`.  Non-`http(s)` schemes and URLs with `userinfo` credentials are rejected, mirroring the index-URL hygiene of the sparse HTTP client.  When absent, the API origin defaults to the index origin. |
+| `api` | string | absent | Absolute base URL of the registry web/API origin, e.g. `"https://dev-registry.cabinpkg.com"`.  Non-`http(s)` schemes and URLs with `userinfo` credentials are rejected, mirroring the index-URL hygiene of the sparse HTTP client.  The read routes never consult it.  When absent, `cabin publish` fails with an error naming the field: mutation requests are only ever sent to an explicitly declared API origin. |
 
 Both index parsers (the local `--index-path` loader and the sparse HTTP client) parse the fields
 unconditionally, but *presence* of either field without `-Z remote-registry` fails the index load
@@ -157,7 +159,43 @@ Server-side behavior is part of the contract:
 - **Idempotency.**  Re-publishing a version with byte-identical metadata and archive succeeds with
   `200` and body `{"ok":true,"no_op":true}`.  Publishing the same version with *different* bytes is
   rejected with `409`.
-- A first-time publish succeeds with `200` and body `{"ok":true}`.
+- A first-time publish succeeds with `201` and body `{"ok":true}`.
+
+### Publishing from the client
+
+`cabin publish` targets a remote registry when the effective index source is an HTTP URL
+(`--index-url`, or the `[registry] index-url` setting in [`config.md`](config.md#registry)) and no
+`--registry-dir` is given.  Without `-Z remote-registry` that combination fails with the standard
+experimental-feature error.  The flow is log in once, publish, then resolve like any consumer:
+
+```console
+$ echo "$TOKEN" | cabin -Z remote-registry login --index-url https://dev-registry.cabinpkg.com
+visit https://dev-registry.cabinpkg.com/me to create a token
+       Login token for `https://dev-registry.cabinpkg.com` saved
+$ cabin -Z remote-registry publish --manifest-path fmt/cabin.toml \
+    --index-url https://dev-registry.cabinpkg.com
+Published fmt 10.2.1 to https://dev-registry.cabinpkg.com
+  checksum: sha256:...
+$ cabin -Z remote-registry resolve --manifest-path app/cabin.toml \
+    --index-url https://dev-registry.cabinpkg.com
+```
+
+Client-side behavior:
+
+- The staging pipeline is the *same* one `cabin package` and the local
+  `cabin publish --registry-dir` run - same validation, same publish lints
+  ([`package-format.md`](package-format.md)), same deterministic archive and canonical per-version
+  metadata document.  The uploaded bytes are byte-identical to what `cabin package` writes into
+  `dist/` for the same source tree.
+- `config.json` (which supplies the [`api`](#registry-configuration) origin) and the lint baseline
+  ride the authenticated read path; the upload carries the same bearer token to the API origin,
+  under the same https-or-loopback cleartext rule.
+- On `201` the client reports the published name, version, and checksum.  On `200` it reports that
+  byte-identical bytes were already published and exits successfully - the same "re-running with
+  identical input succeeds" semantics as the local flows.  On `409` it explains that the version
+  exists with different bytes and that published versions are immutable.
+- `--dry-run` stays entirely local: it stages into the output directory (default `dist/`) and
+  never opens a connection.
 
 ## Yank
 
@@ -179,6 +217,8 @@ succeeds with `200` and body `{"ok":true}`.
 
 | Code | Meaning |
 | --- | --- |
+| `200` | Success without a state change: an idempotent no-op (byte-identical re-publish, or a yank set to the state the version already has). |
+| `201` | Publish of a version that did not exist before. |
 | `400` | Malformed request: bad framing, invalid metadata, or an invalid JSON body. |
 | `401` | No token or an invalid token (never reveals whether the package exists). |
 | `403` | Valid token, but the scope the route requires is missing. |