Document git-refs Checkpoint Backend Architecture · Entire

can you check this repo and ../doc how are documentation for the new ref based backend is, and suggest improvements and explanation documents

1. Internal architecture docs (cli_experiments/docs/architecture/)

   • sessions-and-checkpoints.md: Covers ULID vs 12-hex IDs, kind-based read routing (kindRoutingStore), and generation well. But its two structural sections are still git-branch-only:
     • The Storage table lists shadow branch + entire/checkpoints/v1 and has no row for refs/entire/checkpoints/<shard>/<id>.
     • The Package Structure block predates the refs files entirely — no refs_store.go, pushqueue.go, registry.go, routing_store.go.
   • checkpoint-scenarios.md: zero ref-backend mentions.

2. Public docs (../docs/, Mintlify)

   • guides/checkpoints/overview.mdx: Says every checkpoint has a "12-character ID" (now wrong — ULIDs are 26 chars under git-refs).
   • glossary.mdx: Has "Checkpoints branch" and "Shadow branch" entries but nothing for git-refs.

The core gap

There is no document that explains the ref-based backend as a system — a reader has to reconstruct it from four scattered sources.

Proposed documents

New — internal (highest priority):

1. docs/architecture/ref-checkpoint-backend.md — the missing explanation doc. This is the one I'd write first.

Edits — internal: 2. sessions-and-checkpoints.md — add a refs/entire/checkpoints/ row to the Storage table. 3. checkpoint-scenarios.md — add a git-refs condensation + push/recovery scenario.

Edits — public: 4. overview.mdx — fix "12-character ID" → "short ID". 5. glossary.mdx — add entries for checkpoint backend / git-refs / primary+mirror.

What the v1 mirror push bullet point means

The scenario it's protecting against: downgrade safety.

• The catch is local vs. remote. The mirror fan-out writes v1 into the local object store, but the pre-push path never pushes it.
• The actual gap is that even with the configuration, the remote-push half is deferred.

Proposed action

I can tighten the bullet in the doc to spell out the local-written-but-not-pushed distinction, which is the part most likely to be misread.

Summary of changes

• Taxonomy note — Compatibility is read routing + version policy across all readers, not dual-writing.
• Config example — refs-only, no mirrors block.
• Known limitations — removed the "v1 mirror push for downgrade safety" bullet entirely.

Remaining items

• The only remaining items from the original plan are in ../docs (public site), so they're outside "this repo":
  • guides/checkpoints/overview.mdx — stale "12-character ID" line.
  • glossary.mdx — missing git-refs / backend / primary-mirror entries.

Final Thoughts

The read routing already delivers exactly "write once, read from both"; no need for mirroring since it under-delivers today.

Want me to check the server-side to see how checkpoints are read? That would settle it.