# Clarify checkpoint step count docs

`cddaed8`→[main](/content/gh/entireio/cli/commits/main/index.html)·

dipree·1mo ago·2 files·+21 added/-1 removed

## Sessions

29533fb28a76View transcript

## Changes

2

- cmd/entire/cli/checkpoint  
    - Mcheckpoint.go+3/-1
- docs/architecture  
    - Msessions-and-checkpoints.md+18

```
424 unmodified lines

425
426
427
428
428
429
430
431
432
433

424 unmodified lines

// CreatedAt is when the checkpoint was created
    CreatedAt time.Time

// CheckpointsCount is the total number of checkpoints across all sessions
    // CheckpointsCount is the aggregate displayed "steps" count across sessions:
    // the sum of per-session prompt-window counts. Despite the historical name,
    // it is not a count of checkpoint records.
    CheckpointsCount int

// FilesTouched are files modified during all sessions
```

Mcmd/entire/cli/checkpoint/checkpoint.go+3/-1

````
230 unmodified lines

231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254

230 unmodified lines

}
````

`checkpoints_count` in the root summary is the aggregate displayed "steps" count: the sum of per-session prompt-window counts. Despite the historical name, it is not a count of checkpoint records.

**Session-level metadata.json (`CommittedMetadata`, abbreviated):**

```json
{
  "checkpoint_id": "abc123def456",
  "session_id": "2025-12-01-8f76b0e8-b8f1-4a87-9186-848bdd83d62e",
  "strategy": "manual-commit",
  "created_at": "2025-12-01T12:34:56Z",
  "branch": "main",
  "checkpoints_count": 3,
  "save_step_count": 3,
  "files_touched": ["file1.txt", "file2.txt"]
}
```

In session metadata, `checkpoints_count` is the displayed prompt-window count for that session. `save_step_count` records SaveStep-created shadow-branch commits and is the conservative "real checkpoint work happened" signal; it is omitted when zero (for example, commit-only/fallback sessions). `save_step_count` is not aggregated into the root `CheckpointSummary`.

When condensing multiple concurrent sessions:
- All sessions are stored in numbered subdirectories using 0-based indexing (`0/`, `1/`, `2/`, ...)
- Each `session_id` is assigned a stable index; subsequent writes for the same session reuse the same numbered folder

```