lean-runtime 2.4.0__tar.gz → 2.6.0__tar.gz

{lean_runtime-2.4.0 → lean_runtime-2.6.0}/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 ## Unreleased
 
+## 2.6.0 - 2026-08-14
+
+- Make the local-project path a four-command workflow: `init`, `check`,
+  `build`, and `update`. New projects use the newest stable cataloged Mathlib
+  by default; `--core` opts out, while `--mathlib VERSION` selects a release.
+- Make `init` adopt an existing pinned Lake project without changing its graph,
+  or create a new project transactionally after its exact dependencies are
+  ready. `--plan`, `--offline`, `--max-download`, and `--seed-from` expose its
+  acquisition policy, and failed initialization leaves no partial project.
+- Add persistent discovery of exact local Lake graphs. `scan` registers existing
+  projects as zero-download seeds for future initialization and updates.
+- Preserve verified sparse-capsule build artifacts when materializing exact Git
+  sources for a mutable project, instead of throwing them away and forcing a
+  dependency rebuild.
+- Add explicit, transactional `update` to the newest cataloged Mathlib, with an
+  old/new revision and toolchain preview and rollback after failed adoption.
+- Include exact package revisions, Git tree hashes, and the shared workspace ID
+  in mutable-project check and build provenance.
+
+## 2.5.0 - 2026-08-14
+
+- Make `lean-runtime init` create a concise `AGENTS.md` with build, checking,
+  and shared-dependency safety instructions by default. `--no-agents` opts out,
+  and existing guides are preserved.
+- Make `scripts/release.sh` provision an isolated release environment and allow
+  safe retries after a pre-tag failure instead of depending on undeclared
+  packages in the invoking Python environment.
+
+- Add shared Lake project onboarding and migration. `lean-runtime init` creates
+  a standard core or cataloged-Mathlib project; `attach` previews or
+  transactionally adopts one project or an entire recursive tree; and `detach`
+  materializes independent copies again. Adoption preserves root build output,
+  rejects dirty or mismatched dependencies, verifies both generated overrides
+  and ordinary Lake package links, and rolls back failed swaps. Attached
+  projects automatically use shared mode in `lean-runtime build`.
+- Add content-addressed Lake dependency workspaces. Each exact package is reused
+  across root manifests when its effective transitive closure, toolchain, and
+  platform match. Concurrent runtime builds are serialized, existing clean
+  artifacts seed the store with copy-on-write clones, and local Git object
+  databases seed other revisions without another network clone. Plain
+  `build --shared` never modifies the checkout; only explicit
+  `attach --execute` removes verified generated duplicates.
+
+- Add versioned check capsules: publisher-built manifests record every retained
+  module facet, exact import edges, content digest, package owner, and
+  capability. Publication now fails unless the full environment and a
+  physically isolated capsule both accept the locked public import.
+- Replace monolithic environment pulls with deterministic seekable zstd packs.
+  A clean check downloads only the pack frames covering its transitive import
+  closure; verified raw artifacts are shared in a cross-environment CAS and
+  projected atomically. `lean-run --plan` reports closure and check-runtime
+  costs before transfer, and `--max-download` gates their combined known cost.
+- Publish independently verified check-only Lean toolchains through the same
+  multi-platform OCI library. Consumers prefer the slim signed runtime before
+  installing the full official toolchain, while retaining an Elan fallback for
+  libraries that have not published the new artifact yet.
+- Add explicit sparse capabilities. Batch checking includes every olean facet
+  and IR file Lean actually requires; editor indexes are acquired only when
+  requested. Native/development requests fail with an actionable full-build
+  requirement instead of pretending that a check capsule supports them.
+- Make project export source-free and closure-scoped. `project export` now
+  creates a portable sparse capsule, and `open-copy` verifies its OCI digest
+  chain, per-artifact CAS hashes, exact lock/platform identity, and Lean probe
+  before publishing it locally.
+- Include shared sparse artifacts in `lean-runtime storage` and safely reclaim
+  old unleased CAS entries with `clean --include-downloads`.
+- Make releases tag-driven and fail closed: the helper waits for CI on the exact
+  release commit; the tag workflow independently checks version, changelog,
+  tests, docs, wheel metadata, and wheel installation; PyPI must succeed before
+  the GitHub release is created.
 - Extend the bundled catalog through Mathlib v4.33.0 and add exact LeanCert
   environments for the supported Lean 4.30, 4.31, 4.32, and 4.33 lines.
   Otherwise-equivalent discovery candidates now prefer the smallest exact

{lean_runtime-2.4.0/lean_runtime.egg-info → lean_runtime-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.4.0
+Version: 2.6.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -22,6 +22,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: tomli>=2; python_version < "3.11"
+Requires-Dist: zstandard<1,>=0.23
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
@@ -90,6 +91,21 @@ environment libraries, then builds the exact source environment when necessary.
 `--no-source-build` to forbid that potentially large fallback or `--offline` to use
 retained environments only.
 
+Before a cold run, inspect its cost without changing the store:
+
+```bash
+lean-run Main.lean --plan
+lean-run Main.lean --max-download 2GiB
+```
+
+New-format libraries publish two independently verified pieces: a slim Lean
+check runtime and seekable module packs. Lean Runtime computes the source's
+transitive import closure, downloads only the corresponding compressed frames,
+and shares verified module artifacts across Mathlib, LeanCert, and future
+environments. A warm check is silent apart from its result. Older published
+environments remain readable and automatically use the legacy full-bundle
+path, so this optimization does not invalidate existing locks.
+
 Explicit frontmatter remains available when the desired context is already known:
 
 ```lean
@@ -165,6 +181,35 @@ project = lean.setup(project="./my-project")
 result = project.check_file("./my-project/MyProject/Main.lean")
 ```
 
+Create a normal Lake project. The newest stable cataloged Mathlib is the
+default, and exact dependencies are shared automatically:
+
+```bash
+lean-runtime init MyProof
+cd MyProof
+lean-runtime check MyProof/Basic.lean
+lean-runtime build
+```
+
+`init` also writes an `AGENTS.md` with the project build, checking, dependency,
+and shared-package rules for coding agents. Pass `--no-agents` to omit it; an
+existing `AGENTS.md` is never overwritten. Use `--core` for no Mathlib, or
+`--mathlib 4.33.0` to select a cataloged release. `lean-runtime update`
+explicitly moves a project to the newest cataloged Mathlib after a preview.
+
+Running `lean-runtime init .` in an existing pinned Lake project adopts its
+current exact graph without running `lake update`. If you already have many
+Lake checkouts, register them once as local dependency seeds:
+
+```bash
+lean-runtime scan ~/research
+lean-runtime init .
+```
+
+`init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
+enforce cold-start policy. Advanced bulk migration remains available through
+`attach`, and `detach --execute` materializes an independent project again.
+
 One-shot helpers are available when setup reuse is unnecessary:
 
 ```python
@@ -217,7 +262,9 @@ lean-runtime project init-publish . \
 ```
 
 The workflow builds and verifies Linux and macOS environments, finalizes the
-index atomically, then checks clean consumers. See
+environment and slim-toolchain indexes atomically, then checks clean consumers.
+For a one-machine handoff, `lean-runtime project export` writes a source-free
+portable capsule containing only the selected public module's closure. See
 [Publishing a Lean project](https://alerad.github.io/lean-runtime/project-publishing/).
 
 For an already-built executable, Lean Runtime can also create a verified
@@ -229,10 +276,10 @@ library. See [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob
 
 The simple API is backed by exact Git commits and trees, Lake-resolved locks,
 platform-aware content-addressed environments, atomic cross-process builds,
-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.
+downloadable environment reuse, sparse content-addressed module packs,
+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
 

{lean_runtime-2.4.0 → lean_runtime-2.6.0}/README.md

@@ -55,6 +55,21 @@ environment libraries, then builds the exact source environment when necessary.
 `--no-source-build` to forbid that potentially large fallback or `--offline` to use
 retained environments only.
 
+Before a cold run, inspect its cost without changing the store:
+
+```bash
+lean-run Main.lean --plan
+lean-run Main.lean --max-download 2GiB
+```
+
+New-format libraries publish two independently verified pieces: a slim Lean
+check runtime and seekable module packs. Lean Runtime computes the source's
+transitive import closure, downloads only the corresponding compressed frames,
+and shares verified module artifacts across Mathlib, LeanCert, and future
+environments. A warm check is silent apart from its result. Older published
+environments remain readable and automatically use the legacy full-bundle
+path, so this optimization does not invalidate existing locks.
+
 Explicit frontmatter remains available when the desired context is already known:
 
 ```lean
@@ -130,6 +145,35 @@ project = lean.setup(project="./my-project")
 result = project.check_file("./my-project/MyProject/Main.lean")
 ```
 
+Create a normal Lake project. The newest stable cataloged Mathlib is the
+default, and exact dependencies are shared automatically:
+
+```bash
+lean-runtime init MyProof
+cd MyProof
+lean-runtime check MyProof/Basic.lean
+lean-runtime build
+```
+
+`init` also writes an `AGENTS.md` with the project build, checking, dependency,
+and shared-package rules for coding agents. Pass `--no-agents` to omit it; an
+existing `AGENTS.md` is never overwritten. Use `--core` for no Mathlib, or
+`--mathlib 4.33.0` to select a cataloged release. `lean-runtime update`
+explicitly moves a project to the newest cataloged Mathlib after a preview.
+
+Running `lean-runtime init .` in an existing pinned Lake project adopts its
+current exact graph without running `lake update`. If you already have many
+Lake checkouts, register them once as local dependency seeds:
+
+```bash
+lean-runtime scan ~/research
+lean-runtime init .
+```
+
+`init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
+enforce cold-start policy. Advanced bulk migration remains available through
+`attach`, and `detach --execute` materializes an independent project again.
+
 One-shot helpers are available when setup reuse is unnecessary:
 
 ```python
@@ -182,7 +226,9 @@ lean-runtime project init-publish . \
 ```
 
 The workflow builds and verifies Linux and macOS environments, finalizes the
-index atomically, then checks clean consumers. See
+environment and slim-toolchain indexes atomically, then checks clean consumers.
+For a one-machine handoff, `lean-runtime project export` writes a source-free
+portable capsule containing only the selected public module's closure. See
 [Publishing a Lean project](https://alerad.github.io/lean-runtime/project-publishing/).
 
 For an already-built executable, Lean Runtime can also create a verified
@@ -194,10 +240,10 @@ library. See [Ready-to-run programs](https://github.com/alerad/lean-runtime/blob
 
 The simple API is backed by exact Git commits and trees, Lake-resolved locks,
 platform-aware content-addressed environments, atomic cross-process builds,
-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.
+downloadable environment reuse, sparse content-addressed module packs,
+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
 

{lean_runtime-2.4.0 → lean_runtime-2.6.0}/docs/architecture.md

@@ -114,6 +114,29 @@ renames the stage to its final identity.
 Crashes cannot publish a partially ready environment. Concurrent processes
 requesting the same identity converge on the same published directory.
 
+## Check capsules and sparse acquisition
+
+Publication derives a normalized capsule manifest from the authoritative full
+build with the selected Lean version's import parser. Each module records exact
+imports and all retained artifact facets. The publisher physically projects a
+source-free copy and requires both the full build and that isolated projection
+to accept the locked public import before it can upload anything.
+
+Artifacts are grouped by package and capability into deterministic zstd packs.
+Each pack is a sequence of independently compressed and hashed frames; the OCI
+manifest still addresses the complete pack, while consumers use exact HTTP
+Range requests for only the frames intersecting a source's transitive import
+closure. Decompressed artifacts are verified into a raw-content CAS and
+hardlinked into a growing environment projection. The generated versioned
+`--setup` file points Lean directly at those facets, bypassing Lake and source
+metadata during checks.
+
+The Lean executable and core libraries use a separate multi-platform check
+toolchain index keyed by normalized toolchain identity. Platform selection is
+encoded only in child descriptors, so one atomic index serves Linux AMD64,
+macOS AMD64, and macOS ARM64. Consumers verify the exact Lean commit and run a
+capability corpus before publishing the downloaded runtime locally.
+
 ## Execution
 
 A published build is not used as an ordinary mutable working directory. Each

{lean_runtime-2.4.0 → lean_runtime-2.6.0}/docs/cli.md

@@ -109,8 +109,29 @@ stay; larger reductions require upstream facet-loading changes.
 
 After pruning, source builds of *new* environments and native compilation
 need the full toolchain again; reinstall it with `lean-runtime install`.
-Downloads are unaffected: first-time installation still transfers the full
-official release before a slim copy can be derived from it.
+
+Libraries produced by the current publication workflow also carry this
+verified check profile directly. A cold consumer downloads that compressed
+profile instead of first transferring the full official release. If the
+library has no compatible published check runtime, Lean Runtime falls back to
+the official Elan installation path. Local `toolchain-slim` remains useful for
+older stores and for testing a profile before publication.
+
+## Sparse acquisition and capabilities
+
+`lean-run FILE --plan` reads capsule metadata and reports the exact compressed
+frames required by `FILE`'s transitive import closure, plus the selected Lean
+check-runtime cost. The operation has no store side effects. `--max-download`
+applies before acquisition to the combined known cost; an unknown component is
+reported explicitly instead of treated as zero.
+
+The ordinary check capability retains `.olean`, `.olean.server`,
+`.olean.private`, `.ir`, and `.ir.sig`. This is empirical, not conservative
+guesswork: Lean 4.32 and 4.33 reject ordinary imports when the corresponding
+server/private or IR facets are omitted. `.ilean` editor indexes are a separate
+on-demand capability through `Environment.require_capabilities(["editor"],
+imports=[...])`. Native compilation and development builds require a full
+environment and full toolchain; check capsules reject those requests clearly.
 
 ## Replay
 
@@ -125,18 +146,37 @@ environment can replay offline.
 ## Existing projects and core Lean
 
 ```bash
-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 check Main.lean --toolchain 4.32.2
+lean-runtime check ./existing-project/MyProject/Main.lean
+lean-runtime build
+lean-runtime init MyProof
+lean-runtime init MyProof --core
+lean-runtime init --plan --max-download 500MiB
+lean-runtime update --plan
+lean-runtime scan ~/research
+lean-runtime attach ~/research --recursive
+lean-runtime attach ~/research --recursive --execute
+lean-runtime detach ./existing-project --execute
 lean-runtime install 4.32.2
 ```
 
-Without `--with`, the environment-aware `check` command requires an environment
-identifier. `check-file` is the direct local-project route. When no
+`check FILE` is the direct standalone/local-project route; the legacy
+`check ENVIRONMENT FILE` spelling remains accepted. 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`.
 
+`init` defaults to the newest stable cataloged Mathlib, or adopts an existing
+pinned Lake project without changing its graph. `--core` opts out of Mathlib.
+It prepares dependencies before atomically publishing a new project. `update`
+is the explicit transactional move to the newest cataloged Mathlib; `scan`
+records exact existing graphs as future local seeds. `attach` is read-only
+unless `--execute` is present;
+recursive mode inventories a project tree, reports blockers and estimated disk
+recovery, and adopts each valid project transactionally. `detach` is likewise a
+preview unless `--execute` is present. Attached projects use shared mode by
+default in `lean-runtime build`; detach before requesting `--local`.
+
 Add supporting source files with repeatable `--include` options:
 
 ```bash

{lean_runtime-2.4.0 → lean_runtime-2.6.0}/docs/environments.md

@@ -11,6 +11,12 @@ Lean Runtime separates three states:
 The separation lets one process resolve a lock and another materialize it. A
 completed environment can subsequently be opened offline.
 
+Downloadable environments may use the legacy full-workspace representation or
+the current sparse check-capsule representation. Both resolve to the same exact
+lock and platform environment identity. A capsule stores a normalized module
+graph and content digest for each Lean artifact; its local projection grows as
+new imports are checked without changing that identity.
+
 Package references are an input compiler for `EnvironmentSpec`, not another
 environment type:
 
@@ -87,6 +93,14 @@ Short-lived execution leases prevent deletion during cloning without
 serializing concurrent checks. Locks and source snapshots remain retained in
 the current store schema.
 
+Sparse downloads are stored once by artifact digest under the shared module
+CAS and hardlinked into environment projections when the filesystem permits.
+`lean-runtime storage` reports this category separately. Because it is shared,
+its logical byte count can overlap environment projections and should not be
+added to their logical sizes as an estimate of physical disk use.
+`clean --include-downloads` reclaims old OCI blobs and unleased CAS artifacts;
+per-artifact locks and recency updates prevent collection during projection.
+
 ```python
 report = runtime.clean(dry_run=True)
 report = runtime.clean(dry_run=False, minimum_age_seconds=30 * 24 * 60 * 60)

{lean_runtime-2.4.0 → lean_runtime-2.6.0}/docs/getting-started.md

@@ -6,11 +6,63 @@
 python -m pip install lean-runtime
 ```
 
-On macOS and Linux, Lean Runtime installs requested Lean versions through its
+On macOS and Linux, Lean Runtime first uses a published slim check toolchain when
+one is available and otherwise installs the requested Lean version through its
 private, checksum-verified Elan installation. It does not change the user's
 default toolchain or shell profile. Windows currently requires an existing Elan
 executable through `LEAN_RUNTIME_ELAN`.
 
+## Start a Lake project
+
+Create a standard Lake library with the newest cataloged Mathlib release and
+shared exact dependencies:
+
+```bash
+lean-runtime init MyProof
+cd MyProof
+lean-runtime check MyProof/Basic.lean
+lean-runtime build
+```
+
+By default, `init` writes an `AGENTS.md` explaining the project workflow and
+shared-dependency safety rules to coding agents. Pass `--no-agents` to omit it.
+An existing file is preserved.
+
+Use `--mathlib 4.33.0` to select that release explicitly, or `--core` for a
+core-only library. The root project remains an ordinary mutable Lake project;
+its dependency sources and build artifacts are reused by other projects with
+the same exact graph.
+
+Before doing any work, `init --plan` reports the exact release, local reuse, and
+known download size. `--max-download 500MiB` refuses a larger transfer and
+`--offline` requires a matching local graph. Initialization is transactional:
+the target appears only after Lake and the shared dependency graph both verify.
+Project development requires one full Lake-capable Lean toolchain per Lean
+version. When it is absent, the plan says its Elan download size is unknown;
+`--offline` and `--max-download` fail closed instead of silently installing it.
+
+Dependency upgrades are explicit:
+
+```bash
+lean-runtime update --plan
+lean-runtime update
+```
+
+The update preview names both exact Mathlib revisions and toolchains. In a
+terminal, the second command asks for confirmation; use `--yes` in automation.
+
+For one existing pinned Lake project, preserve and adopt its current exact graph:
+
+```bash
+lean-runtime init .
+lean-runtime scan ~/research
+```
+
+`scan` only records exact local graphs as possible future zero-download seeds.
+Advanced bulk migration remains available through `attach`. See [Local Lake
+projects](local-projects.md) for detachment, storage estimates, and the complete
+safety model.
+
 ## Run a file
 
 For a file inside a pinned Lake project:

{lean_runtime-2.4.0 → lean_runtime-2.6.0}/docs/index.md

@@ -1,7 +1,7 @@
 # Lean Runtime
 
 Lean Runtime runs Lean proofs from Python or a single `.lean` file. It discovers
-local Lake projects or compiles friendly exact dependencies into a
+local Lake projects or compiles friendly exact dependencies into an
 exact reusable environment, then returns structured results and a record of what
 was used.
 
@@ -28,9 +28,12 @@ It deliberately does not replace the official tools:
 
 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 environment libraries, portable copies, trusted publishers,
-verification, captures, policies, and storage lifecycle operations.
+discovery, shared Lake dependencies, exact lock output, batch checking, and
+asyncio. New projects can begin with a shared catalog-pinned Mathlib graph;
+existing project trees can preview and transactionally adopt the same layout.
+The explicit runtime 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-2.6.0/docs/local-projects.md

@@ -0,0 +1,189 @@
+# Local Lake projects
+
+Lean Runtime can discover and operate on an existing trusted Lake checkout
+without converting it into an immutable managed environment:
+
+```python
+from lean_runtime import Runtime
+
+project = Runtime().project("./my-project")
+project.build()
+result = project.check_file("./my-project/MyProject/Main.lean")
+```
+
+`Runtime.project()` accepts either the project root or any contained path. It
+walks upward and selects the nearest directory containing both `lean-toolchain`
+and `lakefile.toml` or `lakefile.lean`.
+
+`Runtime.check_file(path)` performs the same discovery automatically when no
+managed environment, dependency list, or explicit toolchain is supplied:
+
+```python
+result = Runtime().check_file("./my-project/MyProject/Main.lean")
+```
+
+The primary CLI equivalent is:
+
+```bash
+lean-runtime check ./my-project/MyProject/Main.lean
+```
+
+The actual project-relative file is passed to `lake env lean`, so imports of
+local modules retain normal Lake semantics. Checking a source string writes a
+uniquely named disposable file under `.lake/lean-runtime/` and removes it after
+execution:
+
+```python
+result = project.check("import MyProject\nexample : True := by trivial")
+```
+
+## Reusing dependencies across projects
+
+Ordinary Lake workspaces put remote dependencies and their build artifacts in
+each repository's `.lake/packages`. New projects can start in shared mode:
+
+```bash
+lean-runtime init MyProof
+cd MyProof
+lean-runtime check MyProof/Basic.lean
+lean-runtime build
+```
+
+The generated files are a standard Lake project plus a small
+`lean-runtime.toml`. Root build outputs stay local; exact dependencies are
+shared. The newest stable cataloged Mathlib is selected by default. Select a
+release with `--mathlib 4.33.0`, or use `--core` for a core-only library.
+`init` also creates an `AGENTS.md` describing the safe
+build and dependency workflow unless `--no-agents` is passed; it never
+overwrites an existing guide.
+
+Initialization acquires and verifies the exact graph before publishing the
+target directory. Use `--plan` for a side-effect-free cost report, `--offline`
+to require local data, `--max-download SIZE` to enforce a transfer ceiling, or
+`--seed-from PROJECT` to name an exact local donor.
+The plan separately reports whether the full Lake-capable toolchain is already
+installed. Because Elan does not publish a preflight byte count, a missing full
+toolchain is rejected under `--offline` or `--max-download` rather than silently
+bypassing the policy.
+
+For an existing pinned project, `lean-runtime init .` adopts its current
+manifest without changing versions. Register a collection once with
+`lean-runtime scan ~/research`; future exact matches are preferred over
+downloads automatically.
+
+Move an adopted TOML project to the newest cataloged Mathlib explicitly:
+
+```bash
+lean-runtime update --plan
+lean-runtime update
+```
+
+The plan reports old and new release, commit, toolchain, local donor, and known
+download bytes. Acquisition happens before metadata changes, and failures
+restore the prior Lake files and attachment metadata.
+
+For advanced bulk onboarding, preview before changing anything:
+
+```bash
+lean-runtime attach .
+lean-runtime attach . --execute
+```
+
+For a directory containing many projects:
+
+```bash
+lean-runtime attach ~/research --recursive
+lean-runtime attach ~/research --recursive --execute
+```
+
+The preview groups exact graphs, reports current and estimated shared storage,
+and identifies missing local paths, dirty dependencies, and revision
+mismatches. Execution continues through independent projects while reporting
+per-project failures. It first prepares the exact shared workspace and probes it
+through Lake. Only then does it atomically replace `.lake/packages` with package
+links, probe the resulting project through ordinary Lake, and discard the old
+generated copies. Any failure restores the original package directory.
+
+The project itself remains portable. To return to independent package copies:
+
+```bash
+lean-runtime detach .
+lean-runtime detach . --execute
+```
+
+Detachment copy-on-write clones the exact packages where the filesystem allows,
+probes the standalone graph, and only then removes the attachment metadata. The
+preview reports the maximum independent-copy size and available disk space;
+execution refuses to rely on copy-on-write support when there is not enough
+space for a full fallback copy.
+
+The lower-level opt-in remains available without changing project layout:
+
+```bash
+lean-runtime build . --shared
+```
+
+Or from Python:
+
+```python
+Runtime().project(".").build(shared=True)
+```
+
+Lean Runtime reads the existing `lake-manifest.json` and passes Lake a generated
+`--packages` override. Each remote package is keyed by its exact revision,
+effective transitive dependency closure, Lean toolchain, and host platform;
+local-path dependency contents are part of the surrounding workspace identity.
+Dependency sources and their `.lake/build` artifacts live under the runtime
+store, while the root project's own `.lake/build` remains in the checkout. This
+lets two different root manifests share the same Mathlib package safely. Builds
+that touch any of the same package keys are serialized because Lake may update
+their artifacts.
+
+The first shared build imports a clean, revision-matching local dependency copy
+when one exists, using copy-on-write filesystem clones where supported. Missing
+sources are fetched at the exact manifest commit. A plain shared build never
+deletes the old `.lake/packages`; only an explicit `attach --execute` replaces
+those generated copies after verification. `lean-runtime storage` reports
+shared project package usage; automatic cleanup of those packages is not yet
+implemented.
+
+This mode requires a manifest and never runs `lake update`, so it cannot silently
+change dependency revisions. It also reuses an existing local Git object database
+when that database contains another requested revision, avoiding redundant Git
+downloads. Local `path` dependencies remain at their declared locations and are
+included in the workspace identity. Attached projects automatically use shared
+mode when run through `lean-runtime build`; `--local` is an explicit escape
+hatch for unattached checkouts. An attached project must be detached before a
+local build, so `--local` cannot silently continue using shared links. After
+changing the manifest or a local path dependency, rerun `lean-runtime attach .
+--execute` to refresh the ordinary-Lake links.
+
+This differs from `lake env lean File.lean`: that command only constructs the
+current workspace's environment and checks one file; it neither builds missing
+imports nor shares dependencies with another checkout. The shared build still
+uses Lake's real build graph and project targets—it only changes where locked
+dependencies come from. Attached links also let ordinary `lake build` and the
+editor load the graph; prefer `lean-runtime build` when several projects may
+build concurrently, because it serializes writes to shared artifacts.
+
+## Mutable-project provenance
+
+A local project is intentionally represented by `ProjectEnvironment`, not the
+content-addressed `Environment` used for locked dependency graphs. Its results
+therefore have `environment_id=None` and include project provenance containing:
+
+- the canonical project root;
+- a content digest excluding `.git` and `.lake`;
+- Lake configuration and manifest digests;
+- the Git revision and dirty state when Git metadata is available.
+
+The workspace digest changes when local source or configuration changes, while
+generated Lake artifacts do not affect it.
+
+Lean Runtime does not run `lake update` or rewrite the manifest.
+`project.build()` explicitly runs the pinned toolchain's `lake build`; checks
+otherwise use the project exactly as it exists. Shared builds copy or fetch only
+locked dependencies into the runtime store and leave the mutable root checkout
+in place.
+As with managed environments, Lake configuration and dependencies are trusted
+code and the local backend is not a sandbox.