docs: add transactions.md — branch-as-transaction explainer

[ragnorc]

Summary

Adds docs/transactions.md — a user-facing explainer for the atomicity model. The architectural rule lives in docs/invariants.md §VI.23 ("no cross-query BEGIN/COMMIT; branches fill that role") but isn't surfaced anywhere a user looking at docs/query-language.md would find it. New users coming from Postgres/MySQL trip over the gap when they realize multiple queries on main publish independently.

The new page covers:

• The atomicity model — per-query atomic; branches as multi-query transactions.
• Comparison table to traditional BEGIN/COMMIT.
• Four worked examples:
  1. Single-query multi-statement (atomic by default).
  2. Two separate queries on main (NOT atomic — common surprise).
  3. Many queries via a branch (atomic at merge).
  4. Coordinating multiple agents via branch-per-agent.
• Failure modes table.
• "When to use what" decision matrix.
• Explicit "what this can't do" section (cross-graph transactions, long-running interactive sessions, pessimistic locks).

Why now

Came up during MR-794 / PR #68 review when I asked whether the D₂ parse-time rule (rejecting mixed insert/update + delete in one query) hinted at a missing transaction concept. The answer is no — the model deliberately replaces transactions with branches — but the deliberate replacement isn't documented anywhere a user would find it.

Independent of #68. Doesn't reference any MR-794 specifics; the branch-as-transaction model is invariant across MR-794 and predates it.

Test plan

• scripts/check-agents-md.sh passes (27 links, 27 docs)
• Render the page on a PR preview / locally — confirm the tables and code blocks render cleanly
• Skim for tone consistency with the rest of docs/

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only change that adds a new guide page and updates the docs index; no runtime behavior or APIs are modified.

Overview
Adds a new docs/transactions.md page that explains OmniGraph’s transaction/atomicity model: single .gq queries are atomic, and multi-query workflows use branches + merge instead of BEGIN/COMMIT.

Updates AGENTS.md to link the new transactions guide from the docs index, making the “branches as transactions” invariant easier to discover.

^{Reviewed by Cursor Bugbot for commit 52cb3f1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cubic-dev-ai]

No issues found across 2 files