# docs: clarify the git-refs vs git-branch base-path difference

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

Soph·1w ago·1 file·+1 added/-1 removed

The write-path paragraph described the shared treeWriter as "anchored at base path \"\"", which is both awkward and slightly wrong — basePath is a per-write argument, not a property of the treeWriter. Explain it in words: git-branch writes each checkpoint under its <id\[:2\]>/<id[2:\]>/ shard prefix inside the one v1 tree, while git-refs writes with no prefix so the checkpoint subtree is the root of its own per-checkpoint commit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

## Sessions

01KX3B0P27TWE3S04XQGRR8M1JView transcript

## Changes

1

- docs/architecture

- Mref-checkpoint-backend.md+1/-1

## Write path

The git-refs store (`gitRefsStore`, `checkpoint/refs_store.go`) shares the checkpoint-subtree machinery with the git-branch store via an embedded `*treeWriter` anchored at base path `""`. The two differ only in **where the subtree is committed**: a per-checkpoint ref instead of a subtree of the v1 branch.
The git-refs store (`gitRefsStore`, `checkpoint/refs_store.go`) shares the checkpoint-subtree machinery with the git-branch store via an embedded `*treeWriter`. Both build the exact same checkpoint subtree; they differ only in the **base path** they write it at and in **where the result is committed**. The git-branch store writes each checkpoint under its shard prefix `<id[:2]>/<id[2:]>/` inside the single `v1` tree, so many checkpoints share one tree. The git-refs store writes with **no prefix** (an empty base path), so the checkpoint subtree *is* the root of that checkpoint's own commit tree, and the commit is the tip of a per-checkpoint ref rather than a subtree of the v1 branch.

Every persistent write (`WriteSession`, and the `Backfill*` operations for transcript / summary / attribution) follows the same shape: