feat: live R3F effort graph viz with SSE subscriptions

.flatbread-efforts/decisions/dec-brand-the-agent-memory-surface-as-crumb-trail--tngncepdbwjkh9jc.md

@@ -9,6 +9,8 @@ derives_from:
   - fnd-workshop-shortlist-favors-crumb-graph-over-yeast--tv3ydt3wfb3n4y0g
 supersedes:
   - dec-brand-the-agent-memory-surface-as-crumb-graph--fvskcvagx3a7sybe
+superseded_by:
+  - dec-keep-effort-graph-as-the-product-name--r5wr2vdjwjs9bs13
 ---
 
 Supersedes Crumb Graph as the product name. Same system and deferred implementation; product brand is now Crumb Trail, with Crumb Graph retained as the datamodel explainer.

.flatbread-efforts/decisions/dec-keep-effort-graph-as-the-product-name--r5wr2vdjwjs9bs13.md

@@ -0,0 +1,43 @@
+---
+id: dec-keep-effort-graph-as-the-product-name--r5wr2vdjwjs9bs13
+effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz
+title: Keep Effort Graph as the product name
+state: accepted
+created_at: '2026-07-26T03:27:20.788Z'
+derives_from:
+  - fnd-crumb-rebrand-refuted-in-review-effort-graph-is--n8kb269z7vz8jhyk
+supersedes:
+  - dec-brand-the-agent-memory-surface-as-crumb-trail--tngncepdbwjkh9jc
+---
+
+Supersedes Crumb Trail (and, transitively, Crumb Graph). The rebrand line is refuted: **Effort Graph** is the product name for Flatbread's longform agent memory, and crumb naming is dropped entirely rather than retained as a datamodel explainer.
+
+## Context
+
+Two prior Decisions moved the brand from Effort Graph to Crumb Graph and then to Crumb Trail, each time deferring the package, CLI, path, and skill renames. Review of the accumulated naming stack found the crumb metaphor works against the product: crumbs connote leftovers in a system whose pitch is durable, trustworthy reasoning, and _crumb trail_ is already taken by breadcrumb navigation in UI vocabulary. Meanwhile every identifier a user touches — `@flatbread/effort-graph`, `flatbread effort`, `.flatbread-efforts/`, the `effort-graph` skill — still said Effort.
+
+## Decision
+
+Adopt **Effort Graph** as the product name, not merely an allowed technical descriptor. Retire **Crumb Graph** and **Crumb Trail**; neither is a product name, a datamodel explainer, nor a documented alias.
+
+Describe the datamodel in plain terms — Effort-scoped relational records with typed edges and bounded digests — instead of coining a second branded layer for it.
+
+No rename work is required or deferred: code, packages, CLI, paths, and skills already match the product name, and that alignment is now the point rather than a coincidence.
+
+## Alternatives considered
+
+- **Keep Crumb Trail as the brand and finally execute the renames.** Rejected: it pays a full breaking-rename cost to buy a metaphor that review judged actively misleading.
+- **Keep Crumb Trail for marketing, Effort Graph in code.** Rejected: this is the status quo the prior Decisions created, and it is the failure mode — a permanent gap between what the docs call the product and what every command and import path calls it.
+- **Keep Crumb Graph as a datamodel explainer only.** Rejected: a second branded vocabulary for the same graph adds a translation step without adding precision over saying Effort-scoped records and edges.
+- **Pick a third unleavened, Proof-peer name.** Rejected for now: naming churn has already cost two Decisions and two stale Issues, and no candidate beats the name that the API already teaches.
+
+## Consequences
+
+- Docs, skills copy, and product messaging use Effort Graph with no crumb aliases; existing crumb references are wording bugs to fix, not variants to preserve.
+- The rename Issues under this Effort close as wontfix — the work is cancelled, not postponed.
+- Brand and implementation vocabulary are unified, so future naming pressure has to argue for renaming real identifiers rather than only marketing copy.
+- Flatbread gives up a bread-metaphor peer to Proof for this surface. That is accepted: primitive fidelity beats metaphor symmetry here.
+
+## Reversal criteria
+
+Revisit only if Effort Graph measurably fails external comprehension — for example if users read Effort as project-management effort tracking or story points rather than a thread of work — and a candidate name wins while committing to rename the packages, CLI, and paths in the same Decision rather than deferring them again.

.flatbread-efforts/findings/fnd-crumb-rebrand-refuted-in-review-effort-graph-is--n8kb269z7vz8jhyk.md

@@ -0,0 +1,30 @@
+---
+id: fnd-crumb-rebrand-refuted-in-review-effort-graph-is--n8kb269z7vz8jhyk
+effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz
+title: Crumb rebrand refuted in review; Effort Graph is the retained name
+kind: dead-end
+created_at: '2026-07-26T03:26:52.792Z'
+derives_from:
+  - fnd-postable-brand-names-favor-trail-over-graph--zzpgaw0kvqtaqmxt
+  - fnd-workshop-shortlist-favors-crumb-graph-over-yeast--tv3ydt3wfb3n4y0g
+---
+
+## What happened
+
+The Crumb Graph → Crumb Trail branding line was grilled in review and refuted. The owner call is to keep **Effort Graph** as the product name for Flatbread's longform agent memory, not as a fallback technical alias.
+
+## Why the rebrand did not hold
+
+- **Crumb reads as leftovers, not memory.** In a product about durable reasoning, the metaphor undercuts the value claim: crumbs are what falls off the loaf, not the record you are meant to trust.
+- **Crumb collides with breadcrumbs.** In UI vocabulary a crumb trail is a navigation path widget. Users landing on the docs pattern-match to breadcrumb navigation before they reach agent memory.
+- **Effort Graph already names the load-bearing primitive.** Every record belongs to exactly one Effort. A brand that hides the Effort primitive forces a second vocabulary on top of the one the API, CLI, and skills already teach.
+- **The rebrand's own reversal criteria fired.** Both prior Decisions listed external-comprehension failure and crumb ≈ breadcrumbs/scraps confusion as revisit triggers. Review found exactly those failures, so the Decisions closed themselves out on their stated terms.
+- **Deferring implementation hid the cost.** Both Decisions deferred the package/CLI/path/skill renames, which kept the accepted brand permanently out of sync with every identifier a user actually touches.
+
+## Standing evidence
+
+The two workshop Findings remain accurate as records of what those exercises produced — the shortlist did favor crumb over yeast metaphors, and trail did test as more postable than graph. Neither is invalidated. What is refuted is treating brandability as decisive over primitive fidelity and collision risk.
+
+## Consequence
+
+The rename work tracked by both implementation Issues is a dead end and should close as wontfix rather than stay open as latent debt.

.flatbread-efforts/findings/fnd-supersession-transitions-decision-state-on-the-r--2m807tcfjz2jz9gt.md

@@ -0,0 +1,33 @@
+---
+id: fnd-supersession-transitions-decision-state-on-the-r--2m807tcfjz2jz9gt
+effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002
+title: >-
+  Supersession transitions Decision state on the retro-link path but not on
+  create
+kind: survey
+created_at: '2026-07-26T05:06:57.371Z'
+---
+
+## Observation
+
+`packages/effort-graph/src/planner.ts` has two code paths that create a `supersedes` edge, and they disagree about whether the superseded Decision changes state.
+
+- **Retro-link (`Supersede` mutation), planner.ts ~195-215.** When the target is a Decision it composes `supersedeDecisionLifecycle(snapshot, b.id).nextFrontmatter`, which sets `state: 'superseded'`, then appends the `superseded_by` back-pointer.
+- **Inline on create (`WriteDecision` with `supersedes: [...]`), planner.ts ~127-160.** The generic forward-edge loop only appends the `superseded_by` reverse projection. It never consults `supersedeDecisionLifecycle` and never touches `state`.
+
+## Evidence
+
+Two records in this repo's own graph show the create-path outcome — both carry `superseded_by` while still reporting `state: accepted`:
+
+- `dec-brand-the-agent-memory-surface-as-crumb-graph--fvskcvagx3a7sybe`
+- `dec-brand-the-agent-memory-surface-as-crumb-trail--tngncepdbwjkh9jc`
+
+`DecisionFrontmatterSchema` in `schemas.ts` already admits `'superseded'`, and `decision-lifecycle.ts` exists to produce it, so this is an inconsistency between the two paths rather than a deliberate modelling choice.
+
+The blind spot is a test gap: the planner suite covers the create path with `supersedes` only for Findings, which have no state field, so the Decision case is unexercised.
+
+## Why it matters beyond cosmetics
+
+- `planner.ts` gates `MitigateRisk` on `state !== 'accepted'`, so a superseded Decision can currently mitigate a Risk.
+- `flatbread effort records --state accepted` returns retired Decisions.
+- Consumers reading `state` directly label retired reasoning as committed. `examples/effort-viz` now carries a dedicated module (`lib/lifecycle.ts`) that derives effective lifecycle from edges specifically to work around this.

.flatbread-efforts/issues/iss-implement-crumb-graph-rename-across-packages-cli--dp6jvt2kafab7m4t.md

@@ -3,16 +3,20 @@ id: iss-implement-crumb-graph-rename-across-packages-cli--dp6jvt2kafab7m4t
 effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz
 title: 'Implement Crumb Graph rename across packages, CLI, paths, and skills'
 kind: gap
-status: open
+status: wontfix
 created_at: '2026-07-19T03:45:50.712Z'
 derives_from:
   - dec-brand-the-agent-memory-surface-as-crumb-graph--fvskcvagx3a7sybe
 superseded_by:
   - iss-implement-crumb-trail-rename-across-packages-cli--316rdzpt80sdxkw1
+resolved_by:
+  - dec-keep-effort-graph-as-the-product-name--r5wr2vdjwjs9bs13
 ---
 
 Branding Decision accepts Crumb Graph as the product name with Effort Graph as descriptor. Implementation is pending and out of scope for the branding commit.
 
 Likely touchpoints (non-exhaustive): `@flatbread/effort-graph`, `effortGraphContent`, `flatbread effort` CLI, `.flatbread-efforts/`, `.flatbread/effort-graph/`, agent skill name/paths, docs/README copy, error codes (`EFFORT_GRAPH_*`), and dogfood references.
 
 Do not start the mechanical rename until an implementation plan chooses which identifiers move vs stay for compatibility.
+
+Resolution: cancelled as `wontfix`; product name is Effort Graph; resolved by `dec-keep-effort-graph-as-the-product-name--r5wr2vdjwjs9bs13`; do not reopen rename work.

.flatbread-efforts/issues/iss-implement-crumb-trail-rename-across-packages-cli--316rdzpt80sdxkw1.md

@@ -3,16 +3,20 @@ id: iss-implement-crumb-trail-rename-across-packages-cli--316rdzpt80sdxkw1
 effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz
 title: 'Implement Crumb Trail rename across packages, CLI, paths, and skills'
 kind: gap
-status: open
+status: wontfix
 created_at: '2026-07-19T03:54:27.962Z'
 derives_from:
   - dec-brand-the-agent-memory-surface-as-crumb-trail--tngncepdbwjkh9jc
 supersedes:
   - iss-implement-crumb-graph-rename-across-packages-cli--dp6jvt2kafab7m4t
+resolved_by:
+  - dec-keep-effort-graph-as-the-product-name--r5wr2vdjwjs9bs13
 ---
 
 Supersedes the Crumb Graph rename Issue. Branding now targets Crumb Trail as the product name (Crumb Graph = datamodel explainer; Effort Graph = technical descriptor).
 
 Implementation remains pending. Likely touchpoints (non-exhaustive): `@flatbread/effort-graph`, `effortGraphContent`, `flatbread effort` CLI, `.flatbread-efforts/`, `.flatbread/effort-graph/`, agent skill name/paths, docs/README copy, error codes (`EFFORT_GRAPH_*`), and dogfood references.
 
 Do not start the mechanical rename until an implementation plan chooses which identifiers move vs stay for compatibility, and how Crumb Trail / Crumb Graph / Effort Graph map onto public vs internal names.
+
+Resolution: cancelled as `wontfix`; product name is Effort Graph; resolved by `dec-keep-effort-graph-as-the-product-name--r5wr2vdjwjs9bs13`; do not reopen rename work.

.flatbread-efforts/issues/iss-writedecision-with-supersedes-leaves-the-superse--by624gyf21ex42sv.md

@@ -0,0 +1,26 @@
+---
+id: iss-writedecision-with-supersedes-leaves-the-superse--by624gyf21ex42sv
+effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002
+title: WriteDecision with supersedes leaves the superseded Decision in state accepted
+kind: defect
+status: open
+created_at: '2026-07-26T05:07:15.240Z'
+derives_from:
+  - fnd-supersession-transitions-decision-state-on-the-r--2m807tcfjz2jz9gt
+---
+
+## Problem
+
+Creating a Decision with an inline `supersedes` edge appends the `superseded_by` reverse projection to the target but leaves its `state` untouched, so a replaced Decision keeps reporting `state: accepted`. The `Supersede` retro-link mutation on the same target does set `state: superseded`. Same semantic act, two different outcomes depending on which mutation got there first.
+
+## Fix sketch
+
+In the create-path forward-edge loop in `packages/effort-graph/src/planner.ts`, when `edge === 'supersedes'` and the target is a Decision, compose `supersedeDecisionLifecycle(snapshot, target.id).nextFrontmatter` before appending the back-pointer — the same composition the `Supersede` branch already performs. Add a planner test mirroring the existing retro-link supersession test but driven through `WriteDecision`, since the current create-path test only covers Findings and so cannot catch this.
+
+## Repair
+
+Two records in this repo already carry the bad shape (`dec-brand-the-agent-memory-surface-as-crumb-graph--fvskcvagx3a7sybe`, `dec-brand-the-agent-memory-surface-as-crumb-trail--tngncepdbwjkh9jc`). Repair them through the reindexer rather than by hand-editing frontmatter.
+
+## Scope note
+
+Consumers should keep deriving supersession from edges regardless of the fix: forward edges are the authoritative representation, and edge-derived state also covers legacy and hand-edited records. `examples/effort-viz/lib/lifecycle.ts` does this and should not be reverted once the writer is corrected.

.gitignore

@@ -15,4 +15,6 @@
 yarn-error.log
 .pnpm-debug.log
 **/.flatbread-efforts/.journal/
-**/.flatbread/effort-graph/read-cache/
+**/.flatbread/effort-graph/read-cache/
+# proof / local DAG artifacts
+.flatbread/artifacts/

CONTRIBUTING.md

@@ -35,6 +35,7 @@ Optional **`pnpm play`** from the repo root is a shortcut for **`cd examples/nex
 - Build all packages: `pnpm build`
 - **Workspace libraries (watch-only):** `pnpm dev` — runs package `dev` scripts (e.g. `tsup --watch`) for `packages/*`; it does **not** start the Next.js example.
 - **Next.js example:** prefer the flow under [Recommended onboarding](#recommended-onboarding-try-flatbread-in-the-nextjs-example); or `pnpm play` as a convenience alias.
+- **Effort Graph viz (`examples/effort-viz`):** after `pnpm build`, run `pnpm play:efforts` (or `pnpm --filter effort-viz dev`) to dogfood `.flatbread-efforts` with live SSE updates — see that example's README.
 - Check local CI parity before opening a PR: `pnpm verify`
 
 ## Working on a package

examples/effort-viz/.gitignore

@@ -0,0 +1,42 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+.flatbread-codegen-cache.json
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts