feat(snapshots): record immutable run snapshots

CONTRIBUTING.md

@@ -19,7 +19,13 @@ Thanks for your interest in contributing.
 1. Create a feature branch.
 2. Make focused changes.
 3. Add or update tests.
-4. Run checks before opening a PR:
+4. Before every commit, run the full test suite and demo smoke checks:
+   ```bash
+   uv run pytest tests/ -v
+   uv run synix demo run templates/01-chatbot-export-synthesis
+   uv run synix demo run templates/05-batch-build
+   ```
+5. Run the full release checks before opening a PR:
    ```bash
    uv run release
    ```

README.md

@@ -50,9 +50,17 @@ Browse, search, and validate:
 uvx synix list                    # all artifacts, grouped by layer
 uvx synix show final-report       # render an artifact
 uvx synix search "hiking"         # full-text search
+uvx synix runs list               # immutable artifact snapshots for this project
+uvx synix runs list --json        # machine-readable snapshot history (schema_version + runs[])
 uvx synix validate                # run declared validators (experimental)
 ```
 
+Successful builds record canonical immutable artifact snapshots under `.synix/`. The local `build/` directory still exists as the default compatibility materialization surface for current commands and demos, but it is no longer the source of truth for build history. Projection release state remains in that local surface until the explicit `release`/adapter slice lands. `uvx synix clean` only removes the mutable local surface; it does not delete snapshot history.
+
+> **Note:** The `.synix` on-disk snapshot format is new in `v0.15.x` and may evolve before `v1.0`. Objects are schema-versioned, and future changes will preserve a compatibility path rather than silently reusing incompatible state.
+
+> **Note:** Run refs currently use opaque, time-prefixed ids (for example `refs/runs/20260306T082007123456Z-1f2e3d4c`) and remain experimental before `v1.0`. Prefer `uvx synix runs list --json` over scraping the table output; the JSON shape is versioned as `{ "schema_version": 1, "runs": [...] }`.
+
 ## Defining a Pipeline
 
 A pipeline is a Python file. Layers are real objects with dependencies expressed as object references.
@@ -141,6 +149,7 @@ Pre-built transforms for common agent memory patterns. Import from `synix.transf
 | `uvx synix build` | Run the pipeline. Only rebuilds what changed |
 | `uvx synix plan` | Dry-run — show what would build without running transforms |
 | `uvx synix plan --explain-cache` | Plan with inline cache decision reasons |
+| `uvx synix runs list` | List immutable build snapshots recorded under `.synix` |
 | `uvx synix list [layer]` | List all artifacts, optionally filtered by layer |
 | `uvx synix show <id>` | Display an artifact. Resolves by label or ID prefix. `--raw` for JSON |
 | `uvx synix search <query>` | Full-text search. `--mode hybrid` for semantic |

docs/DESIGN.md

@@ -106,6 +106,17 @@ Synix gives you: edit the pipeline definition, run it again, and your same raw d
 
 The name "Synix" comes from **synthesis** — the core action of transforming raw information into processed understanding. In chip design, synthesis turns high-level descriptions into gate-level implementations. In software, build systems turn source files into artifacts. Synix does the same for agent memory: sources become artifacts through declared build rules, with full lineage tracking and incremental rebuilds.
 
+### 1.5 Immutable Build History
+
+As of the snapshotting work in `v0.15.x`, Synix distinguishes between:
+
+- the **mutable local build surface** (`build/`), which current commands and demos still use as a compatibility materialization target
+- the **immutable canonical history** (`.synix/`), which stores content-addressed objects, manifests, snapshots, and refs
+
+This split is intentional. Build history should survive `synix clean`, and future release targets should be materialized from immutable snapshot state rather than treated as the source of truth.
+
+The first shipped slice records **artifact snapshots only**. Projection/release state is still materialized into the local build surface until the explicit release/adapter layer lands.
+
 ---
 
 ## Part II: Conceptual Grounding