lean-runtime 1.0.0__tar.gz → 2.0.0__tar.gz

{lean_runtime-1.0.0 → lean_runtime-2.0.0}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 2.0.0
+
+Version 2 gives the public interface the language used by Lean users rather
+than the language of its storage implementation. The environment format stays
+compatible; command names, Python names, configuration, events, and public
+metadata intentionally change without aliases.
+
+### Public terminology
+
+- Environment libraries replace OCI caches in ordinary configuration and docs.
+- Downloadable environments replace prebuilt artifacts.
+- Portable copies replace OCI bundles.
+- Publisher verification replaces signature-policy terminology.
+- Cleanup and storage replace garbage-collection and blob terminology.
+- Ready-to-run programs replace execution-capsule and container terminology.
+
+### Main migrations
+
+- `Runtime(caches=..., prebuilt=...)` becomes
+  `Runtime(libraries=..., availability=...)`.
+- `resolve`, `ensure`, and named `open` become `prepare`, `open_exact`, and
+  `environment` in the explicit Python API.
+- `export_environment` and `import_environment` become `save_portable_copy`
+  and `open_portable_copy`.
+- CLI workflows use `prepare`, `open`, `download`, `build-and-publish`,
+  `save-copy`, `open-copy`, `compare`, `storage`, and `clean`.
+- Environment libraries accept friendly `ghcr.io/owner/name` locations; the
+  OCI transport remains an advanced implementation detail.
+- Ready-to-run programs can be created, verified, copied, downloaded from a
+  program library, published for multiple kinds of computers, and interrupted
+  during interactive execution.
+
 ## 1.0.0
 
 Lean Runtime v1 establishes the concise `lean-run` and `lean.setup()` workflows while making

{lean_runtime-1.0.0/lean_runtime.egg-info → lean_runtime-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 1.0.0
+Version: 2.0.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -38,8 +38,9 @@ Dynamic: license-file
 Run Lean proofs from Python or a single `.lean` file—without creating a throwaway
 Lake project or rebuilding the same dependencies on every machine.
 
-Lean Runtime discovers or resolves the environment, checks a global OCI cache,
-and returns structured Lean results with exact provenance.
+Lean Runtime discovers the exact Lean environment a project needs and reuses a
+downloadable copy when one is available. It returns structured Lean results
+with a record of the toolchain and dependencies that were actually used.
 
 > **Status:** V1 beta. The local backend runs trusted Lean, Lake, and package code;
 > it is an orchestration boundary, not a security sandbox.
@@ -136,7 +137,7 @@ compare, and measure the same exact contexts:
 
 ```bash
 lean-runtime verify research-stack --offline
-lean-runtime diff previous.lock.json environment.lock.json
+lean-runtime compare previous.lock.json environment.lock.json
 lean-runtime profile research-stack Main.lean --repeat 5
 lean-runtime matrix compatibility.toml Main.lean
 ```
@@ -150,13 +151,34 @@ Friendly references remain exact: use `mathlib@VERSION`,
 `github:owner/repository@REVISION` form. Bare floating package names are never
 accepted.
 
-## Under the hood
+## Share environments
+
+A **project** is your ordinary Lake repository. Its **environment** is the exact
+Lean version, dependencies, and build configuration needed to use it. A
+**downloadable environment** is a ready-to-use copy that collaborators and CI
+can fetch instead of rebuilding Mathlib.
+
+Environment libraries may be public or private. For example:
+
+```bash
+lean-runtime --library ghcr.io/owner/lean-environments download environment.lock.json
+lean-runtime build-and-publish environment.lock.json \
+  --publish-to ghcr.io/owner/lean-environments
+```
+
+For an already-built executable, Lean Runtime can also create a verified
+**ready-to-run program**. It opens without rebuilding the project, can be saved
+as a portable copy, and can be shared through a public or private program
+library. See [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob/main/docs/ready-programs.md).
+
+## Technical details
 
 The simple API is backed by exact Git commits and trees, Lake-resolved locks,
 platform-aware content-addressed environments, atomic cross-process builds,
-transparent OCI cache reuse, replayable provenance, verification, and signed
-attestations. Advanced users can access all of it through `lean_runtime.Runtime`
-and the `lean-runtime` operations CLI.
+downloadable environment reuse, replayable provenance, verification, and trusted
+publishers. The libraries use OCI-compatible storage internally, but users do
+not need Docker or container concepts. Advanced protocol details remain in the
+architecture documentation.
 
 ## Documentation
 
@@ -165,7 +187,8 @@ and the `lean-runtime` operations CLI.
 - [`lean-run` and operations CLI](https://github.com/alerad/lean-runtime/blob/main/docs/cli.md)
 - [Managed environments](https://github.com/alerad/lean-runtime/blob/main/docs/environments.md)
 - [Local Lake projects](https://github.com/alerad/lean-runtime/blob/main/docs/local-projects.md)
-- [Environment bundles and OCI caches](https://github.com/alerad/lean-runtime/blob/main/docs/bundles.md)
+- [Portable copies and environment libraries](https://github.com/alerad/lean-runtime/blob/main/docs/portable-copies.md)
+- [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob/main/docs/ready-programs.md)
 - [Architecture](https://github.com/alerad/lean-runtime/blob/main/docs/architecture.md)
 - [Trust and limitations](https://github.com/alerad/lean-runtime/blob/main/docs/trust-and-limitations.md)
 - [V1 release case study](https://github.com/alerad/lean-runtime/blob/main/docs/case-study-v1.md)

{lean_runtime-1.0.0 → lean_runtime-2.0.0}/README.md

@@ -3,8 +3,9 @@
 Run Lean proofs from Python or a single `.lean` file—without creating a throwaway
 Lake project or rebuilding the same dependencies on every machine.
 
-Lean Runtime discovers or resolves the environment, checks a global OCI cache,
-and returns structured Lean results with exact provenance.
+Lean Runtime discovers the exact Lean environment a project needs and reuses a
+downloadable copy when one is available. It returns structured Lean results
+with a record of the toolchain and dependencies that were actually used.
 
 > **Status:** V1 beta. The local backend runs trusted Lean, Lake, and package code;
 > it is an orchestration boundary, not a security sandbox.
@@ -101,7 +102,7 @@ compare, and measure the same exact contexts:
 
 ```bash
 lean-runtime verify research-stack --offline
-lean-runtime diff previous.lock.json environment.lock.json
+lean-runtime compare previous.lock.json environment.lock.json
 lean-runtime profile research-stack Main.lean --repeat 5
 lean-runtime matrix compatibility.toml Main.lean
 ```
@@ -115,13 +116,34 @@ Friendly references remain exact: use `mathlib@VERSION`,
 `github:owner/repository@REVISION` form. Bare floating package names are never
 accepted.
 
-## Under the hood
+## Share environments
+
+A **project** is your ordinary Lake repository. Its **environment** is the exact
+Lean version, dependencies, and build configuration needed to use it. A
+**downloadable environment** is a ready-to-use copy that collaborators and CI
+can fetch instead of rebuilding Mathlib.
+
+Environment libraries may be public or private. For example:
+
+```bash
+lean-runtime --library ghcr.io/owner/lean-environments download environment.lock.json
+lean-runtime build-and-publish environment.lock.json \
+  --publish-to ghcr.io/owner/lean-environments
+```
+
+For an already-built executable, Lean Runtime can also create a verified
+**ready-to-run program**. It opens without rebuilding the project, can be saved
+as a portable copy, and can be shared through a public or private program
+library. See [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob/main/docs/ready-programs.md).
+
+## Technical details
 
 The simple API is backed by exact Git commits and trees, Lake-resolved locks,
 platform-aware content-addressed environments, atomic cross-process builds,
-transparent OCI cache reuse, replayable provenance, verification, and signed
-attestations. Advanced users can access all of it through `lean_runtime.Runtime`
-and the `lean-runtime` operations CLI.
+downloadable environment reuse, replayable provenance, verification, and trusted
+publishers. The libraries use OCI-compatible storage internally, but users do
+not need Docker or container concepts. Advanced protocol details remain in the
+architecture documentation.
 
 ## Documentation
 
@@ -130,7 +152,8 @@ and the `lean-runtime` operations CLI.
 - [`lean-run` and operations CLI](https://github.com/alerad/lean-runtime/blob/main/docs/cli.md)
 - [Managed environments](https://github.com/alerad/lean-runtime/blob/main/docs/environments.md)
 - [Local Lake projects](https://github.com/alerad/lean-runtime/blob/main/docs/local-projects.md)
-- [Environment bundles and OCI caches](https://github.com/alerad/lean-runtime/blob/main/docs/bundles.md)
+- [Portable copies and environment libraries](https://github.com/alerad/lean-runtime/blob/main/docs/portable-copies.md)
+- [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob/main/docs/ready-programs.md)
 - [Architecture](https://github.com/alerad/lean-runtime/blob/main/docs/architecture.md)
 - [Trust and limitations](https://github.com/alerad/lean-runtime/blob/main/docs/trust-and-limitations.md)
 - [V1 release case study](https://github.com/alerad/lean-runtime/blob/main/docs/case-study-v1.md)

{lean_runtime-1.0.0 → lean_runtime-2.0.0}/docs/architecture.md

@@ -1,5 +1,16 @@
 # Architecture
 
+## Ready-to-run programs
+
+A ready-to-run program is the small result you can open immediately, without
+rebuilding its Lean project first. Lean Runtime verifies its files every time it
+is opened and records the exact source revision and, when known, the environment
+that produced it. Use one for fast service execution. Open the full environment
+when you need kernel replay, custom compilation, or an independent rebuild.
+
+Program libraries and portable program copies use OCI-compatible storage under
+the hood. That transport detail does not appear in the ordinary Python API or CLI.
+
 ## Dominant abstraction
 
 Lean Runtime is an environment compiler:

{lean_runtime-1.0.0 → lean_runtime-2.0.0}/docs/case-study-v1.md

@@ -23,7 +23,7 @@ The resulting JSON records:
 - offline verification and captured-execution replay.
 
 The harness deliberately starts from an already prepared environment. Measure cold source
-preparation separately and state whether local, Lake, and OCI caches were empty. Do not combine
+preparation separately and state whether local, Lake, and OCI libraries were empty. Do not combine
 cold source builds and warm execution into one headline number.
 
 ## Clean-wheel acceptance

{lean_runtime-1.0.0 → lean_runtime-2.0.0}/docs/cli.md

@@ -47,31 +47,31 @@ lean-runtime check Main.lean \
 ## Environment workflow
 
 ```bash
-lean-runtime resolve environment.toml --output environment.lock.json
-lean-runtime ensure environment.lock.json --name research-stack
-lean-runtime --cache oci://ghcr.io/owner/cache pull environment.lock.json
-lean-runtime export research-stack --output research-stack.oci.tar.gz
-lean-runtime --home /tmp/fresh import research-stack.oci.tar.gz --name research-stack
-lean-runtime build-and-push environment.lock.json --push-to oci://ghcr.io/owner/cache
+lean-runtime prepare environment.toml --output environment.lock.json
+lean-runtime open environment.lock.json --name research-stack
+lean-runtime --library ghcr.io/owner/lean-environments download environment.lock.json
+lean-runtime save-copy research-stack --output research-stack.lean-environment
+lean-runtime --home /tmp/fresh open-copy research-stack.lean-environment --name research-stack
+lean-runtime build-and-publish environment.lock.json --publish-to ghcr.io/owner/lean-environments
 lean-runtime check research-stack Main.lean --json
 lean-runtime inspect research-stack --packages
-lean-runtime env-list
-lean-runtime cache-status
+lean-runtime environments
+lean-runtime storage
 lean-runtime doctor
 lean-runtime verify research-stack --offline
-lean-runtime diff old.lock.json new.lock.json
+lean-runtime compare old.lock.json new.lock.json
 lean-runtime profile research-stack Main.lean --repeat 5
 lean-runtime matrix matrix.toml Main.lean
-lean-runtime gc
-lean-runtime gc --execute
+lean-runtime clean
+lean-runtime clean --execute
 ```
 
-`gc` is a dry run unless `--execute` is supplied.
+`clean` is a dry run unless `--execute` is supplied.
 
-`export` produces a deterministic OCI image-layout archive. `import` verifies
-the digest and identity chain, package Git trees, platform compatibility, and a
-Lean probe before atomically publishing the environment. See
-[Environment bundles](bundles.md) for the format and trust boundary.
+`save-copy` creates a portable environment file. `open-copy` verifies its exact
+identity, package Git trees, computer compatibility, and Lean probe before
+making the environment available. See [Portable copies and environment
+libraries](portable-copies.md) for its trust boundary.
 
 ## Replay
 
@@ -86,14 +86,14 @@ environment can replay offline.
 ## Existing projects and core Lean
 
 ```bash
-lean-runtime raw-check Main.lean --toolchain 4.32.2
-lean-runtime raw-check ./existing-project/MyProject/Main.lean
-lean-runtime project-build ./existing-project MyLibrary
+lean-runtime check-file Main.lean --toolchain 4.32.2
+lean-runtime check-file ./existing-project/MyProject/Main.lean
+lean-runtime build ./existing-project MyLibrary
 lean-runtime install 4.32.2
 ```
 
 Without `--with`, the environment-aware `check` command requires an environment
-identifier. `raw-check` remains the explicitly unmanaged route. When no
+identifier. `check-file` is the direct local-project route. When no
 `--project` or `--toolchain` is supplied, it discovers the nearest directory
 containing a Lake configuration and `lean-toolchain`, then passes the actual
 project-relative file to `lake env lean`.
@@ -112,10 +112,11 @@ execution output uses the versioned `lean-runtime.execution/v1` envelope; the ot
 schemas and advanced command examples are documented in
 [Verify, understand, compare, and measure](v1-precision.md).
 
-Global `--cache` is repeatable and `--prebuilt auto|require|never` controls
-transparent cache acquisition. `LEAN_RUNTIME_CACHES` accepts a comma-separated
-equivalent and `LEAN_RUNTIME_PREBUILT` sets the default policy.
+Global `--library` is repeatable and `--availability auto|required|local`
+controls whether ready-to-use environments are downloaded or built locally.
+`LEAN_RUNTIME_LIBRARIES` accepts a comma-separated equivalent and
+`LEAN_RUNTIME_AVAILABILITY` sets the default policy.
 
-Use global `--signatures require --trusted-identity ID --trusted-issuer ISSUER`
-to require a Cosign-verified publisher. `build-and-push --sign` signs the
-published lock-index digest using Cosign's configured keyless or keyed context.
+Use global `--publisher_verification required --trusted-publisher ID --trusted-issuer ISSUER`
+to require a verified publisher. `build-and-publish --sign` records the trusted
+publisher using the configured Cosign identity.

{lean_runtime-1.0.0 → lean_runtime-2.0.0}/docs/environments.md

@@ -88,6 +88,6 @@ serializing concurrent checks. Locks and source snapshots remain retained in
 the current store schema.
 
 ```python
-report = runtime.gc(dry_run=True)
-report = runtime.gc(dry_run=False, minimum_age_seconds=30 * 24 * 60 * 60)
+report = runtime.clean(dry_run=True)
+report = runtime.clean(dry_run=False, minimum_age_seconds=30 * 24 * 60 * 60)
 ```

{lean_runtime-1.0.0 → lean_runtime-2.0.0}/docs/index.md

@@ -2,7 +2,8 @@
 
 Lean Runtime runs Lean proofs from Python or a single `.lean` file. It discovers
 local Lake projects or compiles friendly exact dependencies into a
-content-addressed environment, then returns structured results and provenance.
+exact reusable environment, then returns structured results and a record of what
+was used.
 
 ```text
 lean-run FILE / lean.setup(CONTEXT)
@@ -20,16 +21,16 @@ It deliberately does not replace the official tools:
 
 - **Elan** installs and selects Lean toolchains.
 - **Lake** resolves packages and builds workspaces.
-- **Lean Runtime** owns acquisition, immutable identities, caching, execution
-  policy, Python ergonomics, and provenance.
+- **Lean Runtime** prepares exact environments, reuses downloaded and built
+  files, runs Lean, and records what was used.
 
 ## Current scope
 
 The front-facing API supports setup-once Python environments, one-shot helpers,
 friendly exact package references, standalone TOML frontmatter, local-project
 discovery, exact lock output, batch checking, and asyncio. The explicit runtime
-also exposes OCI caches, bundles, verification, signatures, captures, policies, and
-store lifecycle operations.
+also exposes environment libraries, portable copies, trusted publishers,
+verification, captures, policies, and storage lifecycle operations.
 
 The local backend executes **trusted inputs only**. Lean packages and Lake
 configuration can run native programs and arbitrary build commands; the local

{lean_runtime-1.0.0 → lean_runtime-2.0.0}/docs/local-projects.md

@@ -25,7 +25,7 @@ result = Runtime().check_file("./my-project/MyProject/Main.lean")
 The CLI equivalent is:
 
 ```bash
-lean-runtime raw-check ./my-project/MyProject/Main.lean
+lean-runtime check-file ./my-project/MyProject/Main.lean
 ```
 
 The actual project-relative file is passed to `lake env lean`, so imports of

lean_runtime-1.0.0/docs/bundles.md → lean_runtime-2.0.0/docs/portable-copies.md

@@ -1,106 +1,104 @@
-# Environment bundles
+# Portable copies and environment libraries
 
 Lean Runtime can move an already built environment between compatible machines
 without rebuilding its Lake packages:
 
 ```bash
-lean-runtime export research-stack --output research-stack.oci.tar.gz
-lean-runtime --home /tmp/fresh import research-stack.oci.tar.gz --name research-stack
+lean-runtime save-copy research-stack --output research-stack.lean-environment
+lean-runtime --home /tmp/fresh open-copy research-stack.lean-environment --name research-stack
 ```
 
 The equivalent Python API is:
 
 ```python
-info = runtime.export_environment("research-stack", "research-stack.oci.tar.gz")
-environment = another_runtime.import_environment("research-stack.oci.tar.gz", name="research-stack")
+info = runtime.save_portable_copy("research-stack", "research-stack.lean-environment")
+environment = another_runtime.open_portable_copy(
+    "research-stack.lean-environment", name="research-stack"
+)
 ```
 
-Import verifies the OCI manifest and every blob digest, recomputes the lock and
-environment identities, requires an exact platform compatibility match, checks
-each package's Git commit and tree, and runs a Lean probe. Publication uses a
-staging directory and atomic rename, so a failed import is never visible as a
-ready environment. `--no-probe` exists for inspection and testing workflows;
-normal imports should keep the probe enabled.
+Opening a copy verifies its exact environment identity, computer compatibility,
+package revisions, and a real Lean import before making it available. A failed
+open never appears as a ready environment. `--no-probe` exists for inspection
+and testing; normal use should keep the probe enabled.
 
-Layer construction, archive writing, import, and registry downloads are
-disk-backed and streamed. Peak memory does not scale with package-layer size.
+Saving, opening, and downloading are disk-backed and streamed. Peak memory does
+not scale with the size of the environment.
 
-## OCI global caches
+## Environment libraries
 
 By default, Lean Runtime checks the public
-`oci://ghcr.io/alerad/lean-runtime-cache` mirror. A miss or availability failure
+`ghcr.io/alerad/lean-runtime-cache` library. A missing or unavailable copy
 falls back to the existing source build, so environment specifications do not
-change. Set `LEAN_RUNTIME_CACHES=` or construct `Runtime(caches=[])` to disable
-all remote cache lookups.
+change. Set `LEAN_RUNTIME_LIBRARIES=` or construct `Runtime(libraries=[])` to disable
+all library lookups.
 
-Configure one or more cache repositories without changing the environment
+Configure one or more libraries without changing the environment
 specification or lock:
 
 ```python
 runtime = Runtime(
-    caches=["oci://ghcr.io/alerad/leancert-runtime"],
-    prebuilt="auto",
+    libraries=["ghcr.io/alerad/leancert-runtime"],
+    availability="auto",
 )
-environment = runtime.ensure(lock)
+environment = runtime.open_exact(lock)
 ```
 
 The equivalent environment variables are:
 
 ```bash
-export LEAN_RUNTIME_CACHES=oci://ghcr.io/alerad/leancert-runtime
-export LEAN_RUNTIME_PREBUILT=auto
+export LEAN_RUNTIME_LIBRARIES=ghcr.io/alerad/leancert-runtime
+export LEAN_RUNTIME_AVAILABILITY=auto
 ```
 
-`auto` tries caches in order and builds from source when an artifact is absent,
-incompatible, or temporarily unavailable. `require` makes an ordinary cache
-miss an error. `never` disables remote lookup. Digest, lock, archive-safety, and
-probe failures are security failures and never silently fall back to source.
+`auto` tries libraries in order and builds locally when a copy is absent,
+incompatible, or temporarily unavailable. `required` makes a missing copy an
+error. `local` disables library lookup. Verification failures never silently
+fall back to a local build.
 
 Explicit prefetch uses the same verified path:
 
 ```bash
 lean-runtime \
-  --cache oci://ghcr.io/alerad/leancert-runtime \
-  pull environment.lock.json
+  --library ghcr.io/alerad/leancert-runtime \
+  download environment.lock.json
 ```
 
-Registry blobs are retained content-addressed under the runtime home. Pulling a
-second environment with an identical package layer reuses it without another
-download.
+Downloaded files are retained under the runtime home. Opening another
+environment with identical dependencies reuses them without another download.
 
 Old blobs can be included in garbage collection explicitly:
 
 ```bash
 # Preview, then apply after reviewing the candidates.
-lean-runtime gc --include-blobs
-lean-runtime gc --include-blobs --execute
+lean-runtime clean --include-downloads
+lean-runtime clean --include-downloads --execute
 ```
 
-Blobs referenced by an imported environment or leased by an active pull are
-retained. Collection rechecks both conditions while holding the same per-blob
-lock used by downloads.
+Files used by a ready environment or an active download are retained. Cleanup
+rechecks both conditions before removing anything.
 
-### Required publisher signatures
+### Required publisher publisher_verification
 
 For high-trust workflows, require a Sigstore signature from one exact GitHub
 Actions identity:
 
 ```python
 runtime = Runtime(
-    caches=["oci://ghcr.io/alerad/leancert-runtime"],
-    signatures="require",
-    trusted_identity=(
+    libraries=["ghcr.io/alerad/leancert-runtime"],
+    publisher_verification="required",
+    trusted_publisher=(
         "https://github.com/alerad/leancert/.github/workflows/cache.yml@refs/heads/main"
     ),
     trusted_issuer="https://token.actions.githubusercontent.com",
 )
 ```
 
-CLI equivalents are `--signatures require`, `--trusted-identity`, and
+CLI equivalents are `--publisher_verification required`, `--trusted-publisher`, and
 `--trusted-issuer`. Verification uses an installed Cosign 2.6.2 or 3.0.4+ and
 binds the canonical lock-index digest, certificate identity, issuer, and
 transparency-log claims. Older versions are rejected because of the patched
-[Cosign verification advisory](https://github.com/sigstore/cosign/security/advisories/GHSA-whqx-f9j3-ch6m).
+[Cosign verification advisory](https://github.com/sigstore/verification_tool/security/advisories/GHSA-whqx-f9j3-ch6m).
 
 Signature failure is an integrity failure and never triggers source fallback.
 
@@ -112,8 +110,8 @@ Publish the current platform after ensuring the lock:
 export LEAN_RUNTIME_REGISTRY_USERNAME=alerad
 export LEAN_RUNTIME_REGISTRY_PASSWORD="$GHCR_TOKEN"
 
-lean-runtime build-and-push environment.lock.json \
-  --push-to oci://ghcr.io/alerad/leancert-runtime \
+lean-runtime build-and-publish environment.lock.json \
+  --publish-to ghcr.io/alerad/leancert-runtime \
   --tag v4.32.2.4 \
   --sign --attest
 ```
@@ -135,21 +133,21 @@ permissions:
 
 steps:
   - uses: actions/checkout@v4
-  - uses: ./.github/actions/cache
+  - uses: ./.github/actions/publish-environment
     with:
       lock: environment.lock.json
-      repository: oci://ghcr.io/${{ github.repository_owner }}/leancert-runtime
+      library: ghcr.io/${{ github.repository_owner }}/leancert-runtime
       tag: ${{ github.ref_name }}
-      registry-username: ${{ github.actor }}
-      registry-password: ${{ secrets.GITHUB_TOKEN }}
+      username: ${{ github.actor }}
+      password: ${{ secrets.GITHUB_TOKEN }}
 ```
 
 For a build matrix, have each platform publish without changing the canonical
 index and retain its JSON result:
 
 ```bash
-lean-runtime build-and-push environment.lock.json \
-  --push-to oci://ghcr.io/alerad/leancert-runtime \
+lean-runtime build-and-publish environment.lock.json \
+  --publish-to ghcr.io/alerad/leancert-runtime \
   --platform-only > platform-result.json
 ```
 
@@ -157,8 +155,8 @@ After collecting the result files, one final job publishes the deterministic
 multi-platform index and human aliases:
 
 ```bash
-lean-runtime publish-index "$LOCK_ID" results/*.json \
-  --repository oci://ghcr.io/alerad/leancert-runtime \
+lean-runtime finalize-publication "$LOCK_ID" results/*.json \
+  --library ghcr.io/alerad/leancert-runtime \
   --tag "$GITHUB_REF_NAME"
 ```
 
@@ -192,7 +190,7 @@ separate byte-reproducibility measurement: a mismatch is reported but is not
 treated as failed source/proof verification, because native toolchains and package build
 steps are not promised to produce byte-identical artifacts.
 
-## Format version 1
+## Advanced storage details
 
 The gzip file is a deterministic OCI image-layout archive. It contains a
 standard `oci-layout`, `index.json`, one image manifest, a Lean Runtime config
@@ -205,6 +203,12 @@ package. Package layers include both source and `.lake/build`, so identical
 serialized package trees are reused by the registry transport. The Lean
 toolchain is not bundled; Elan supplies the exact toolchain named by the lock.
 
+Package verification binds every tracked file to the locked Git commit and
+tree and rejects non-ignored untracked source. Git-ignored files generated by
+package build tooling are treated as derived artifacts: their bytes remain
+covered by the OCI layer digest and publisher trust policy, but they do not
+change the locked source identity.
+
 Archives use sorted paths, zero timestamps and ownership, normalized tar
 metadata, canonical JSON, and deterministic gzip headers. Exporting an unchanged
 environment twice therefore produces identical bytes and digests.
@@ -214,9 +218,9 @@ environment twice therefore produces identical bytes and digests.
 `lock_id` identifies the platform-independent locked source graph.
 `environment_id` additionally includes the release build profile and the
 versioned platform compatibility record. Informational host details remain in
-metadata but do not invalidate compatible caches across OS patch releases.
+metadata but do not invalidate compatible libraries across OS patch releases.
 
-A bundle is trusted executable build output. Digest, lock, Git-tree, and probe
+A portable copy is trusted executable build output. Digest, lock, Git-tree, and probe
 verification detect corruption and identity substitution, but do not prove that
-the builder compiled the sources faithfully. Registry credentials authenticate
-access but are not a builder attestation; only use cache publishers you trust.
+the builder compiled the sources faithfully. Library credentials authenticate
+access but are not a builder attestation; only use environment publishers you trust.