docs: update CLI and examples for snapshot save/check workflow

Author: akhundMurad

docs/ci-integration.md

@@ -221,15 +221,23 @@ repos:
 Add Pacta to your Makefile for easy local runs:
 
 ```makefile
-.PHONY: arch arch-baseline
+.PHONY: arch arch-snapshot arch-check arch-baseline arch-ci
 
-# Run architecture check
+# Full scan (snapshot + check in one step)
 arch:
 	pacta scan . --model architecture.yml --rules rules.pacta.yml
 
+# Two-step workflow
+arch-snapshot:
+	pacta snapshot save . --model architecture.yml
+
+arch-check:
+	pacta check . --rules rules.pacta.yml
+
 # Update baseline
 arch-baseline:
-	pacta scan . --model architecture.yml --rules rules.pacta.yml --save-ref baseline
+	pacta snapshot save . --model architecture.yml --ref baseline
+	pacta check . --ref baseline --rules rules.pacta.yml
 
 # Check against baseline (CI mode)
 arch-ci:

docs/cli.md

@@ -63,9 +63,9 @@ Violations are displayed with human-readable explanations:
 
 ## check
 
-Evaluate architectural rules against an existing snapshot.
+Evaluate architectural rules against an existing snapshot and write violations back into it.
 
-This separates the "capture" step (`snapshot save`) from the "verify" step (`check`), allowing you to snapshot your architecture once and check it against different rule sets or at different times.
+This separates the "capture" step (`snapshot save`) from the "verify" step (`check`), allowing you to snapshot your architecture once and check it against different rule sets or at different times. The existing snapshot object is updated in-place — no new snapshot is created.
 
 ```bash
 pacta check [PATH] [OPTIONS]

docs/getting-started.md

@@ -38,7 +38,7 @@ containers:
 Now capture a snapshot:
 
 ```bash
-pacta snapshot . --model architecture.yml
+pacta snapshot save . --model architecture.yml
 ```
 
 Pacta just analyzed every module and dependency in your codebase and stored a content-addressed snapshot in `.pacta/`. This snapshot is immutable — a permanent record of your architecture at this moment.
@@ -50,7 +50,7 @@ Pacta just analyzed every module and dependency in your codebase and stored a co
 A week passes. Your team ships features, fixes bugs, refactors code. Run another snapshot:
 
 ```bash
-pacta snapshot . --model architecture.yml
+pacta snapshot save . --model architecture.yml
 ```
 
 Now you have two points in time. See what changed:
@@ -149,12 +149,19 @@ Two violations. But wait — this is a legacy codebase. You can't fix everything
 Save the current state as a baseline:
 
 ```bash
+# One-step:
 pacta scan . --model architecture.yml --rules rules.pacta.yml --save-ref baseline
+
+# Or two-step:
+pacta snapshot save . --model architecture.yml --ref baseline
+pacta check . --ref baseline --rules rules.pacta.yml
 ```
 
-Now future scans compare against this baseline:
+Now future checks compare against this baseline:
 
 ```bash
+pacta check . --rules rules.pacta.yml --baseline baseline
+# Or equivalently:
 pacta scan . --model architecture.yml --rules rules.pacta.yml --baseline baseline
 ```
 

examples/README.md

@@ -22,7 +22,13 @@ To run any example:
 
 ```bash
 cd examples/<example-name>
+
+# One-step (scan = snapshot + check):
 pacta scan . --model architecture.yml --rules rules.pacta.yml
+
+# Or two-step:
+pacta snapshot save . --model architecture.yml
+pacta check . --rules rules.pacta.yml
 ```
 
 ## Creating Your Own