Add JSON output to cog push

architecture/06-cli.md

@@ -14,7 +14,7 @@ The Cog CLI is a Go binary that provides commands for the full model lifecycle:
 | `cog exec`       | Run arbitrary commands in a container |
 | `cog serve`      | Start HTTP server in a container      |
 | `cog playground` | Open a local UI for a model API       |
-| `cog push`       | Deploy to Replicate                   |
+| `cog push`       | Publish to an OCI registry            |
 | `cog login`      | Authenticate with Replicate           |
 
 ## Development Commands
@@ -146,21 +146,19 @@ Key flags:
 
 ### cog push
 
-**Job**: Build and push to Replicate.
+**Job**: Build and publish an image or model bundle to an OCI registry.
 
 ```bash
-cog push r8.im/username/model-name
+cog push registry.example.com/username/model-name:v1
 ```
 
-What happens:
+The `image` or `model` field in `cog.yaml` selects the artifact format. A positional target changes the destination without changing that format. Image projects publish one container image. Bundle projects publish an OCI image index containing the model image and any managed weight manifests.
 
-1. Builds image (like `cog build`)
-2. Pushes to Replicate's registry
-3. Registers model with Replicate API
+Pushes attempt to resolve the published artifacts to digest-pinned references, which the normal terminal output renders as a tree. `--json` makes digest resolution mandatory and emits one versioned document to stdout after the push and registry-provider post-processing succeed; progress and diagnostics remain on stderr. This lets automation consume immutable references without hiding a long-running push's live output.
 
-The image tag must be a Replicate model reference (`r8.im/owner/name`).
+Registry-specific authentication, diagnostics, and post-push work sit behind the provider boundary. Replicate is one provider, not a requirement of the push path.
 
-**Code**: `pkg/cli/push.go`, `pkg/web/`
+**Code**: `pkg/cli/` owns the command and output contract; `pkg/model/` owns image and bundle publication; `pkg/registry/` and `pkg/provider/` own registry operations and provider-specific behavior.
 
 ---
 

docs/cli.md

@@ -220,25 +220,36 @@ cog playground [flags]
 
 ## `cog push`
 
-Build a Docker image from cog.yaml and push it to a container registry.
+Build from cog.yaml and push to an OCI-compliant registry. Run 'cog login'
+first when pushing to Replicate's registry (r8.im).
 
-Cog can push to any OCI-compliant registry. When pushing to Replicate's
-registry (r8.im), run 'cog login' first to authenticate.
+TARGET overrides the configured destination and all COG_MODEL\* environment
+variables. It doesn't change the project format: projects configured with
+'image' push an image, while projects configured with 'model' push an OCI
+bundle. Push targets must use tags, not digests. Untagged image targets use
+Docker's default 'latest' tag; untagged bundle targets get a timestamp tag.
+
+With --json, Cog writes one versioned JSON result to stdout after the entire
+push succeeds. Progress, warnings, and diagnostics continue on stderr. Every
+reference in the result is digest-pinned.
 
 ```
-cog push [IMAGE] [flags]
+cog push [TARGET] [flags]
 ```
 
 **Examples**
 
 ```
-  # Push to Replicate
+  # Push an image to Replicate
   cog push r8.im/your-username/my-model
 
-  # Push to any OCI registry
+  # Push an image to any OCI registry
   cog push registry.example.com/your-username/model-name
 
-  # Push with model weights in a separate layer (Replicate only)
+  # Push a bundle project and print its immutable references as JSON
+  cog push registry.example.com/your-username/model-name:v1 --json
+
+  # Push with model weights in a separate image layer (Replicate only)
   cog push r8.im/your-username/my-model --separate-weights
 ```
 
@@ -247,6 +258,7 @@ cog push [IMAGE] [flags]
 ```
   -f, --file string                  The name of the config file. (default "cog.yaml")
   -h, --help                         help for push
+      --json                         Output the pushed references as JSON
       --no-cache                     Do not use cache when building the image
       --openapi-schema string        Load OpenAPI schema from a file
       --progress string              Set type of build progress output, 'auto' (default), 'tty', 'plain', or 'quiet' (default "auto")

docs/deploy.md

@@ -22,6 +22,83 @@ cog build -t my-model
 The image contains your model code, dependencies, the Cog runtime, and everything in between.
 It serves an HTTP server on port 5000 when run.
 
+## Push to a registry
+
+`cog push` builds the project and publishes it to an OCI-compliant registry:
+
+```console
+cog push registry.example.com/acme/my-model:v1
+```
+
+The project configuration decides what Cog publishes. A project with `image` in
+`cog.yaml` publishes a container image. A project with `model` publishes an OCI
+bundle containing the image and any managed weights. Passing a target doesn't
+switch between these formats.
+
+The positional target is optional when `image` or `model` already supplies a
+destination. When present, it overrides that configured destination and every
+`COG_MODEL*` environment variable. The target must be tag-addressable -- Cog
+rejects digest-pinned targets. An untagged image target uses Docker's `latest`
+tag, while an untagged bundle target gets a timestamp tag generated by Cog.
+
+For a bundle with managed weights, use the same repository where `cog weights
+import` published the weight manifests. The model tag may differ. If the
+repository doesn't contain every required weight manifest, Cog fails before
+pushing the image and tells you to run `cog weights import` for that repository.
+
+Without `--json`, a successful push prints the published references as a
+human-readable tree on stderr.
+
+### Machine-readable output
+
+Use `--json` when another program needs the immutable references produced by a
+push. For example, this pushes a bundle and prints its model, image, and managed
+weight references:
+
+```console
+cog push registry.example.com/acme/my-model:v1 --json
+```
+
+Version 1 output for a bundle with managed weights has this shape:
+
+```json
+{
+  "version": 1,
+  "model": "registry.example.com/acme/my-model@sha256:1111111111111111111111111111111111111111111111111111111111111111",
+  "image": "registry.example.com/acme/my-model@sha256:2222222222222222222222222222222222222222222222222222222222222222",
+  "weights": [
+    {
+      "name": "transformer",
+      "reference": "registry.example.com/acme/my-model@sha256:3333333333333333333333333333333333333333333333333333333333333333"
+    }
+  ]
+}
+```
+
+The version 1 fields are:
+
+- `version`: Always `1`.
+- `image`: Always present. The value is the published image's complete,
+  digest-pinned reference.
+- `model`: Present only for bundle pushes. The value is the complete,
+  digest-pinned bundle reference.
+- `weights`: Present only when the bundle has managed weights. Each entry has a
+  `name` and a complete, digest-pinned `reference`. Entries keep their
+  `cog.yaml` order.
+
+JSON whitespace and object key order aren't part of the contract.
+
+Stdout stays empty while the command runs. Build and upload progress, warnings,
+diagnostics, and registry-provider messages go to stderr. After the push and
+provider post-processing both succeed, stdout receives exactly one JSON
+document. JSON mode suppresses the human-readable reference tree.
+
+Any build, push, digest-resolution, provider, or serialization failure exits
+nonzero without writing a JSON document to stdout. JSON mode requires Cog to
+resolve every published reference to an immutable digest, so it can report
+failure even when an image was pushed successfully. Non-JSON image pushes keep
+their existing fallback when a registry can't resolve the pushed image's digest.
+
 ## Run the model
 
 You have several options for running a built image.

docs/environment.md

@@ -137,7 +137,7 @@ Overrides the full model reference used by commands that need a model destinatio
 
 The value is parsed as a complete model reference (`registry/repo`, `registry/repo:tag`, or `registry/repo@digest`). If no tag is supplied, Cog generates a timestamp tag.
 
-When `COG_MODEL` is set, it takes precedence over `COG_MODEL_REGISTRY`, `COG_MODEL_REPO`, and `COG_MODEL_TAG`.
+When `COG_MODEL` is set, it takes precedence over `COG_MODEL_REGISTRY`, `COG_MODEL_REPO`, and `COG_MODEL_TAG`. A positional target passed to `cog push` takes precedence over all four variables. Although commands that inspect existing artifacts accept a digest, `cog push` rejects digest-pinned destinations because a push requires a tag.
 
 ```console
 $ COG_MODEL=r8.im/acme/my-model:v1 cog push