varve 0.1.0__tar.gz

varve-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format
+        run: uv run ruff format --check .
+
+      - name: Tests
+        run: uv run pytest
+
+      - name: Pyright pre-flight
+        continue-on-error: true
+        run: uv run pyright

varve-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    name: Release PR
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+
+    steps:
+      - name: Create or finalize release PR
+        id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  build:
+    name: Build distribution
+    needs: release-please
+    if: ${{ always() && (github.event_name == 'workflow_dispatch' || needs.release-please.outputs.release_created == 'true') }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build source and wheel distributions
+        run: uv build --no-sources
+
+      - name: Smoke install from sdist
+        run: |
+          python -m venv /tmp/varve-smoke
+          /tmp/varve-smoke/bin/python -m pip install dist/*.tar.gz
+          /tmp/varve-smoke/bin/python -c "import varve; varve.Pipeline"
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs:
+      - release-please
+      - build
+    runs-on: ubuntu-latest
+    if: needs.release-please.outputs.release_created == 'true'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/varve
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

varve-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+

varve-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.5
+    hooks:
+      - id: ruff-check
+        types_or: [python, pyi]
+        args: [--fix]
+      - id: ruff-format
+        types_or: [python, pyi]

varve-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

varve-0.1.0/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## Read First
+
+- User-facing positioning and examples: `README.md`.
+- Package layout, dependency direction, cache/store, CLI/config, clean, and dashboard boundaries: `ARCHITECTURE.md`.
+- Contributor setup, public API policy, style, and Conventional Commits: `CONTRIBUTING.md`.
+
+## Agent Rules
+
+`varve` is an independent Python infrastructure submodule. Documentation, comments, examples, and user-facing messages in this submodule must be English.
+
+Keep the public import surface small:
+
+```python
+from varve import Ctx, Pipeline, JSON, KeySpec, StageSpec, batch_stage, stage
+```
+
+Prefer compact pre-1.0 APIs over compatibility shims. If an old public name is awkward and there are no external users, update current callers and docs instead of keeping deprecated aliases.
+
+When changing author-facing behavior, update `README.md` and `ARCHITECTURE.md` in the same change. Release/version/changelog design lives in the workspace spec, not in this submodule.

varve-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,107 @@
+# varve Architecture
+
+`varve` is a small single-machine runner for Python-defined experiment pipelines with a materialized, content-addressed cache. Users define `Pipeline` classes and stages; varve owns branch-aware output roots, cache keys, store records, generated CLI commands, and clean/status behavior.
+
+## Package Layout
+
+```text
+src/varve/
+├── __init__.py          # public re-export surface
+├── pipeline.py          # Pipeline base class, stage collection, CLI hook
+├── decorators.py        # @stage, @batch_stage, StageSpec
+├── context.py           # Ctx passed to stage methods
+├── branch.py            # varve.yaml and override branch helpers
+├── branch_config.py     # Config construction and output-root selection
+├── keyspec.py           # JSON and KeySpec declarations
+├── models.py            # persisted pydantic store models
+├── keying/              # source/file/config/upstream key components
+├── store/               # file lock and latest-wins Store
+├── engine/              # cache-state decisions and runner
+├── cli/                 # generated Pipeline.cli() commands
+└── dashboard/           # varve ls/show/refresh over existing stores
+```
+
+## Public Surface
+
+Only these names are exported from `varve.__all__`:
+
+```python
+from varve import Ctx, Pipeline, JSON, KeySpec, StageSpec, batch_stage, stage
+```
+
+Everything else is internal unless this document or `README.md` says otherwise. `Store`, persisted models, keying helpers, runner helpers, and dashboard models may be used by internal code and tests through full module paths, but they are not public API.
+
+## Dependency Direction
+
+- Low-level packages: `keying`, `store`, and `engine.state`. They depend only on leaf modules such as `models`, `log`, and `keyspec`.
+- Middle layer: `branch_config` and `engine.runner`.
+- Top layers: `cli` and `dashboard`.
+- Public-facing modules such as `pipeline`, `decorators`, and `context` may use internals to keep the user API small.
+- The only intentional reverse edge is the lazy import inside `Pipeline.cli()`: `from varve.cli.app import main`.
+
+There is no import-direction tool. Keep the graph boring by review.
+
+## Cache And Store
+
+The store lives under `<output_root>/.varve/` and is latest-wins, not append-only:
+
+```text
+.varve/
+├── manifest.json
+├── lock
+├── stages/<stage>.json
+├── attempts/<stage>.json
+└── partial/<stage>/<run_key>/
+```
+
+`content_key` includes stage source, discovered project callables, full `Config`, declared `KeySpec.files`, declared `KeySpec.values`, and upstream content keys. `run_key` adds batch partition values.
+
+Recorded artifact paths are output-root-relative. Stage bodies should write through `ctx.out`.
+
+Stage bodies read upstream outputs through `ctx.input(stage)` for exactly one path or `ctx.inputs(stage)` for a list of paths. Both helpers require `stage` to be declared in the current stage's `needs=` list, because only declared upstreams are folded into the content key.
+
+Known cache states are `dirty`, `hit`, `artifact-missing`, `stale`, `no-cache`, `resume`, and `unrecoverable`.
+
+## Output Roots And Branches
+
+`Pipeline.default_output_root(config)` returns the base output root. The CLI can override that with `--out`. Varve then appends the selected branch:
+
+```text
+base/<branch>        # persistent branches
+base/.tmp/<branch>   # temporary override branches
+```
+
+`varve.yaml` is discovered next to the pipeline module. Missing `varve.yaml` is allowed for `main`.
+
+## CLI And Config
+
+`Pipeline.cli(argv)` delegates to `varve.cli.app.main` and provides `run`, `status`, `plan`, `list`, and `clean`.
+
+`argparse` parses commands and generated `Args` flags. `pydantic-settings` builds semantic `Config` values from branch/override values, environment variables, `.env`, and model defaults.
+
+Config priority:
+
+```text
+branch or override value > env > dotenv (.env) > field default
+```
+
+Do not add Click or Typer. The strict `argparse` behavior is intentional.
+
+## Clean Safety
+
+All clean operations require a valid `.varve/manifest.json` anchor under the selected output root.
+
+Full clean removes the whole output root after rejecting dangerous roots such as empty paths, `/`, the home directory, and the current working directory. Pipelines can narrow allowed full-clean roots by overriding `Pipeline.clean_roots(config)`.
+
+Per-stage clean only deletes recorded artifacts and store records for the selected downstream closure. It does not use `allowed_roots`; its boundary is the manifest anchor plus recorded artifact paths.
+
+## Dashboard
+
+The top-level `varve` console script reads existing stores.
+
+Temporary branches under `out/.tmp` are filtered by default and included only with `--include-temp`. Discovery is zero-import; state rendering imports stored manifest modules only after discovery. `refresh` runs branches whose evaluated status is executable: `artifact-missing`, `dirty`, `no-cache`, `resume`, or `stale`.
+
+## Known Limitations
+
+- Source fingerprints use `ast.dump`; a CPython minor-version upgrade may invalidate caches.
+- Windows is not supported yet because locking uses `fcntl`.

varve-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## 0.1.0 (2026-07-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* ctx.input now requires exactly one output; use ctx.inputs for upstream stages with zero or multiple outputs.
+* rename Experiment to Pipeline
+* removes file_set, __version__, the Ctx ledger alias, the corrupt-store status, KeySpec.coerce, and the top-level dashboard --include-temp compatibility path.
+* **keying:** enable automatic source uses
+* **dashboard:** evaluate status through engine
+* **cli:** redesign generated commands
+* **core:** rename branches.yaml to varve.yaml
+* **core:** KeySpec.config is removed and the full Config now enters the content key; Experiment.output_root gained branch/is_temporary and resolve_output_root is gone; `--config` now points to branches.yaml and semantic flags are replaced by --branch/--override/--name.
+* **cli:** own output root resolution
+
+### Features
+
+* add file set key helper ([ab1046a](https://github.com/moeakwak/varve/commit/ab1046a069a354e5553717ce732272948d77235f))
+* **cli:** own output root resolution ([04b93ff](https://github.com/moeakwak/varve/commit/04b93fff8a97f1315dc82dc6bad9924bc1ef2ea3))
+* **cli:** redesign generated commands ([cf5b729](https://github.com/moeakwak/varve/commit/cf5b72941550defd09806e9d2e70d1fc9c1c6bb9))
+* **cli:** support `refresh --prefix` ([adb2a06](https://github.com/moeakwak/varve/commit/adb2a06664ca44cf990f136d8feb3292018afa85))
+* **cli:** support Literal/Enum choices, null, help, and lighter clean ([53879bf](https://github.com/moeakwak/varve/commit/53879bffda1daadeca809b63a85e02b22c2f6f9f))
+* **context:** default tqdm progress bar for resumed batch stages ([62b33f2](https://github.com/moeakwak/varve/commit/62b33f21a8991befb604401e6833e4486a87148e))
+* **core:** branch-scoped runs with Args/Config split and full-config keying ([13dfb0f](https://github.com/moeakwak/varve/commit/13dfb0f54a377bd5f11f468af8670fe33c6854ee))
+* **dashboard:** add `refresh` command ([eebf01e](https://github.com/moeakwak/varve/commit/eebf01ebced024db197531f2bcdd33695c8b91c3))
+* **dashboard:** add read-only store dashboard ([1f32834](https://github.com/moeakwak/varve/commit/1f32834b8f256c055135d9cc8e7230c17f4bd981))
+* **dashboard:** evaluate status through engine ([c0df1b9](https://github.com/moeakwak/varve/commit/c0df1b9269c159e51e434254e1a5a67d87c329c3))
+* **dashboard:** include temporary branches ([733673a](https://github.com/moeakwak/varve/commit/733673a30631c944479364ce312e8f3fbef0d7b5))
+* **dashboard:** show persisted stage duration ([6ce520f](https://github.com/moeakwak/varve/commit/6ce520f45614c260a6ca2ed8360c601489d6f301))
+* **keying:** enable automatic source uses ([2d05a8f](https://github.com/moeakwak/varve/commit/2d05a8f8d37fb0bf04cdeb3c86bc6f3f0cedc1e4))
+* split upstream output helpers ([805cd7d](https://github.com/moeakwak/varve/commit/805cd7d8ab557e8031f4588c6655f3751909a605))
+
+
+### Bug Fixes
+
+* **cli:** refresh executable dashboard stores ([024ce71](https://github.com/moeakwak/varve/commit/024ce719dcd3e243d62a27c5c0ae40485f4e8a07))
+* **engine:** harden output-root path and lock handling ([d4c481d](https://github.com/moeakwak/varve/commit/d4c481d292bd70333d6753637cda44712c1b1ff4))
+* **keying:** stabilize `__main__` helper labels ([96916ea](https://github.com/moeakwak/varve/commit/96916eab1af66c05841fd05a7a978f8d00f5250b))
+
+
+### Documentation
+
+* sync docs with current behavior ([c9dcfb0](https://github.com/moeakwak/varve/commit/c9dcfb0df9fc1da777768ec5ddc02d4c0e11321c))
+
+
+### Code Refactoring
+
+* **core:** rename branches.yaml to varve.yaml ([4b1a369](https://github.com/moeakwak/varve/commit/4b1a3692b3631a5120bd32f9e1584820f8637390))
+* rename Experiment to Pipeline ([e994f79](https://github.com/moeakwak/varve/commit/e994f7955b011d39216fde5b5402891164a8e710))
+* simplify varve surface and tests ([07649ba](https://github.com/moeakwak/varve/commit/07649ba03a6f5ec218e1a144a7e481ec0440d27e))
+
+## Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Varve is in the 0.x phase. Minor releases may include breaking API or store schema changes; read this changelog before upgrading.
+
+Release entries are generated by release-please from Conventional Commits.

varve-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Varve is still alpha-stage. Keep changes small, tested, and easy to review.
+
+## Setup
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv run pyright
+```
+
+`pyright` is currently a pre-flight signal, not a blocking quality bar.
+
+## Public API
+
+The public import surface is intentionally small:
+
+```python
+from varve import Ctx, JSON, KeySpec, Pipeline, StageSpec, batch_stage, stage
+```
+
+Do not re-export internal store, keying, runner, or dashboard types from `varve.__all__`. Treat public API and `.varve/` store schema changes as breaking.
+
+## Style
+
+- User-facing docs, examples, comments, and messages are English.
+- Follow the package boundaries in `ARCHITECTURE.md`.
+- Do not add Click, Typer, import-linter, or release tooling beyond what is already documented.
+- Use Conventional Commits: `<type>(<scope>)<!>: <subject>`.
+- Append `!` for public API or store schema breaks.
+
+## Releases
+
+Do not hand-edit versions or release changelog entries; release-please owns them.

varve-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bob Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

varve-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: varve
+Version: 0.1.0
+Summary: A small Python library for experiment pipelines with code-aware materialized caching.
+Project-URL: Repository, https://github.com/moeakwak/varve
+Project-URL: Issues, https://github.com/moeakwak/varve/issues
+Project-URL: Changelog, https://github.com/moeakwak/varve/blob/main/CHANGELOG.md
+Author: Bob Wang
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic-settings[yaml]>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tqdm>=4.66.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# varve
+
+[![PyPI](https://img.shields.io/pypi/v/varve.svg)](https://pypi.org/project/varve/) [![License](https://img.shields.io/pypi/l/varve.svg)](LICENSE)
+
+Varve is a small Python library for running experiment pipelines as code. Each stage is a Python method, the run/status/plan/list/clean CLI is generated for you, and every output is cached under a key derived automatically from your code, config, and pinned inputs, so re-runs only re-execute what actually changed. Single machine, no daemon, no pipeline YAML.
+
+A varve is an annual layer of lake sediment: thin, ordered, and datable. This library uses the same idea for pipeline outputs: materialized layers whose keys record the code, config, inputs, and upstream layers that produced them.
+
+For the package layout, cache model, and edge-case behavior, see [ARCHITECTURE.md](ARCHITECTURE.md). For contribution guidance, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Quick start
+
+```python
+from pydantic import BaseModel
+from varve import Pipeline, stage
+
+
+class Config(BaseModel):
+    seed: int = 1
+
+
+class Demo(Pipeline):
+    Config = Config
+
+    @stage(produces="sample.txt")
+    def sample(self, ctx):
+        (ctx.out / "sample.txt").write_text(str(ctx.config.seed))
+
+
+if __name__ == "__main__":
+    raise SystemExit(Demo.cli())
+```
+
+Run the pipeline:
+
+```bash
+python demo.py run
+python demo.py status
+python demo.py plan
+python demo.py list
+python demo.py clean --yes
+```
+
+By default, outputs are written next to the pipeline module under `out/main/`. Use `--out PATH` to choose a different output base.
+
+## Batch stages
+
+Use `@batch_stage` for resumable batch work. The stage iterates through `ctx.resume(...)`, writes one or more files per item, and yields the paths it produced. If a run fails halfway through, the next run skips completed batch indexes and continues from the remaining items.
+
+```python
+from pathlib import Path
+
+from pydantic import BaseModel
+from varve import Ctx, Pipeline, batch_stage, stage
+
+
+class Config(BaseModel):
+    batch_size: int = 100
+
+
+class Args(BaseModel):
+    progress: bool = True
+
+
+class Demo(Pipeline):
+    Config = Config
+    Args = Args
+
+    @stage(produces="items.txt")
+    def prepare(self, ctx: Ctx[Config, Args]) -> None:
+        (ctx.out / "items.txt").write_text("alpha\nbeta\ngamma\n")
+
+    @batch_stage(needs="prepare", partition_key=("batch_size",))
+    async def process(self, ctx: Ctx[Config, Args]):
+        items = ctx.input("prepare").read_text().splitlines()
+        async for index, item in ctx.resume(items, progress=ctx.args.progress):
+            path = ctx.out / "parts" / f"{index:04d}.txt"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(item.upper())
+            yield path
+
+    @stage(needs="process", produces="summary.txt")
+    def summarize(self, ctx: Ctx[Config, Args]) -> None:
+        parts = [path.read_text() for path in ctx.inputs("process")]
+        (ctx.out / "summary.txt").write_text("\n".join(parts))
+```
+
+`ctx.input("stage")` returns exactly one upstream output path and fails if the stage produced zero or many paths. `ctx.inputs("stage")` always returns `list[Path]`. Both require the upstream stage to be declared in `needs=`, so the upstream content key is part of the downstream cache key.
+
+## Why varve
+
+Varve is for research and data-analysis pipelines where Python code is already the best source of truth. It is intentionally closer to a small library such as redun, Hamilton, or pydoit than to a workflow platform.
+
+Unlike DVC, varve is not data version control. Unlike Snakemake, it does not introduce a separate DSL. Unlike Prefect, Dagster, or Airflow, it has no scheduler service, worker fleet, or deployment model.
+
+The core design choices are:
+
+- **Pipelines are Python code.** Stages are instance methods, dependencies are declared with `needs=`, and semantic configuration is a pydantic model.
+- **Cache keys are code-aware by default.** Varve fingerprints stage source, automatically discovered project callables, full Config values, declared input files, declared JSON values, and upstream content keys.
+- **Outputs are materialized.** Successful stage records point at durable files under the output root, so missing artifacts are detected instead of silently treated as cache hits.
+- **Single machine, no service.** Varve uses an in-process runner and a file-system store. There is no daemon, database, or remote backend.
+
+## Features
+
+- Public API: `Pipeline`, `@stage`, `@batch_stage`, `KeySpec`, `Ctx`, `JSON`, and `StageSpec`.
+- Generated pipeline commands:
+  - `run [--branch NAME] [--override JSON] [--upto STAGE | --downstream STAGE] [--force] [--out PATH]`
+  - `status [--branch NAME] [--upto STAGE | --downstream STAGE] [--out PATH]`
+  - `plan [--upto STAGE | --downstream STAGE]`
+  - `list`
+  - `clean [--branch NAME] [--downstream STAGE] [--out PATH] [--yes]`
+- `run`, `status`, and `clean` also accept generated flags from the pipeline's `Args` model.
+- Cache states for hits, stale records, missing artifacts, dirty attempts, resumable batches, and unrecoverable partition changes.
+- `ctx.input(...)`, `ctx.inputs(...)`, and `ctx.resume(...)` for stage bodies.
+- `KeySpec.files` for pinning input file contents into the content key.
+
+## Branches
+
+`varve.yaml` lives next to the pipeline module. The `main` branch is the default and may rely entirely on Config defaults when the file is missing.
+
+Varve resolves the output root from `--out` or `Pipeline.default_output_root(config)`, then appends the selected branch:
+
+```text
+out/<branch>        # persistent branches
+out/.tmp/<branch>   # temporary override branches
+```
+
+Use `run --override '{"field": "value"}'` to deep-merge JSON over `main` and create a temporary branch. `status` and `clean` locate that branch later with `--branch NAME`.
+
+## Dashboard
+
+The top-level `varve` command discovers existing stores without requiring a custom dashboard entrypoint:
+
+```bash
+varve ls [--root DIR] [--include-temp]
+varve show <pipeline_id> [--root DIR] [--branch NAME] [--include-temp]
+varve refresh [--root DIR] [--prefix MODULE_PREFIX] [--include-temp]
+```
+
+Dashboard commands are secondary tooling. The primary interface remains each pipeline's generated CLI.
+
+## Platform support
+
+Varve is currently Unix-only. The output-root lock uses `fcntl`, so Windows support requires a future lock implementation.
+
+Source fingerprints use `ast.dump`. A CPython minor-version upgrade may invalidate stage source hashes and rebuild caches.
+
+## API stability
+
+Varve follows SemVer, but 0.x releases are alpha releases. Minor releases may include breaking changes to the public API or to the `.varve/` store schema. Read `CHANGELOG.md` before upgrading.
+
+## Non-goals
+
+- Remote storage or data version control.
+- Distributed scheduling or cluster execution.
+- Workflow platform, server, or DAG visualization service.
+- Cross-pipeline lineage or observability platform.
+
+## License
+
+MIT. See [LICENSE](LICENSE).