Paragraphs: extend_scene, references that bind to earlier items, and a bind change

From QA round 10 (paragraph experiments) and the user's choice of defaults:
- "the cat" when a cat already exists refers to it instead of making a twin,
surfaced as "which cat? the one already mentioned". "a/an/another cat"
always makes a new one. Fixes the twin-cat scene where the apple sat
beside a second cat on the floor.
- Pronouns (it, he, she, they, him, her, them) are words now: they refer to
the most recent object (not the clause's own subject), surfaced as
"'it' = the table?" with the alternatives.
- extend_scene(ledger, sentence, ...) adds the next sentence to a ledger.
- refine_scene takes {"id": "q10", "bind": "n1"} to rebind a reference and
{"id": "n12", "bind": "n1"} to merge a duplicate, with a resolution note.

Tested with a stub dictionary: one sentence with the cat twice, pronoun
across sentences, rebind, another cat, duplicate merge, self-relation
refused, pronoun with nothing before it, light question dropped.

Also archives QA rounds 9-10.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

SPEC.md

@@ -103,6 +103,29 @@ Relations: `on, under, beside, near, behind, in_front_of, above, faces, lights`.
 Verbs: `sat/stood/lay/rested` → `on` (ground implied), `shone/glowed` → `lights`
 (shadows only turn on with this coupling), `faced` → `faces`.
 
+## Paragraphs: sentences + bindings
+
+`extend_scene` adds the next sentence to an existing ledger (token and item ids carry
+on, `sentences` lists them). Within a sentence or across sentences:
+
+- **"the <noun>"** when that noun is already in the ledger refers to it (the most
+  recent one) instead of adding an item. Surfaced as an implied question: "which cat?
+  the one already mentioned" (default: the same cat), alternatives include "say
+  'another cat' for a new one".
+- **"a/an/another <noun>"** always adds a new item.
+- **Pronouns** (it, he, she, they, him, her, them) refer to the most recent object,
+  leaving out the clause's own subject when the pronoun is its object ("the apple lay
+  beside it" can't mean the apple). Surfaced as "'it' = the table?", with the other
+  objects as alternatives, most recent first. A pronoun with nothing before it is an
+  error.
+- Each reference question carries `binds: {token, to}`; relations record which token
+  named each end (`tokens: {subject, object}`), so a reference can be rebound.
+- **`bind`** (a `refine_scene` change): `{"id": "q10", "bind": "n1"}` rebinds a
+  reference question; `{"id": "n12", "bind": "n1"}` merges a duplicate object into
+  another (relations move, its "which?" question goes, a light carries over). Both
+  refuse to relate an object to itself and add a note to `resolutions`.
+- "what light?" is asked once per ledger and dropped when a later sentence lights the scene.
+
 ## MCP tools
 
 | Tool | In → out |
@@ -110,6 +133,7 @@ Verbs: `sat/stood/lay/rested` → `on` (ground implied), `shone/glowed` → `lig
 | `check_words` | sentence, primitives → per-word status, missing words, completions |
 | `translate_to_scene` | sentence, primitives, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
 | `refine_scene` | ledger, changes, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
+| `extend_scene` | ledger, sentence, primitives, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
 | `simplify_item` | ledger, item id, html, rings, samples → report, rung PNGs, rung GLBs, mini HTML file, mini HTML text |
 | `papercraft_rings` | ledger, item id, rings, samples, height_cm → pieces report, PNG per A4 page (to look at), SVG per A4 page (mm, to print) |
 

app.py

@@ -157,6 +157,8 @@ def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0",
         {"id": "n1", "shape": "sphere"}   use a primitive (box, sphere, cylinder, cone, plane)
         {"reroll": true}                  every unfrozen object takes its next alternative;
                                           repeated rerolls visit the whole pool, whatever the seed
+        {"id": "n12", "bind": "n1"}       n12 is the same thing as n1: merged into it, its relations move
+        {"id": "q11", "bind": "n5"}       the word behind reference question q11 ("it", "the cat") means n5
     Frozen items cannot be changed. The configuration (placement, sun angle) is always
     re-chosen from `seed`: change the seed for another valid configuration.
 
@@ -179,6 +181,34 @@ def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0",
         _fail(e)
 
 
+def extend_scene(ledger_json: str, sentence: str, primitives_json: str = "{}", seed: str = "0",
+                 html: str = "url") -> tuple[str, str, str, str, str]:
+    """Add the next sentence of a paragraph to an existing scene.
+
+    Paragraphs are sentences plus bindings. "the cat" when a cat is already in the ledger,
+    and pronouns (it, he, she, they), refer back to an existing item instead of adding one;
+    each such reference is an implied question ("which cat? the one already mentioned",
+    "'it' = the cat?") whose `binds` names the item. Rebind with refine_scene
+    {"id": "<question id>", "bind": "<item id>"}. "a/an/another cat" always adds a new one.
+
+    Args:
+        ledger_json: Ledger JSON from translate_to_scene, refine_scene or a previous extend_scene.
+        sentence: The next sentence, e.g. "the apple lay beside it".
+        primitives_json: JSON object mapping missing words to shapes, as in translate_to_scene.
+        seed: Picks one of the configurations that satisfy the whole ledger.
+        html: "url" (default), "inline" or "skip", as in translate_to_scene.
+
+    Returns:
+        (ledger JSON string, rendered PNG, GLB scene file, mini HTML file, mini HTML text or "").
+    """
+    try:
+        ledger = _json(ledger_json, "ledger_json")
+        *rest, page = pipeline.extend(ledger, sentence, _json(primitives_json, "primitives_json", {}), _seed(seed))
+        return (*rest, *_html_out(page, html))
+    except Exception as e:
+        _fail(e)
+
+
 def simplify_item(ledger_json: str, item_id: str, html: str = "url", rings: str = "8",
                   samples: str = "16") -> tuple[str, list, list, str, str]:
     """Build the simplification ladder for one object: full asset -> fewer faces -> rings -> convex hull -> box.
@@ -382,6 +412,9 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
         ledger = gr.Code(label="Ledger", language="json", interactive=True)
         changes = gr.Code(label="Changes", language="json", value=EXAMPLE_CHANGES, interactive=True)
         refine = gr.Button("Refine")
+        with gr.Row():
+            next_sentence = gr.Textbox(label="Next sentence (refers back: 'the cat', 'it')", scale=4)
+            extend = gr.Button("Add sentence", scale=1)
     with gr.Accordion("Simplification ladder", open=False):
         with gr.Row():
             item_id = gr.Textbox(label="Object item id", value="n1")
@@ -412,6 +445,9 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
     refine.click(refine_scene, [ledger, changes, seed, html_mode],
                  [ledger, picture, model, scene_file, scene_html], api_name="refine_scene") \
         .then(_html_preview, scene_file, scene_preview, api_visibility="private")
+    extend.click(extend_scene, [ledger, next_sentence, primitives, seed, html_mode],
+                 [ledger, picture, model, scene_file, scene_html], api_name="extend_scene") \
+        .then(_html_preview, scene_file, scene_preview, api_visibility="private")
     simp.click(simplify_item, [ledger, item_id, html_mode, ring_count, ring_samples],
                [ladder_report, ladder_pics, ladder_files, ladder_file, ladder_html], api_name="simplify_item") \
         .then(_html_preview, ladder_file, ladder_preview, api_visibility="private")

feedback/vli-qa-feedback-2026-10-30.md

@@ -182,3 +182,27 @@ Note: apple `b01` is a reddish-brown (#b27045) — "a green apple" still means w
 - **Bug: `top cap` has `glues_to: []`** — its glue edge to band 7 is missing from the assembly graph (bottom cap correctly glues to band 1). Small fix in the glue-path builder; an assembler would otherwise hold an unlabeled lid.
 
 > Note (agent): not a missing edge — tabs sit on one side of each joint, and the top cap's are on band 7's top edge. The report listed only outgoing tabs; it now also lists `receives_from`, so the top cap shows band 7a–7c.
+
+Remaining open: the `use`-back-swap check after skip-shifted indices, and the UI visual click-tests (mode radio, preview-from-file, papercraft download). The sentence → scene → ladder → printable-kit loop is now complete and demo-ready end to end.
+
+---
+
+## 10. Paragraph / disambiguation experiments (2026-10-30) — the next frontier, probed live
+
+The goal going forward is the **learning-disambiguation tool**: paragraphs and pages, where later sentences refer back to earlier entities. Four attempts:
+
+| # | Input | Result |
+|---|---|---|
+| 0 | `{"id":"n1","use":0}` on a pool with a skip-shifted index | ✓ chosen resolved to `alternatives[0]` correctly — `use` is sound. **Item closed** with the rule: indices are relative to the ledger you pass; callers must reuse the latest returned ledger. (UI click-tests also cleared by the reviewer.) |
+| 1 | `"the cat sat on the table and the apple lay beside the cat and the lamp glowed"` (raw, repeated noun) | Structure ✓ — three clauses in one ledger, all relations intact, lamp lights the scene. Semantics ✗ — **two cat items (n1, n12)**, two "which cat?" questions; "beside the cat" bound to the *ground-level* twin, so the apple sat on the floor while the real cat was on the table (render proves it: cat on tabletop, second cat + apple on the ground) |
+| 2 | `"…and the apple lay beside it…"` (pronoun) | ✗ hard fail: `Not available (no asset): it` — pronouns are unknown words |
+| 3 | Attempt 1 hand-resolved from chat: `r10` bound `n12 → n1`, duplicate item + its question deleted, provenance tokens blanked; re-rendered via `refine_scene` with empty changes | ✓ **coherent page**: one cat on the table, apple beside it at the cat's height (both y = 0.916 — the `beside` solver inherited the table level automatically), lamp glowing. The reference-driven solver follows the fix |
+
+**What this establishes:** the chat-side disambiguation loop works today with zero Space changes — *chat resolves, ledger persists, Space re-renders*. That is the learning-disambiguation tool's core loop, demonstrated.
+
+**Proposed Space changes to make it first-class (next push candidates):**
+1. **`{"id": "n12", "bind": "n1"}`** as a new change type — deletes the duplicate item, retargets all relations referencing it into the target, preserves token provenance (e.g. a `resolution: "n12 → n1 (same referent)"` note). Symmetric in spirit to `shape`/`reject`; hand-editing the ledger works but is error-prone and loses the resolution note.
+2. **`extend_scene(ledger, sentence)`** — build the new sentence's ledger with knowledge of the *existing* items: repeated determiner+noun proposes a bind instead of a duplicate (an implied question like `"which cat — the one on the table?"`), "another/a new" forces a fresh item. Pages then become incremental: one call per sentence, one shared ledger.
+3. Pronoun handling: keep in chat (per SPEC, discussion resolves), but `bind` gives the Space a primitive for it once chat names the referent. Worth a SPEC section: *paragraphs = sentences + bindings.*
+
+**Also observed:** Objaverse items now carry `color: null` (SimReady items have thumbnail-derived colours; Objaverse has no thumbnails in this pipeline — a future colour source for Objaverse would close the grey-Objaverse gap).

vli/grammar.py

@@ -4,12 +4,19 @@ serial ledger (the decisions reading hides, in reading order).
 Nouns come from the lexicon, verbs are relations between meshes, and glue
 words (the, a, and) commit no geometry -- determiners open a "which?" question.
 A word with no asset is not available unless the caller maps it to a primitive.
+
+Paragraphs are sentences plus bindings. "the <noun>" when that noun is already in
+the ledger, and pronouns (it, she, they...), refer back instead of adding an item;
+each reference is surfaced as an implied question the discussion can rebind.
+"a/an/another <noun>" always adds a new item.
 """
 import re
 
 from .lexicon import ASSET_TIERS, LEXICON, PRIMITIVE_SHAPES, TIERS
 
-DETERMINERS = {"the", "a", "an"}
+DETERMINERS = {"the", "a", "an", "another"}
+NEW_DETERMINERS = {"a", "an", "another"}  # always introduce a new item
+PRONOUNS = {"it", "he", "she", "they", "him", "her", "them"}
 CONJUNCTIONS = {"and", "then"}
 COPULAS = {"is", "was", "are", "were"}
 
@@ -35,7 +42,7 @@ DEFAULT_HEIGHT_M = 0.5
 
 
 def grammar_words():
-    return sorted(DETERMINERS | CONJUNCTIONS | COPULAS | set(VERBS) | set(PREPOSITIONS))
+    return sorted(DETERMINERS | CONJUNCTIONS | COPULAS | PRONOUNS | set(VERBS) | set(PREPOSITIONS))
 
 
 def parse_primitives(primitives):
@@ -80,6 +87,8 @@ def classify_phrase(text):
 def classify(word):
     if word in DETERMINERS:
         return "determiner"
+    if word in PRONOUNS:
+        return "pronoun"
     if word in CONJUNCTIONS:
         return "conjunction"
     if word in COPULAS:
@@ -137,23 +146,43 @@ def candidate_label(cand):
     return cand.get("name") or cand.get("category") or cand.get("shape") or cand.get("prompt") or "?"
 
 
-def build_ledger(sentence, primitives=None):
+def _reference_question(qid, token, word, target, others, determiner=None):
+    """An implied question for a word that refers back instead of adding an item."""
+    if determiner:
+        question, alt = f"which {word}? the one already mentioned", [f"say 'another {word}' for a new one"]
+    else:
+        question, alt = f"'{word}' = the {target['word']}?", []
+    return {"id": qid, "token": token["index"], "about": target["id"], "question": question,
+            "default_chosen": f"the {target['word']} ({target['id']})", "implied": True,
+            "alternatives": alt + [f"the {o['word']} ({o['id']})" for o in others],
+            "binds": {"token": token["index"], "to": target["id"]}}
+
+
+def build_ledger(sentence, primitives=None, prior=None):
+    """The ledger for one sentence. With `prior` (an existing ledger), token indices
+    continue after it and words can refer back to its objects; the result holds only
+    the new tokens, items and questions (extend_ledger merges them)."""
     primitives = parse_primitives(primitives)
     tokens = tokenize(sentence, primitives)
     unknown = [t["text"] for t in tokens if t["kind"] == "unknown"]
     if unknown:
         raise ValueError(f"Not available (no asset): {', '.join(unknown)}. "
                          f"Rephrase, or map each to a primitive: {PRIMITIVE_SHAPES}")
+    offset = len(prior["tokens"]) if prior else 0
     for t in tokens:
+        t["index"] += offset
         t["commits"], t["opens"] = [], []
 
     items, unresolved = [], []
-    by_id = {}
+    by_id = {i["id"]: i for i in prior["items"]} if prior else {}
+    objects = [i for i in prior["items"] if i["kind"] == "object"] if prior else []  # in reading order
 
     def add_item(item, token):
         items.append(item)
         by_id[item["id"]] = item
         token["commits"].append(item["id"])
+        if item["kind"] == "object":
+            objects.append(item)
         return item
 
     clauses, current = [], []
@@ -168,27 +197,47 @@ def build_ledger(sentence, primitives=None):
     pending_q = None
     for clause in clauses:
         subject, verb_rel, implied_obj, prep_rel, obj, verb_tok = None, None, None, None, None, None
+        subject_tok = obj_tok = None
         for t in clause:
             kind = t["kind"]
             if kind == "determiner":
-                pending_q = {"id": f"q{t['index']}", "token": t["index"], "about": None}
+                pending_q = {"id": f"q{t['index']}", "token": t["index"], "about": None, "determiner": t["text"]}
                 t["opens"].append(pending_q["id"])
                 unresolved.append(pending_q)
-            elif kind in ("noun", "primitive"):
-                # height is settled with the asset: metric for simready, nominal otherwise
-                item = add_item({"id": f"n{t['index']}", "kind": "object", "word": t["text"],
-                                 "token": t["index"],
-                                 "decision": _object_decision(t["text"], primitives.get(t["text"])),
-                                 "height_m": {"value": None, "source": "pending"},
-                                 "frozen": False}, t)
-                if pending_q is not None:
-                    pending_q["about"] = item["id"]
-                    pending_q["question"] = f"which {t['text']}?"
+            elif kind in ("noun", "primitive", "pronoun"):
+                in_object = subject is not None and (verb_rel is not None or prep_rel is not None)
+                if kind == "pronoun":
+                    pool = [o for o in objects if not (in_object and o is subject)]
+                    if not pool:
+                        raise ValueError(f"'{t['text']}' refers to nothing yet: name the object first")
+                    item = pool[-1]  # the most recent object it can mean
+                    q = _reference_question(f"q{t['index']}", t, t["text"], item, pool[-2::-1])
+                    t["opens"].append(q["id"])
+                    unresolved.append(q)
+                else:
+                    same = [o for o in objects if o["word"] == t["text"]]
+                    if same and pending_q is not None and pending_q["determiner"] not in NEW_DETERMINERS:
+                        item = same[-1]  # "the cat" again: the cat already mentioned
+                        others = [o for o in objects if o is not item][::-1]
+                        pending_q.update(_reference_question(pending_q["id"], t, t["text"], item, others,
+                                                             determiner=pending_q["determiner"]))
+                    else:
+                        # height is settled with the asset: metric for simready, nominal otherwise
+                        item = add_item({"id": f"n{t['index']}", "kind": "object", "word": t["text"],
+                                         "token": t["index"],
+                                         "decision": _object_decision(t["text"], primitives.get(t["text"])),
+                                         "height_m": {"value": None, "source": "pending"},
+                                         "frozen": False}, t)
+                        if pending_q is not None:
+                            pending_q["about"] = item["id"]
+                            pending_q["question"] = f"which {t['text']}?"
                     pending_q = None
-                if verb_rel is None and prep_rel is None:
-                    subject = item
+                if item["id"] not in t["commits"]:
+                    t["refers_to"] = item["id"]
+                if in_object:
+                    obj, obj_tok = item, t["index"]
                 else:
-                    obj = item
+                    subject, subject_tok = item, t["index"]
             elif kind == "verb":
                 verb_rel, implied_obj = VERBS[t["text"]]
                 verb_tok = t
@@ -221,14 +270,19 @@ def build_ledger(sentence, primitives=None):
             obj = {"id": "scene"}
         if obj is None:
             raise ValueError(f"'{relation}' needs an object noun")
+        if obj is subject:
+            raise ValueError(f"'{verb_tok['text']}' would relate the {subject['word']} to itself")
         add_item({"id": f"r{verb_tok['index']}", "kind": "relation", "relation": relation,
                   "subject": subject["id"], "object": obj["id"], "token": verb_tok["index"],
-                  "frozen": False}, verb_tok)
+                  "tokens": {"subject": subject_tok, "object": obj_tok}, "frozen": False}, verb_tok)
 
     for q in unresolved:
+        q.pop("determiner", None)
         if q["about"] is None:
             q["question"] = "determiner without a noun"
-    if not any(i.get("emits_light") for i in items):
+    lit = any(i.get("emits_light") for i in by_id.values())
+    asked = bool(prior) and any(q["id"] == "q_light" for q in prior["unresolved"])
+    if not lit and not asked:
         # Seeing needs light, as sitting needs a ground: unstated, so surfaced like the ground.
         unresolved.append({"id": "q_light", "token": None, "about": "light", "question": "what light?",
                            "default_chosen": "daylight", "implied": True,
@@ -237,6 +291,18 @@ def build_ledger(sentence, primitives=None):
             "tokens": tokens, "items": items, "unresolved": unresolved}
 
 
+def extend_ledger(ledger, sentence, primitives=None):
+    """Add a sentence to a ledger: the next sentence of a paragraph."""
+    prims = {**ledger.get("primitives", {}), **parse_primitives(primitives)}
+    new = build_ledger(sentence, prims, prior=ledger)
+    lit = any(i.get("emits_light") for i in ledger["items"] + new["items"])
+    unresolved = [q for q in ledger["unresolved"] + new["unresolved"] if not (lit and q["id"] == "q_light")]
+    return {**ledger, "sentence": ledger["sentence"].rstrip(" .") + ". " + sentence.strip(),
+            "sentences": ledger.get("sentences", [ledger["sentence"]]) + [sentence.strip()],
+            "primitives": prims, "tokens": ledger["tokens"] + new["tokens"],
+            "items": ledger["items"] + new["items"], "unresolved": unresolved}
+
+
 def check_words(sentence, primitives=None):
     """Per-word status, the words with no asset, and completions for the word being typed."""
     primitives = parse_primitives(primitives)

vli/pipeline.py

@@ -8,7 +8,8 @@ import os
 import tempfile
 
 from . import assets, html, scene
-from .grammar import POOL, build_ledger, candidate_label, next_tier, parse_primitives, primitive_candidate
+from .grammar import (POOL, build_ledger, candidate_label, extend_ledger, next_tier, parse_primitives,
+                      primitive_candidate)
 from .lexicon import ASSET_TIERS, LEXICON
 
 
@@ -45,6 +46,8 @@ def settle_all(ledger):
             meshes[it["id"]] = assets.scene_mesh(full)
             it["decision"]["label"] = candidate_label(it["decision"]["chosen"])
     for q in ledger["unresolved"]:
+        if q.get("binds"):
+            continue  # a reference: which item a word means, not which asset
         about = next((i for i in ledger["items"] if i["id"] == q.get("about")), None)
         if about and about["kind"] == "object":
             q["default_chosen"] = _option_label(about["decision"]["chosen"])
@@ -67,6 +70,67 @@ def translate(sentence, primitives=None, seed=0):
     return outputs(build_ledger(sentence, primitives), seed)
 
 
+def extend(ledger, sentence, primitives=None, seed=0):
+    return outputs(extend_ledger(ledger, sentence, primitives), seed)
+
+
+def _bind(ledger, src, dst):
+    """Two words mean one thing. `src` is a duplicate object (merged into `dst`) or a
+    reference question (its word now means `dst`). Recorded in ledger["resolutions"]."""
+    by_id = {i["id"]: i for i in ledger["items"]}
+    target = by_id.get(dst)
+    if target is None or target["kind"] != "object":
+        raise ValueError(f"bind target {dst!r} is not an object item")
+    relations = [i for i in ledger["items"] if i["kind"] == "relation"]
+    q = next((q for q in ledger["unresolved"] if q["id"] == src and q.get("binds")), None)
+    if q is not None:
+        tok = q["binds"]["token"]
+        moves = [(r, role) for r in relations for role in ("subject", "object")
+                 if r.get("tokens", {}).get(role) == tok]
+        word, old = ledger["tokens"][tok]["text"] if tok < len(ledger["tokens"]) else "?", q["binds"]["to"]
+    else:
+        it = by_id.get(src)
+        if it is None or it["kind"] != "object":
+            raise ValueError(f"{src!r} is neither an object item nor a reference question")
+        if it is target:
+            raise ValueError(f"{src} is already {dst}")
+        if it["frozen"]:
+            raise ValueError(f"{src} is frozen; unfreeze it first")
+        moves = [(r, role) for r in relations for role in ("subject", "object") if r[role] == src]
+        word, old = it["word"], src
+    for r, role in moves:  # check before changing anything
+        if r["object" if role == "subject" else "subject"] == dst:
+            raise ValueError(f"binding {src} to {dst} would relate the {target['word']} to itself ({r['id']})")
+    for r, role in moves:
+        r[role] = dst
+    if q is not None:
+        ledger["tokens"][tok]["refers_to"] = dst
+        ledger["unresolved"].remove(q)
+    else:
+        ledger["items"].remove(it)
+        if it.get("emits_light"):
+            target["emits_light"] = True
+        for t in ledger["tokens"]:
+            if src in t["commits"]:
+                t["commits"].remove(src)
+                t["refers_to"] = dst
+            elif t.get("refers_to") == src:
+                t["refers_to"] = dst
+        kept = []
+        for u in ledger["unresolved"]:
+            if u.get("about") == src and not u.get("binds"):
+                continue  # "which cat?" for the duplicate: the duplicate is gone
+            if u.get("binds", {}).get("to") == src:
+                u["binds"]["to"], u["about"], u["default_chosen"] = dst, dst, f"the {target['word']} ({dst})"
+            kept.append(u)
+        ledger["unresolved"] = kept
+    live = {u["id"] for u in ledger["unresolved"]}
+    for t in ledger["tokens"]:  # answered questions leave the reading too; the resolution note keeps them
+        t["opens"] = [o for o in t.get("opens", []) if o in live]
+    ledger.setdefault("resolutions", []).append(
+        {"word": word, "from": old, "to": dst, "note": f"{old} -> {dst} (same referent)"})
+
+
 def apply_changes(ledger, changes):
     """changes: list of
         {"id": ..., "freeze": true|false}
@@ -75,11 +139,17 @@ def apply_changes(ledger, changes):
         {"id": ..., "height_m": 0.4}
         {"id": ..., "shape": "sphere"}       -> primitive tier with that shape
         {"reroll": true}                     -> every unfrozen object takes its next alternative
+        {"id": "n12", "bind": "n1"}          -> n12 is the same thing as n1: merged into it
+        {"id": "q11", "bind": "n5"}          -> the word behind reference question q11 means n5
     Reroll walks the pool (the old choice goes to the back), so repeated rerolls
     visit every alternative before repeating, independent of the seed.
     """
     by_id = {i["id"]: i for i in ledger["items"]}
     for ch in changes:
+        if "bind" in ch:
+            _bind(ledger, ch.get("id"), ch["bind"])
+            by_id = {i["id"]: i for i in ledger["items"]}
+            continue
         if ch.get("reroll"):
             for it in ledger["items"]:
                 dec = it.get("decision")