Forge: initial deploy — API + static UI over prebuilt forge.db (seeded at build)

Dockerfile

@@ -0,0 +1,19 @@
+# Forge demo — single container serves the API + static frontend over the
+# prebuilt forge.db. No scraping / no LLM at runtime (that's build-time, local),
+# so this stays tiny and CPU-only — fits a free HF Docker Space.
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY forge/ ./forge/
+COPY frontend/ ./frontend/
+
+# Bake the prebuilt graph if it shipped in the build context; otherwise seed a
+# fresh curated graph so the Space always boots with something.
+RUN test -f forge/forge.db || python -m forge.seed
+
+EXPOSE 7860
+CMD ["uvicorn", "forge.api:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,46 @@
 ---
 title: Forge
-emoji: 😻
-colorFrom: green
-colorTo: green
+emoji: 🔥
+colorFrom: yellow
+colorTo: red
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Forge — ML Training Compatibility Graph
+
+Pick your training ingredients (optimizer, scheduler, quantization, technique, architecture). Incompatible or not-yet-satisfied components grey out **live**, each with a cited reason and the fix. Output: a validated training recipe assembled from real practitioner evidence across the web.
+
+Built for the Bright Data **Web Data UNLOCKED** hackathon.
+
+## How it works
+
+- **Data (Bright Data):** `discover` (AI-intent ranking) + Web Unlocker + SERP (EN + CN geo) + Scraper API + Scraping Browser mine compatibility signal from docs, papers, GitHub repos/issues, and forums.
+- **Extraction (local, free):** a local Qwen2.5-3B model (llama.cpp) pulls `(A, relation, B, conditions)` triples — no paid LLM API. A keyless heuristic is the fallback.
+- **Trust:** tier-1 = verified practitioner research + a real LR-scheduler benchmark; tier-2 = docs / 2+ independent sources; tier-3 = single scrape (held in a review queue until corroborated). GitHub is used as a secondary source to verify candidates.
+- **Graph:** SQLite (`forge.db`). The grey-out resolves client-side for instant feedback.
+
+## Architecture
+
+The heavy work (scrape + extraction) runs at **build time** on the maintainer's machine. This Space just serves the prebuilt `forge.db` via FastAPI + a static D3 frontend — one origin, CPU-only.
+
+```
+brightdata CLI + local model  ──build──>  forge.db  ──serve──>  FastAPI (/graph,/resolve,/recipe,/feed) + static UI
+```
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+python -m forge.seed                 # build forge.db
+uvicorn forge.api:app --port 7860    # serves API + UI at http://localhost:7860
+```
+
+To grow the graph from live web data (needs the Bright Data CLI authenticated + a local `llama-server`):
+
+```bash
+python -m forge.campaign             # discover EN+CN across components
+python -m forge.github_collect corroborate   # verify candidates against GitHub
+```

forge/__init__.py

@@ -0,0 +1 @@
+"""Forge — compatibility graph for ML training components."""

forge/api.py

@@ -0,0 +1,136 @@
+"""Forge read API (piece 3) — serves the prebuilt forge.db to the frontend.
+
+Lightweight + read-only: this is what ships to the HF Space. The heavy
+build-time work (Bright Data scrape + local-model extraction) happens
+upstream; the Space just serves the graph.
+
+Run:  uvicorn forge.api:app --reload --port 8000
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+
+from pathlib import Path
+
+from fastapi import Body, FastAPI, HTTPException, Query
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from . import db, engine, scraper
+
+FRONTEND_DIR = Path(__file__).resolve().parent.parent / "frontend"
+
+app = FastAPI(title="Forge API", version="0.1")
+app.add_middleware(
+    CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"],
+)
+
+
+def _conn():
+    return db.connect()
+
+
+@app.get("/health")
+def health():
+    return {"ok": True, "llm_up": scraper._llm_up()}
+
+
+@app.get("/graph")
+def graph():
+    """All nodes + edges for the initial force-graph render."""
+    conn = _conn()
+    nodes = [dict(id=r["id"], canonical=r["canonical"], name=r["name"], type=r["type"],
+                  description=r["description"], tags=json.loads(r["tags_json"]))
+             for r in conn.execute("SELECT * FROM nodes").fetchall()]
+    name = {r["id"]: (r["canonical"], r["name"]) for r in conn.execute("SELECT id, canonical, name FROM nodes")}
+    ev_by_edge = {}
+    for x in conn.execute("SELECT * FROM evidence").fetchall():
+        ev_by_edge.setdefault(x["edge_id"], []).append(
+            dict(url=x["url"], quote=x["quote"], source_type=x["source_type"], tier=x["source_tier"]))
+    edges = []
+    for e in conn.execute("SELECT * FROM edges").fetchall():
+        fc, fn = name[e["from_id"]]
+        tc, tn = name[e["to_id"]]
+        edges.append(dict(id=e["id"], from_canon=fc, to_canon=tc, from_name=fn, to_name=tn,
+                          relation=e["relation"], conditions=json.loads(e["conditions_json"]),
+                          fix=e["fix"], tier=e["tier"], confidence=e["confidence"],
+                          evidence=ev_by_edge.get(e["id"], [])))
+    return {"nodes": nodes, "edges": edges}
+
+
+@app.post("/resolve")
+def resolve(payload: dict = Body(...)):
+    """Grey-out engine. Body: {selected:[canonical], context:{...}}."""
+    conn = _conn()
+    return engine.resolve(conn, payload.get("selected", []), payload.get("context", {}))
+
+
+@app.get("/recipe")
+def recipe(selected: str = Query("", description="comma-separated canonicals")):
+    conn = _conn()
+    sel = [s.strip() for s in selected.split(",") if s.strip()]
+    return engine.recipe(conn, sel)
+
+
+@app.get("/node/{canonical}")
+def node(canonical: str):
+    conn = _conn()
+    row = conn.execute("SELECT * FROM nodes WHERE canonical=?", (canonical,)).fetchone()
+    if not row:
+        raise HTTPException(404, f"no node {canonical!r}")
+    nid = row["id"]
+    name = {r["id"]: r["name"] for r in conn.execute("SELECT id, name FROM nodes")}
+    edges = []
+    for e in conn.execute("SELECT * FROM edges WHERE from_id=? OR to_id=?", (nid, nid)).fetchall():
+        ev = [dict(url=x["url"], quote=x["quote"], source_type=x["source_type"], tier=x["source_tier"])
+              for x in conn.execute("SELECT * FROM evidence WHERE edge_id=?", (e["id"],)).fetchall()]
+        edges.append(dict(from_name=name[e["from_id"]], to_name=name[e["to_id"]], relation=e["relation"],
+                          conditions=json.loads(e["conditions_json"]), fix=e["fix"], tier=e["tier"],
+                          confidence=e["confidence"], evidence=ev))
+    bench = [dict(model=b["model"], task=b["task"], val_loss=b["val_loss_mean"], val_acc=b["val_acc_mean"],
+                  steps_to_target=b["steps_to_target"], n_seeds=b["n_seeds"], source=b["source_url"])
+             for b in conn.execute("SELECT * FROM benchmarks WHERE component=?", (canonical,)).fetchall()]
+    return dict(id=nid, canonical=row["canonical"], name=row["name"], type=row["type"],
+                description=row["description"], aliases=json.loads(row["aliases_json"]),
+                tags=json.loads(row["tags_json"]), edges=edges, benchmarks=bench)
+
+
+@app.get("/feed")
+def feed(n: int = 10):
+    """Newest edges — the 'just discovered' panel."""
+    return scraper.feed(_conn(), n)
+
+
+@app.get("/review")
+def review(n: int = 20):
+    """Pending candidates awaiting corroboration."""
+    rows = _conn().execute(
+        "SELECT raw_a, relation, raw_b, COUNT(*) c FROM review_queue WHERE status='pending'"
+        " GROUP BY raw_a, relation, raw_b ORDER BY c DESC LIMIT ?", (n,)).fetchall()
+    return [dict(a=r["raw_a"], relation=r["relation"], b=r["raw_b"], sources=r["c"]) for r in rows]
+
+
+@app.get("/feed/stream")
+async def feed_stream():
+    """SSE: emits an edge event whenever a newer one appears."""
+    async def gen():
+        last_id = 0
+        while True:
+            rows = _conn().execute(
+                "SELECT e.id, e.relation, e.tier, n1.name a, n2.name b FROM edges e"
+                " JOIN nodes n1 ON n1.id=e.from_id JOIN nodes n2 ON n2.id=e.to_id"
+                " WHERE e.id > ? ORDER BY e.id", (last_id,)).fetchall()
+            for r in rows:
+                last_id = max(last_id, r["id"])
+                yield f"data: {json.dumps(dict(a=r['a'], relation=r['relation'], b=r['b'], tier=r['tier']))}\n\n"
+            await asyncio.sleep(2)
+
+    return StreamingResponse(gen(), media_type="text/event-stream")
+
+
+# Serve the static frontend at root (mounted LAST so API routes take precedence).
+# Same-origin hosting → no CORS in prod, one public URL for the HF Space.
+if FRONTEND_DIR.is_dir():
+    app.mount("/", StaticFiles(directory=str(FRONTEND_DIR), html=True), name="site")

forge/campaign.py

@@ -0,0 +1,127 @@
+"""Max-depth Bright Data collection campaign.
+
+Exercises the full BD stack to grow the graph and back the 'Application of
+Technology' story:
+  - discover (AI intent ranking) over every seeded component, EN + CN geo
+  - Web Unlocker page content (via discover --include-content)
+  - Scraper API (pipelines) — structured data from a pre-built scraper
+  - Scraping Browser — a JS-heavy forum page
+
+Extraction stays local/free (Qwen via llama-server, heuristic fallback).
+Raw payloads saved to data/raw/. Console gets compact summaries only.
+
+Run:  python -m forge.campaign            # full
+      python -m forge.campaign 3          # validate on first 3 components
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from datetime import datetime, timezone
+
+from . import collect, scraper
+from . import seed as seed_mod
+
+# Scraper API demo: pull a repo file as structured data.
+PIPELINE_TYPE = "github_repository_file"
+PIPELINE_URL = "https://github.com/artidoro/qlora/blob/main/README.md"
+FORUM_RE = re.compile(r"reddit\.com|huggingface\.co/.*/discussions|/forum|zhihu\.com|csdn\.net")
+BROWSER_FALLBACK = "https://www.reddit.com/r/LocalLLaMA/"  # JS-heavy, guaranteed Browser target
+
+
+def en_query(name):
+    return f"{name} training optimizer scheduler compatible OR incompatible OR requires"
+
+
+def cn_query(name):
+    return f"{name} 微调"  # 2-word CN query; 3+ keywords return 0
+
+
+def gather(label, query, n):
+    """EN: discover (AI intent + inline content). CN: SERP + Web Unlocker scrape
+    (discover --country CN reliably returns 0; SERP CN works)."""
+    if label == "EN":
+        return [{"url": r.get("link", ""), "content": r.get("content") or ""}
+                for r in collect.discover(query, country=None, language="en", n=n)]
+    items = []
+    for hit in scraper.search(query, n=n, country="cn"):
+        items.append({"url": hit["url"], "content": scraper.fetch(hit["url"])})
+    return items
+
+
+def run(limit=None, n=8, do_pipeline=True, do_browser=True):
+    conn = seed_mod.seed()
+    ai = scraper.build_alias_index(conn)
+    resolver = scraper.build_resolver(conn)
+    comps = [(r["canonical"], r["name"]) for r in
+             conn.execute("SELECT canonical, name FROM nodes ORDER BY type, canonical").fetchall()]
+    if limit:
+        comps = comps[:limit]
+
+    totals = {"promoted": [], "queued": [], "pages": 0, "components": 0,
+              "bd_calls": 0, "first_forum": None, "products": {"discover", "web_unlocker"}}
+    raw = {"ts": datetime.now(timezone.utc).isoformat(), "passes": {}}
+
+    for canon, name in comps:
+        totals["components"] += 1
+        for label, q in [("EN", en_query(name)), ("CN", cn_query(name))]:
+            items = gather(label, q, n)
+            totals["bd_calls"] += 1
+            raw["passes"][f"{canon}:{label}"] = [{"url": i["url"]} for i in items]
+            print(f"[{canon}/{label}] {len(items)} items")
+            for it in items:
+                url, content = it["url"], it["content"]
+                if totals["first_forum"] is None and FORUM_RE.search(url):
+                    totals["first_forum"] = url
+                if len(content) < 200:
+                    continue
+                totals["pages"] += 1
+                res = scraper.ingest(conn, scraper.extract(content[:15000], url, ai), url, resolver)
+                totals["promoted"] += res["promoted"]
+                totals["queued"] += res["queued"]
+
+    if do_pipeline:  # Scraper API (async snapshot job)
+        data, err = scraper.run_pipeline(PIPELINE_TYPE, PIPELINE_URL)
+        blob = (err or "") + json.dumps(data)
+        m = re.search(r"(sd_[A-Za-z0-9]+)", blob)
+        totals["pipeline_ok"] = bool(data) or bool(m)
+        totals["pipeline_note"] = (f"triggered snapshot {m.group(1)}" if m
+                                   else ("ok" if data else f"err: {(err or '')[:100]}"))
+        if totals["pipeline_ok"]:
+            totals["products"].add("scraper_api")
+
+    target = totals["first_forum"] or BROWSER_FALLBACK
+    if do_browser and target:  # Scraping Browser
+        out, err, rc = scraper.browser_open(target)
+        totals["browser_ok"] = rc == 0 and bool(out)
+        totals["browser_note"] = (f"ok on {target} ({len(out)} chars)" if totals["browser_ok"]
+                                  else f"err: {(err or out)[:120]}")
+        if totals["browser_ok"]:
+            totals["products"].add("scraping_browser")
+
+    collect.RAW_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    (collect.RAW_DIR / f"forge_campaign_{stamp}.json").write_text(json.dumps(raw, ensure_ascii=False))
+    return conn, totals
+
+
+def main():
+    limit = int(sys.argv[1]) if len(sys.argv) > 1 else None
+    conn, t = run(limit=limit)
+    print(f"\n=== campaign summary ===")
+    print(f"components       : {t['components']}")
+    print(f"Bright Data calls: {t['bd_calls']} discover (EN+CN)")
+    print(f"pages extracted  : {t['pages']}")
+    print(f"edges promoted   : {len(t['promoted'])}")
+    print(f"queued candidates: {len(t['queued'])}")
+    print(f"BD products used : {', '.join(sorted(t['products']))}")
+    print(f"scraper api      : {t.get('pipeline_note', 'skipped')}")
+    print(f"scraping browser : {t.get('browser_note', 'skipped')}")
+    total_edges = conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+    pending = conn.execute("SELECT COUNT(*) FROM review_queue WHERE status='pending'").fetchone()[0]
+    print(f"graph now        : {total_edges} edges, {pending} pending candidates")
+
+
+if __name__ == "__main__":
+    main()

forge/collect.py

@@ -0,0 +1,168 @@
+"""Live Bright Data collection run (max depth).
+
+Uses `brightdata discover` (AI-driven intent ranking) with --include-content, so a
+single call ranks results AND returns Web-Unlocker'd page markdown. Runs EN and
+CN (geo-targeted) passes, extracts compatibility triples, and feeds the
+corroboration gate. Optionally demos the Scraping Browser on a JS-heavy forum.
+
+Bright Data is the only external dependency. Raw payloads are saved to
+data/raw/ for provenance; only compact summaries print to the console.
+
+Run:  python -m forge.collect QLoRA
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import db, scraper
+from . import seed as seed_mod
+
+INTENT = (
+    "I am building a compatibility graph of ML training components. Prioritize results "
+    "that explicitly state how components combine: which optimizers, schedulers, "
+    "quantization methods, PEFT techniques and architectures work together, require each "
+    "other, or are incompatible. Favor concrete statements like 'X requires Y', 'X is "
+    "incompatible with Y', 'X works with Y under condition Z', with hardware/precision "
+    "context. Deprioritize marketing, beginner tutorials, and pure inference content."
+)
+
+RAW_DIR = Path(__file__).resolve().parent.parent / "data" / "raw"
+
+
+def _parse_discover(raw: str) -> list[dict]:
+    try:
+        return json.loads(raw).get("results", [])
+    except json.JSONDecodeError:
+        m = re.search(r"\{[\s\S]*\}", raw)
+        if not m:
+            return []
+        try:
+            return json.loads(m.group(0)).get("results", [])
+        except json.JSONDecodeError:
+            return []
+
+
+def discover(query, *, country=None, language="en", n=8) -> list[dict]:
+    args = ["discover", query, "--intent", INTENT, "--include-content",
+            "--num-results", str(n), "--pretty"]
+    if country:
+        args += ["--country", country]
+    if language:
+        args += ["--language", language]
+    out, _, _ = scraper._brightdata(args, timeout=600)
+    return _parse_discover(out)
+
+
+def browser_showcase(url) -> str:
+    """Demo the Scraping Browser on a JS-heavy page. Guarded; never blocks the run."""
+    try:
+        out, err, rc = scraper._brightdata(
+            ["browser", "open", url, "--interactive", "--timeout", "30000", "--pretty"],
+            timeout=60,
+        )
+        return f"ok ({len(out)} chars)" if out and rc == 0 else f"no-op ({(err or '').strip()[:80]})"
+    except Exception as e:  # noqa: BLE001 - showcase only, must not kill the run
+        return f"skipped ({type(e).__name__})"
+
+
+def run(target="QLoRA"):
+    conn = seed_mod.seed()  # fresh seed; live edges land on top
+    alias_index = scraper.build_alias_index(conn)
+    resolver = scraper.build_resolver(conn)
+
+    passes = [
+        ("EN", f"{target} optimizer scheduler quantization compatible OR incompatible OR requires", None, "en"),
+        ("CN", f"{target} 微调 优化器 调度器 量化 兼容 不兼容 需要", "CN", "zh"),
+    ]
+
+    raw_bundle, total = {"target": target, "ts": datetime.now(timezone.utc).isoformat(), "passes": {}}, \
+        {"promoted": [], "queued": [], "pages": 0, "first_forum": None}
+
+    for label, q, country, lang in passes:
+        results = discover(q, country=country, language=lang, n=8)
+        raw_bundle["passes"][label] = results
+        print(f"[{label}] discover returned {len(results)} ranked results")
+        for r in results:
+            content = r.get("content") or ""
+            url = r.get("link", "")
+            if total["first_forum"] is None and re.search(r"reddit\.com|huggingface\.co/.*/discussions|forum", url):
+                total["first_forum"] = url
+            if len(content) < 200:
+                continue
+            total["pages"] += 1
+            triples = scraper.extract(content[:15000], url, alias_index)
+            res = scraper.ingest(conn, triples, url, resolver)
+            total["promoted"] += res["promoted"]
+            total["queued"] += res["queued"]
+
+    RAW_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    (RAW_DIR / f"forge_collect_{stamp}.json").write_text(json.dumps(raw_bundle, ensure_ascii=False))
+
+    return conn, total
+
+
+def replay(path=None):
+    """Re-extract + ingest over a saved raw bundle. No new Bright Data credits."""
+    conn = seed_mod.seed()
+    alias_index = scraper.build_alias_index(conn)
+    resolver = scraper.build_resolver(conn)
+    files = sorted(RAW_DIR.glob("forge_collect_*.json"))
+    f = Path(path) if path else (files[-1] if files else None)
+    if not f or not f.exists():
+        print("no saved bundle found — run a live collection first")
+        return conn, None
+    bundle = json.loads(f.read_text())
+    total = {"promoted": [], "queued": [], "pages": 0, "first_forum": None}
+    for results in bundle.get("passes", {}).values():
+        for r in results:
+            content = r.get("content") or ""
+            if len(content) < 200:
+                continue
+            total["pages"] += 1
+            url = r.get("link", "")
+            res = scraper.ingest(conn, scraper.extract(content[:15000], url, alias_index), url, resolver)
+            total["promoted"] += res["promoted"]
+            total["queued"] += res["queued"]
+    print(f"[replay] {f.name}: {total['pages']} pages (no credits spent)")
+    return conn, total
+
+
+def _report(conn, total):
+    backend = "local-model" if scraper._llm_up() else "heuristic"
+    print(f"\n=== extraction ({backend}) ===")
+    print(f"pages extracted : {total['pages']}")
+    print(f"edges promoted  : {len(total['promoted'])}  (2+ independent sources agreed)")
+    for a, rel, b in total["promoted"][:12]:
+        print(f"   ● {a} —{rel}→ {b}")
+    print(f"queued (1 src)  : {len(total['queued'])}  (waiting for corroboration)")
+    rows = conn.execute(
+        "SELECT raw_a, relation, raw_b, COUNT(*) c FROM review_queue WHERE status='pending'"
+        " GROUP BY raw_a, relation, raw_b ORDER BY c DESC LIMIT 10"
+    ).fetchall()
+    if rows:
+        print("\ntop pending candidates (raw_a, rel, raw_b, #sources):")
+        for r in rows:
+            print(f"   ◐ {r['raw_a']} —{r['relation']}→ {r['raw_b']}  ({r['c']})")
+    print("\nlive feed (newest edges):")
+    for fd in scraper.feed(conn, n=10):
+        print(f"   {fd['a']} —{fd['relation']}→ {fd['b']}  (T{fd['tier']})")
+
+
+def main():
+    arg = sys.argv[1] if len(sys.argv) > 1 else "QLoRA"
+    if arg == "replay":
+        conn, total = replay(sys.argv[2] if len(sys.argv) > 2 else None)
+    else:
+        conn, total = run(arg)
+    if total:
+        _report(conn, total)
+
+
+if __name__ == "__main__":
+    import os  # noqa: E402 - used by _report
+    main()

forge/db.py

@@ -0,0 +1,186 @@
+"""Forge SQLite layer: schema, connection, insert helpers.
+
+One file: forge.db. No vector layer in v1 (see spec). Confidence is derived
+from tier so the scraper can never assert nonsense above what its evidence earns.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+DB_PATH = Path(__file__).with_name("forge.db")
+
+# tier -> confidence. Tier 1 = Rick's verified research (immutable, scraper never
+# overwrites). Tier 2 = official docs or 2+ independent sources. Tier 3 = single
+# scrape (lands in review_queue, not asserted as a live edge).
+TIER_CONFIDENCE = {1: 1.0, 2: 0.8, 3: 0.5}
+
+RELATIONS = {"REQUIRES", "CONDITIONAL", "COMPATIBLE", "DEGRADES", "BREAKS"}
+# REQUIRES is directional (from -> to). The rest are treated as undirected.
+DIRECTED = {"REQUIRES"}
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS nodes (
+    id           INTEGER PRIMARY KEY,
+    type         TEXT NOT NULL,
+    name         TEXT NOT NULL,
+    canonical    TEXT NOT NULL UNIQUE,
+    aliases_json TEXT NOT NULL DEFAULT '[]',
+    description  TEXT NOT NULL DEFAULT '',
+    tags_json    TEXT NOT NULL DEFAULT '[]'
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+    id              INTEGER PRIMARY KEY,
+    from_id         INTEGER NOT NULL REFERENCES nodes(id),
+    to_id           INTEGER NOT NULL REFERENCES nodes(id),
+    relation        TEXT NOT NULL,
+    conditions_json TEXT NOT NULL DEFAULT '{}',
+    fix             TEXT NOT NULL DEFAULT '',
+    tier            INTEGER NOT NULL,
+    confidence      REAL NOT NULL,
+    created_at      TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS evidence (
+    id          INTEGER PRIMARY KEY,
+    edge_id     INTEGER NOT NULL REFERENCES edges(id),
+    url         TEXT NOT NULL DEFAULT '',
+    quote       TEXT NOT NULL DEFAULT '',
+    source_type TEXT NOT NULL DEFAULT '',
+    source_tier INTEGER NOT NULL,
+    scraped_at  TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS review_queue (
+    id           INTEGER PRIMARY KEY,
+    raw_a        TEXT NOT NULL,
+    raw_b        TEXT NOT NULL,
+    relation     TEXT NOT NULL,
+    conditions   TEXT NOT NULL DEFAULT '{}',
+    evidence_url TEXT NOT NULL DEFAULT '',
+    status       TEXT NOT NULL DEFAULT 'pending'
+);
+
+-- Performance evidence (NOT compatibility). Drives recipe recommendations.
+-- One row per scheduler under a fixed benchmark condition. Wall-clock is
+-- deliberately omitted: observed elapsed had a 4x GPU-contention artifact.
+CREATE TABLE IF NOT EXISTS benchmarks (
+    id                  INTEGER PRIMARY KEY,
+    component           TEXT NOT NULL,        -- scheduler name (matches a node canonical/alias)
+    optimizer           TEXT NOT NULL DEFAULT 'AdamW',
+    model               TEXT NOT NULL,
+    task                TEXT NOT NULL,
+    val_loss_mean       REAL,
+    val_loss_std        REAL,
+    val_acc_mean        REAL,
+    val_acc_std         REAL,
+    steps_to_target     REAL,
+    n_seeds             INTEGER,
+    conditions_json     TEXT NOT NULL DEFAULT '{}',
+    source_url          TEXT NOT NULL DEFAULT '',
+    tier                INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_id);
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(to_id);
+"""
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def connect(path: Path | str = DB_PATH) -> sqlite3.Connection:
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def init_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript(SCHEMA)
+    conn.commit()
+
+
+def reset(path: Path | str = DB_PATH) -> sqlite3.Connection:
+    """Drop and recreate from scratch. Used by seed/harness for a clean build."""
+    p = Path(path)
+    if p.exists():
+        p.unlink()
+    conn = connect(path)
+    init_schema(conn)
+    return conn
+
+
+def add_node(conn, *, type, name, canonical, aliases=None, description="", tags=None) -> int:
+    cur = conn.execute(
+        "INSERT INTO nodes(type, name, canonical, aliases_json, description, tags_json)"
+        " VALUES(?,?,?,?,?,?)",
+        (type, name, canonical, json.dumps(aliases or []), description, json.dumps(tags or [])),
+    )
+    return cur.lastrowid
+
+
+def node_id(conn, canonical: str) -> int:
+    row = conn.execute("SELECT id FROM nodes WHERE canonical=?", (canonical,)).fetchone()
+    if row is None:
+        raise KeyError(f"no node with canonical={canonical!r}")
+    return row["id"]
+
+
+def add_edge(conn, *, from_canon, to_canon, relation, tier, conditions=None, fix="",
+             evidence=None) -> int:
+    if relation not in RELATIONS:
+        raise ValueError(f"bad relation {relation!r}")
+    fid, tid = node_id(conn, from_canon), node_id(conn, to_canon)
+    cur = conn.execute(
+        "INSERT INTO edges(from_id, to_id, relation, conditions_json, fix, tier, confidence, created_at)"
+        " VALUES(?,?,?,?,?,?,?,?)",
+        (fid, tid, relation, json.dumps(conditions or {}), fix, tier,
+         TIER_CONFIDENCE[tier], now_iso()),
+    )
+    edge_id = cur.lastrowid
+    for ev in (evidence or []):
+        conn.execute(
+            "INSERT INTO evidence(edge_id, url, quote, source_type, source_tier, scraped_at)"
+            " VALUES(?,?,?,?,?,?)",
+            (edge_id, ev.get("url", ""), ev.get("quote", ""), ev.get("source_type", ""),
+             ev.get("source_tier", tier), ev.get("scraped_at", now_iso())),
+        )
+    return edge_id
+
+
+def add_review(conn, *, raw_a, raw_b, relation, conditions=None, evidence_url="") -> int:
+    cur = conn.execute(
+        "INSERT INTO review_queue(raw_a, raw_b, relation, conditions, evidence_url)"
+        " VALUES(?,?,?,?,?)",
+        (raw_a, raw_b, relation, json.dumps(conditions or {}), evidence_url),
+    )
+    return cur.lastrowid
+
+
+def add_evidence(conn, edge_id, ev) -> int:
+    cur = conn.execute(
+        "INSERT INTO evidence(edge_id, url, quote, source_type, source_tier, scraped_at)"
+        " VALUES(?,?,?,?,?,?)",
+        (edge_id, ev.get("url", ""), ev.get("quote", ""), ev.get("source_type", ""),
+         ev.get("source_tier", 3), ev.get("scraped_at", now_iso())),
+    )
+    return cur.lastrowid
+
+
+def add_benchmark(conn, *, component, model, task, val_loss_mean, val_loss_std,
+                  val_acc_mean, val_acc_std, steps_to_target, n_seeds,
+                  optimizer="AdamW", conditions=None, source_url="", tier=1) -> int:
+    cur = conn.execute(
+        "INSERT INTO benchmarks(component, optimizer, model, task, val_loss_mean,"
+        " val_loss_std, val_acc_mean, val_acc_std, steps_to_target, n_seeds,"
+        " conditions_json, source_url, tier) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)",
+        (component, optimizer, model, task, val_loss_mean, val_loss_std, val_acc_mean,
+         val_acc_std, steps_to_target, n_seeds, json.dumps(conditions or {}),
+         source_url, tier),
+    )
+    return cur.lastrowid

forge/engine.py

@@ -0,0 +1,165 @@
+"""Forge engine.
+
+resolve()  -- the grey-out engine. Given a selected set + a context, classify
+              every other node as available / conditional / blocked, with the
+              reason and cited evidence. Pairwise over the edge graph (v1).
+recommend() -- reads the benchmark table to rank components under a condition.
+              Performance evidence, kept separate from compatibility.
+"""
+from __future__ import annotations
+
+import json
+from . import db
+
+# status severity ordering (worst wins when a node has multiple edges)
+SEVERITY = {"available": 0, "conditional": 1, "blocked": 2}
+
+
+def _node_map(conn):
+    rows = conn.execute("SELECT id, canonical, name, type FROM nodes").fetchall()
+    by_id = {r["id"]: dict(id=r["id"], canonical=r["canonical"], name=r["name"], type=r["type"]) for r in rows}
+    by_canon = {r["canonical"]: r["id"] for r in rows}
+    # aliases
+    for r in conn.execute("SELECT id, aliases_json FROM nodes").fetchall():
+        for a in json.loads(r["aliases_json"]):
+            by_canon.setdefault(a, r["id"])
+    return by_id, by_canon
+
+
+def _conditions_met(conditions: dict, context: dict) -> bool:
+    """A CONDITIONAL/REQUIRES edge is satisfied if context matches all its keys."""
+    for k, v in conditions.items():
+        if k == "note":
+            continue
+        if str(context.get(k)) != str(v):
+            return False
+    return True
+
+
+def _edges_touching(conn, node_id, selected_ids):
+    """All edges between node_id and any selected node (both directions)."""
+    rows = conn.execute(
+        "SELECT * FROM edges WHERE (from_id=? AND to_id IN (%s)) OR (to_id=? AND from_id IN (%s))"
+        % (",".join("?" * len(selected_ids)), ",".join("?" * len(selected_ids))),
+        [node_id, *selected_ids, node_id, *selected_ids],
+    ).fetchall() if selected_ids else []
+    return rows
+
+
+def _evidence_for(conn, edge_id):
+    return [dict(url=r["url"], quote=r["quote"], source_type=r["source_type"], tier=r["source_tier"])
+            for r in conn.execute("SELECT * FROM evidence WHERE edge_id=?", (edge_id,)).fetchall()]
+
+
+def resolve(conn, selected, context=None):
+    """selected: list of canonical names (or aliases). context: dict of chosen settings.
+    Returns {canonical: {status, reasons:[...]}} for every node not in selected."""
+    context = context or {}
+    by_id, by_canon = _node_map(conn)
+    selected_ids = [by_canon[s] for s in selected if s in by_canon]
+    selected_set = set(selected_ids)
+
+    out = {}
+    for nid, node in by_id.items():
+        if nid in selected_set:
+            continue
+        status, reasons = "available", []
+
+        for e in _edges_touching(conn, nid, selected_ids):
+            rel = e["relation"]
+            conds = json.loads(e["conditions_json"])
+            other = e["to_id"] if e["from_id"] == nid else e["from_id"]
+            other_name = by_id[other]["name"]
+            ev = _evidence_for(conn, e["id"])
+
+            if rel == "BREAKS":
+                status = _worst(status, "blocked")
+                reasons.append(_reason("blocked", f"breaks with {other_name}", e["fix"], conds, ev, e["tier"], e["confidence"]))
+            elif rel in ("REQUIRES", "CONDITIONAL"):
+                if not _conditions_met(conds, context):
+                    status = _worst(status, "conditional")
+                    label = f"requires {other_name}" if rel == "REQUIRES" else f"conditional with {other_name}"
+                    reasons.append(_reason("conditional", label, e["fix"], conds, ev, e["tier"], e["confidence"]))
+            elif rel == "DEGRADES":
+                reasons.append(_reason("degrades", f"degrades with {other_name}", e["fix"], conds, ev, e["tier"], e["confidence"]))
+
+        # node's own unmet REQUIRES pointing at something not selected
+        for e in conn.execute("SELECT * FROM edges WHERE from_id=? AND relation='REQUIRES'", (nid,)).fetchall():
+            if e["to_id"] not in selected_set and not _conditions_met(json.loads(e["conditions_json"]), context):
+                req = by_id[e["to_id"]]["name"]
+                status = _worst(status, "conditional")
+                reasons.append(_reason("conditional", f"requires {req}", e["fix"],
+                                       json.loads(e["conditions_json"]), _evidence_for(conn, e["id"]),
+                                       e["tier"], e["confidence"]))
+
+        out[node["canonical"]] = dict(name=node["name"], type=node["type"], status=status, reasons=reasons)
+    return out
+
+
+def _worst(a, b):
+    return a if SEVERITY[a] >= SEVERITY[b] else b
+
+
+def _reason(kind, label, fix, conditions, evidence, tier, confidence):
+    return dict(kind=kind, label=label, fix=fix, conditions=conditions,
+                evidence=evidence, tier=tier, confidence=confidence)
+
+
+def recommend(conn, *, metric="val_loss", task=None, top=5):
+    """Rank benchmarked components by a metric. metric in {val_loss, val_acc}."""
+    order = "ASC" if metric == "val_loss" else "DESC"
+    col = "val_loss_mean" if metric == "val_loss" else "val_acc_mean"
+    sql = f"SELECT * FROM benchmarks WHERE {col} IS NOT NULL"
+    params = []
+    if task:
+        sql += " AND task=?"
+        params.append(task)
+    sql += f" ORDER BY {col} {order} LIMIT ?"
+    params.append(top)
+    rows = conn.execute(sql, params).fetchall()
+    return [dict(component=r["component"], val_loss=r["val_loss_mean"], val_acc=r["val_acc_mean"],
+                 steps_to_target=r["steps_to_target"], n_seeds=r["n_seeds"],
+                 source=r["source_url"]) for r in rows]
+
+
+def recipe(conn, selected, context=None):
+    """Validate a selection: conflicts (BREAKS within set), unmet REQUIRES/CONDITIONAL,
+    plus benchmark-backed scheduler suggestions. The 'recipe card' payload."""
+    context = context or {}
+    by_id, by_canon = _node_map(conn)
+    sel_ids = {by_canon[s] for s in selected if s in by_canon}
+
+    conflicts, unmet = [], []
+    for e in conn.execute("SELECT * FROM edges").fetchall():
+        if e["from_id"] not in sel_ids:
+            continue
+        if e["relation"] == "BREAKS" and e["to_id"] in sel_ids:
+            conflicts.append({"a": by_id[e["from_id"]]["name"], "b": by_id[e["to_id"]]["name"],
+                              "fix": e["fix"], "tier": e["tier"]})
+        elif e["relation"] in ("REQUIRES", "CONDITIONAL") and e["to_id"] not in sel_ids \
+                and not _conditions_met(json.loads(e["conditions_json"]), context):
+            unmet.append({"component": by_id[e["from_id"]]["name"], "needs": by_id[e["to_id"]]["name"],
+                          "relation": e["relation"], "fix": e["fix"], "tier": e["tier"]})
+
+    return {
+        "selected": selected,
+        "context": context,
+        "valid": not conflicts and not unmet,
+        "conflicts": conflicts,
+        "unmet": unmet,
+        "scheduler_picks": recommend(conn, metric="val_loss", top=3),
+        "warnings": warnings(conn),
+    }
+
+
+def warnings(conn, *, task=None):
+    """Components that clearly underperform the field (loss > field_mean + 2*field_std)."""
+    rows = conn.execute("SELECT component, val_loss_mean FROM benchmarks WHERE val_loss_mean IS NOT NULL").fetchall()
+    if not rows:
+        return []
+    vals = [r["val_loss_mean"] for r in rows]
+    mean = sum(vals) / len(vals)
+    std = (sum((v - mean) ** 2 for v in vals) / len(vals)) ** 0.5
+    cutoff = mean + 2 * std
+    return [dict(component=r["component"], val_loss=r["val_loss_mean"], cutoff=round(cutoff, 4))
+            for r in rows if r["val_loss_mean"] > cutoff]

forge/github_collect.py

@@ -0,0 +1,136 @@
+"""GitHub-focused collection — the highest-signal compatibility source.
+
+READMEs state intended composition ("uses bitsandbytes 4-bit", "requires LoRA");
+issues are where real incompatibilities surface ("X breaks with Y", error reports).
+We mine both via Bright Data Web Unlocker, plus fire a Scraper-API snapshot
+(github_repository_file) as the structured-data showcase.
+
+Adds to the EXISTING forge.db (does not reseed) so it stacks on the campaign.
+
+Run:  python -m forge.github_collect
+"""
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+
+from . import collect, db, scraper
+
+# High-signal ML training repos — where composition + breakage actually get documented.
+REPOS = [
+    "artidoro/qlora", "unslothai/unsloth", "huggingface/peft", "huggingface/trl",
+    "huggingface/transformers", "bitsandbytes-foundation/bitsandbytes",
+    "microsoft/DeepSpeed", "Dao-AILab/flash-attention", "huggingface/accelerate",
+    "KellerJordan/modded-nanogpt",
+]
+PIPELINE_TYPE = "github_repository_file"
+
+
+def issue_query(repo):
+    return f'site:github.com/{repo} incompatible OR "does not work" OR requires OR breaks'
+
+
+def run(repos=None, issues_per_repo=4):
+    repos = repos or REPOS
+    conn = db.connect()  # stack onto existing graph
+    ai = scraper.build_alias_index(conn)
+    resolver = scraper.build_resolver(conn)
+    totals = {"promoted": [], "queued": [], "readmes": 0, "issues": 0, "repos": 0,
+              "snapshots": []}
+    raw = {"ts": datetime.utcnow().isoformat(), "pages": {}}
+
+    for repo in repos:
+        totals["repos"] += 1
+        # 1. README (rendered repo page via Web Unlocker)
+        md = scraper.fetch(f"https://github.com/{repo}")
+        if md and len(md) > 200:
+            totals["readmes"] += 1
+            raw["pages"][f"{repo}#readme"] = md[:20000]
+            res = scraper.ingest(conn, scraper.extract(md[:15000], f"https://github.com/{repo}", ai),
+                                 f"https://github.com/{repo}", resolver)
+            totals["promoted"] += res["promoted"]; totals["queued"] += res["queued"]
+
+        # 2. issue threads (richest breakage signal) via SERP -> Web Unlocker
+        for hit in scraper.search(issue_query(repo), n=issues_per_repo):
+            url = hit["url"]
+            if "/issues/" not in url and "/pull/" not in url:
+                continue
+            page = scraper.fetch(url)
+            if not page or len(page) < 200:
+                continue
+            totals["issues"] += 1
+            raw["pages"][url] = page[:20000]
+            res = scraper.ingest(conn, scraper.extract(page[:15000], url, ai), url, resolver)
+            totals["promoted"] += res["promoted"]; totals["queued"] += res["queued"]
+        print(f"[{repo}] readme+{totals['issues']} issues so far")
+
+    # 3. Scraper API showcase — structured file pulls (async snapshots)
+    for repo in repos[:3]:
+        data, err = scraper.run_pipeline(PIPELINE_TYPE, f"https://github.com/{repo}/blob/main/README.md")
+        m = re.search(r"(sd_[A-Za-z0-9]+)", (err or "") + json.dumps(data))
+        if m:
+            totals["snapshots"].append(m.group(1))
+
+    collect.RAW_DIR.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    (collect.RAW_DIR / f"forge_github_{stamp}.json").write_text(json.dumps(raw, ensure_ascii=False))
+    return conn, totals
+
+
+def corroborate_via_github(conn=None, limit=30):
+    """Rick's idea: verify pending candidates against GitHub (secondary/authoritative
+    source). For each single-source (A, rel, B) in the queue, search GitHub for the
+    same pair; if the model re-extracts that edge from a GitHub page, it's an
+    independent 2nd source → the gate promotes it."""
+    conn = conn or db.connect()
+    ai = scraper.build_alias_index(conn)
+    resolver = scraper.build_resolver(conn)
+    names = {r["canonical"]: r["name"] for r in conn.execute("SELECT canonical, name FROM nodes")}
+    pend = conn.execute(
+        "SELECT DISTINCT raw_a, relation, raw_b FROM review_queue WHERE status='pending'").fetchall()
+    promoted, checked = [], 0
+    for row in pend:
+        a, b = row["raw_a"], row["raw_b"]
+        if a not in names or b not in names:  # only verify already-resolved candidates
+            continue
+        if checked >= limit:
+            break
+        checked += 1
+        q = f'site:github.com {names[a]} {names[b]}'
+        for hit in scraper.search(q, n=3):
+            page = scraper.fetch(hit["url"])
+            if not page or len(page) < 200:
+                continue
+            res = scraper.ingest(conn, scraper.extract(page[:15000], hit["url"], ai), hit["url"], resolver)
+            promoted += res["promoted"]
+        print(f"[corroborate] {names[a]}—{row['relation']}→{names[b]}: {len(promoted)} promoted so far")
+    return conn, promoted
+
+
+def main():
+    import sys
+    if len(sys.argv) > 1 and sys.argv[1] == "corroborate":
+        conn, promoted = corroborate_via_github()
+        print(f"\n=== github corroboration ===")
+        print(f"edges promoted by GitHub verification: {len(promoted)}")
+        for a, rel, b in promoted:
+            print(f"   ● {a} —{rel}→ {b}")
+        edges = conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+        print(f"graph now: {edges} edges")
+        return
+    conn, t = run()
+    print(f"\n=== github campaign ===")
+    print(f"repos          : {t['repos']}")
+    print(f"readmes scraped: {t['readmes']}")
+    print(f"issues scraped : {t['issues']}")
+    print(f"edges promoted : {len(t['promoted'])}")
+    print(f"queued         : {len(t['queued'])}")
+    print(f"scraper-api snapshots: {len(t['snapshots'])} {t['snapshots']}")
+    edges = conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+    pending = conn.execute("SELECT COUNT(*) FROM review_queue WHERE status='pending'").fetchone()[0]
+    print(f"graph now      : {edges} edges, {pending} pending candidates")
+
+
+if __name__ == "__main__":
+    main()

forge/harness.py

@@ -0,0 +1,68 @@
+"""Piece 1 harness: seed the graph, then watch the engine work on real data.
+
+Run:  python -m forge.harness
+No network, no server. Pure spine. Includes asserts so we know it's correct.
+"""
+from __future__ import annotations
+
+from . import seed as seed_mod
+from . import engine
+
+
+C_RED, C_YEL, C_GRN, C_DIM, C_RST = "\033[91m", "\033[93m", "\033[92m", "\033[2m", "\033[0m"
+ICON = {"available": f"{C_GRN}●{C_RST}", "conditional": f"{C_YEL}◐{C_RST}", "blocked": f"{C_RED}○{C_RST}"}
+
+
+def show(conn, selected, context=None):
+    context = context or {}
+    ctx = f"  context={context}" if context else ""
+    print(f"\n{C_DIM}── selected: {selected}{ctx} ──{C_RST}")
+    res = engine.resolve(conn, selected, context)
+    for status in ("blocked", "conditional", "available"):
+        for canon, info in sorted(res.items()):
+            if info["status"] != status:
+                continue
+            line = f"  {ICON[status]} {info['name']:<24} [{info['type']}]"
+            if info["reasons"]:
+                r = info["reasons"][0]
+                tag = f"T{r['tier']}·{r['confidence']:.1f}"
+                line += f"  {C_DIM}{r['label']} ({tag}){C_RST}"
+                if r["fix"]:
+                    line += f"\n      {C_DIM}↳ fix: {r['fix']}{C_RST}"
+            print(line)
+    return res
+
+
+def main():
+    conn = seed_mod.seed()
+    print(f"{C_GRN}forge.db seeded.{C_RST}")
+
+    # Scenario 1: your verified tier-1 edge. Pick per-layer LR rotation -> AdamW 8-bit blocks.
+    res = show(conn, ["per_layer_lr_rotation"])
+    assert res["adamw_8bit"]["status"] == "blocked", "tier-1 edge should block adamw_8bit"
+
+    # Scenario 2: QLoRA pulls in its requirement (bnb_4bit) and blocks full fine-tune.
+    res = show(conn, ["qlora"])
+    assert res["fft"]["status"] == "blocked", "QLoRA and FFT are mutually exclusive"
+    assert res["bnb_4bit"]["status"] in ("conditional", "available")
+
+    # Scenario 3: conditional flips on context. vLLM + gradient_checkpointing.
+    r_off = engine.resolve(conn, ["vllm"], {"gradient_checkpointing": "disabled"})
+    r_on = engine.resolve(conn, ["vllm"], {"gradient_checkpointing": "enabled"})
+    assert r_off["gradient_checkpointing"]["status"] == "conditional"
+    assert r_on["gradient_checkpointing"]["status"] == "available"
+    show(conn, ["vllm"], {"gradient_checkpointing": "disabled"})
+
+    # Scenario 4: benchmark-backed recommendation (performance, not compatibility).
+    print(f"\n{C_DIM}── recipe: best schedulers by val_loss (your benchmark) ──{C_RST}")
+    for i, r in enumerate(engine.recommend(conn, metric="val_loss", top=5), 1):
+        print(f"  {i}. {r['component']:<16} val_loss={r['val_loss']:.4f}  val_acc={r['val_acc']:.4f}  (n={r['n_seeds']})")
+    print(f"\n{C_DIM}── underperformers (>2σ worse on val_loss) ──{C_RST}")
+    for w in engine.warnings(conn):
+        print(f"  {C_RED}⚠ {w['component']}{C_RST}  val_loss={w['val_loss']:.4f} (field cutoff {w['cutoff']})")
+
+    print(f"\n{C_GRN}all assertions passed.{C_RST}")
+
+
+if __name__ == "__main__":
+    main()

forge/scraper.py

@@ -0,0 +1,360 @@
+"""Piece 2: the Bright Data scraper that grows the graph.
+
+Flow:  search (SERP) -> scrape (Web Unlocker) -> Haiku extract triples
+       -> entity-resolve against node aliases -> corroboration gate
+       -> edges (2+ independent sources) OR review_queue (single/unknown).
+
+The corroboration gate is what keeps the graph clean as it grows: a single
+scraped claim never becomes an asserted edge. It waits in review_queue until a
+second independent source says the same thing, then it promotes to a tier-2 edge.
+Tier-1 (Rick's) edges are never touched by this path.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import urllib.request
+
+from . import db
+
+# COMPATIBLE/BREAKS/DEGRADES are undirected; dedupe (a,b) and (b,a) into one edge.
+SYMMETRIC = {"COMPATIBLE", "BREAKS", "DEGRADES"}
+# Local OpenAI-compatible LLM (llama.cpp server). No API key, fully local/free.
+LLM_URL = os.environ.get("FORGE_LLM_URL", "http://localhost:8080")
+
+# Key-free extraction. Bright Data is the ONLY external dependency — no LLM API.
+# We scan scraped text for sentences mentioning >=2 known components plus a
+# relation cue word, and emit candidate triples. Noisy by design; the
+# corroboration gate (2+ independent sources) is what makes the graph clean.
+# Checked in priority order so "not compatible" classifies BREAKS, not COMPATIBLE.
+RELATION_CUES = [
+    ("BREAKS", ["incompatible with", "not compatible with", "cannot be used with",
+                "can't be used with", "does not work with", "doesn't work with",
+                "breaks with", "conflicts with", "unsupported with", "mutually exclusive",
+                "not supported with", "fails with"]),
+    ("REQUIRES", ["requires", "depends on", "only works with", "must use", "must be used with",
+                  "needs", "is required for"]),
+    ("DEGRADES", ["slower with", "degrades", "hurts performance", "worse with",
+                  "regression with", "underperforms"]),
+    ("CONDITIONAL", ["works with .* if", "compatible .* when", "as long as", "provided that",
+                     "only if", "when using"]),
+    ("COMPATIBLE", ["works with", "compatible with", "pairs with", "combined with",
+                    "alongside", "together with", "in combination with", "uses", "use",
+                    "used with", "integrated with", "built on", "based on", "leverages",
+                    "supports", "relies on", "applied to", "runs on", "paired with",
+                    "on top of", "enabled with"]),
+]
+
+
+def _brightdata(args, timeout=120):
+    r = subprocess.run(["brightdata", *args], capture_output=True, text=True, timeout=timeout)
+    return r.stdout, r.stderr, r.returncode
+
+
+def _json_from_output(out: str) -> dict:
+    """CLI prints progress lines before the JSON body; extract the JSON object."""
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError:
+        m = re.search(r"\{[\s\S]*\}", out)
+        if not m:
+            return {}
+        try:
+            return json.loads(m.group(0))
+        except json.JSONDecodeError:
+            return {}
+
+
+def search(query, n=8, country=None):
+    args = ["search", query, "--pretty"]
+    if country:
+        args += ["--country", country]
+    out, _, _ = _brightdata(args)
+    d = _json_from_output(out)
+    organic = d.get("organic") or d.get("results") or []
+    hits = []
+    for o in organic[:n]:
+        url = o.get("link") or o.get("url")
+        if url:
+            hits.append({"url": url, "title": o.get("title", ""), "description": o.get("description", "")})
+    return hits
+
+
+def fetch(url, timeout=90):
+    out, _, _ = _brightdata(["scrape", url, "--format", "markdown"], timeout=timeout)
+    return out.strip()
+
+
+def run_pipeline(ptype, *params, timeout=600):
+    """Bright Data Scraper API — structured data from a pre-built pipeline."""
+    out, err, rc = _brightdata(["pipelines", ptype, *params, "--pretty"], timeout=timeout)
+    return _json_from_output(out), (err or "").strip()
+
+
+def browser_open(url, timeout=90):
+    """Bright Data Scraping Browser — navigate a JS-heavy page, return a snapshot."""
+    out, err, rc = _brightdata(["browser", "open", url, "--pretty"], timeout=timeout)
+    return out.strip(), (err or "").strip(), rc
+
+
+# --- entity resolution -------------------------------------------------------
+
+def _norm(s: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", (s or "").lower())
+
+
+def build_resolver(conn) -> dict[str, str]:
+    """Map normalized canonical/name/alias -> canonical. Single source of truth."""
+    res = {}
+    for r in conn.execute("SELECT canonical, name, aliases_json FROM nodes").fetchall():
+        for k in [r["canonical"], r["name"], *json.loads(r["aliases_json"])]:
+            res[_norm(k)] = r["canonical"]
+    return res
+
+
+def resolve(name: str, resolver: dict[str, str]):
+    return resolver.get(_norm(name))
+
+
+# --- key-free extraction -----------------------------------------------------
+
+def _variants(alias: str) -> set[str]:
+    """Separator variants so 'adamw 8-bit' also matches 'adamw_8bit', 'adamw-8bit', etc."""
+    parts = re.split(r"[-_ ]+", alias)
+    if len(parts) == 1:
+        return {alias}
+    return {sep.join(parts) for sep in (" ", "-", "_", "")}
+
+
+def build_alias_index(conn) -> list[tuple[str, str]]:
+    """[(alias_lower, canonical)] sorted longest-first so 'adamw 8bit' beats 'adamw'."""
+    idx = set()
+    for r in conn.execute("SELECT canonical, name, aliases_json FROM nodes").fetchall():
+        for k in [r["canonical"], r["name"], *json.loads(r["aliases_json"])]:
+            for v in _variants(k.lower()):
+                idx.add((v, r["canonical"]))
+    return sorted(idx, key=lambda x: -len(x[0]))
+
+
+def _find_components(sentence: str, alias_index) -> list[str]:
+    """Canonicals mentioned, in order of first appearance, longest-alias-wins, no overlaps."""
+    s = sentence.lower()
+    consumed, found = [], []
+    for alias, canon in alias_index:  # longest first
+        for m in re.finditer(r"(?<![a-z0-9])" + re.escape(alias) + r"(?![a-z0-9])", s):
+            span = (m.start(), m.end())
+            if any(span[0] < e and span[1] > b for b, e in consumed):
+                continue
+            consumed.append(span)
+            found.append((span[0], canon))
+    seen, ordered = set(), []
+    for _, canon in sorted(found):
+        if canon not in seen:
+            seen.add(canon)
+            ordered.append(canon)
+    return ordered
+
+
+def _classify(sentence: str):
+    s = sentence.lower()
+    for relation, cues in RELATION_CUES:
+        for cue in cues:
+            if (".*" in cue and re.search(cue, s)) or (".*" not in cue and cue in s):
+                return relation
+    return None
+
+
+def extract(markdown: str, source_url: str, alias_index) -> list[dict]:
+    """Dispatch: local llama.cpp model if its server is up, else keyless heuristic."""
+    if _llm_up():
+        try:
+            return _extract_local(markdown, alias_index)
+        except Exception:  # noqa: BLE001 - never let extraction kill a run
+            pass
+    return _extract_heuristic(markdown, alias_index)
+
+
+def _clean_markdown(md: str) -> str:
+    """Strip nav/links/images and short non-prose lines so extractors see signal."""
+    md = re.sub(r"!\[[^\]]*\]\([^)]*\)", " ", md)        # images
+    md = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", md)     # links -> anchor text
+    out = []
+    for ln in md.splitlines():
+        s = ln.strip()
+        if len(s) >= 20 and s.count(" ") >= 3:           # keep prose, drop nav
+            out.append(s)
+    return "\n".join(out)
+
+
+def _extract_heuristic(markdown: str, alias_index) -> list[dict]:
+    """Scan text for (a, relation, b) candidates. Co-mention -> weak COMPATIBLE.
+    Noisy by design; the corroboration gate filters it."""
+    triples, seen = [], set()
+    for raw in re.split(r"(?<=[.!?])\s+|\n+", _clean_markdown(markdown)):
+        seg = raw.strip()
+        if len(seg) < 12 or len(seg) > 400:
+            continue
+        comps = _find_components(seg, alias_index)
+        if len(comps) < 2:
+            continue
+        relation = _classify(seg) or "COMPATIBLE"  # co-mention fallback
+        a, b = comps[0], comps[1]
+        key = (a, relation, b)
+        if a == b or key in seen:
+            continue
+        seen.add(key)
+        triples.append({"component_a": a, "relation": relation, "component_b": b,
+                        "conditions": {}, "fix": "", "evidence_quote": seg[:300]})
+    return triples
+
+
+_LLM_PROMPT = """You extract ML training-component compatibility relationships from text.
+Content may be Chinese/Japanese/English — respond in English.
+Return a JSON object: {"relations": [ {"component_a","relation","component_b","conditions","fix","evidence_quote"} ]}
+relation in: REQUIRES|CONDITIONAL|COMPATIBLE|DEGRADES|BREAKS.
+Only relationships with DIRECT textual evidence. Prefer CONDITIONAL/REQUIRES over BREAKS.
+If none, return {"relations": []}."""
+
+
+def _llm_up() -> bool:
+    try:
+        with urllib.request.urlopen(LLM_URL.rstrip("/") + "/v1/models", timeout=2) as r:
+            return r.status == 200
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _extract_local(markdown: str, alias_index) -> list[dict]:
+    """Extract via a local llama.cpp OpenAI-compatible server. No API key."""
+    vocab = sorted({c for _, c in alias_index})
+    system = _LLM_PROMPT + "\nKnown components (prefer these names when they match): " + ", ".join(vocab[:60])
+    payload = {
+        "messages": [{"role": "system", "content": system},
+                     {"role": "user", "content": _clean_markdown(markdown)[:12000]}],
+        "temperature": 0,
+        "max_tokens": 1500,
+        "response_format": {"type": "json_object"},
+    }
+    req = urllib.request.Request(
+        LLM_URL.rstrip("/") + "/v1/chat/completions",
+        data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json", "Authorization": "Bearer no-key"},
+    )
+    with urllib.request.urlopen(req, timeout=120) as r:
+        resp = json.loads(r.read())
+    text = resp["choices"][0]["message"]["content"]
+    m = re.search(r"\{[\s\S]*\}", text)
+    obj = json.loads(m.group(0)) if m else {}
+    out = []
+    for t in obj.get("relations", []):
+        comps_a = _find_components(str(t.get("component_a", "")), alias_index)
+        comps_b = _find_components(str(t.get("component_b", "")), alias_index)
+        if comps_a and comps_b:
+            t["component_a"], t["component_b"] = comps_a[0], comps_b[0]
+            out.append(t)
+    return out
+
+
+# --- ingestion with corroboration gate ---------------------------------------
+
+def _corroborated(conn, a, rel, b, source_url) -> bool:
+    """True if a DIFFERENT source already asserted this (a, rel, b). Direction-aware."""
+    if rel in SYMMETRIC:
+        rows = conn.execute(
+            "SELECT evidence_url FROM review_queue WHERE relation=? AND status='pending'"
+            " AND ((raw_a=? AND raw_b=?) OR (raw_a=? AND raw_b=?))", (rel, a, b, b, a)).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT evidence_url FROM review_queue WHERE relation=? AND status='pending'"
+            " AND raw_a=? AND raw_b=?", (rel, a, b)).fetchall()
+    return any(r["evidence_url"] and r["evidence_url"] != source_url for r in rows)
+
+
+def _existing_edge(conn, a_id, b_id, rel):
+    """Edge id if one already exists (symmetric relations match either direction)."""
+    if rel in SYMMETRIC:
+        row = conn.execute(
+            "SELECT id FROM edges WHERE relation=? AND ((from_id=? AND to_id=?) OR (from_id=? AND to_id=?))",
+            (rel, a_id, b_id, b_id, a_id)).fetchone()
+    else:
+        row = conn.execute("SELECT id FROM edges WHERE relation=? AND from_id=? AND to_id=?",
+                           (rel, a_id, b_id)).fetchone()
+    return row["id"] if row else None
+
+
+def _mark_promoted(conn, a, b, rel):
+    if rel in SYMMETRIC:
+        conn.execute("UPDATE review_queue SET status='promoted' WHERE relation=? AND"
+                     " ((raw_a=? AND raw_b=?) OR (raw_a=? AND raw_b=?))", (rel, a, b, b, a))
+    else:
+        conn.execute("UPDATE review_queue SET status='promoted' WHERE relation=? AND raw_a=? AND raw_b=?",
+                     (rel, a, b))
+
+
+def ingest(conn, triples, source_url, resolver) -> dict:
+    promoted, queued = [], []
+    for t in triples:
+        rel = (t.get("relation") or "").upper()
+        if rel not in db.RELATIONS:
+            continue
+        a = resolve(t.get("component_a", ""), resolver)
+        b = resolve(t.get("component_b", ""), resolver)
+        conditions = t.get("conditions") or {}
+
+        if not a or not b:  # unknown entity -> queue with raw names
+            db.add_review(conn, raw_a=t.get("component_a", ""), raw_b=t.get("component_b", ""),
+                          relation=rel, conditions=conditions, evidence_url=source_url)
+            queued.append((t.get("component_a"), rel, t.get("component_b")))
+            continue
+
+        ev = {"url": source_url, "quote": t.get("evidence_quote", ""),
+              "source_type": "scraped", "source_tier": 3}
+        existing = _existing_edge(conn, db.node_id(conn, a), db.node_id(conn, b), rel)
+        if existing:  # already an edge -> just accumulate evidence
+            db.add_evidence(conn, existing, ev)
+        elif _corroborated(conn, a, rel, b, source_url):  # 2nd independent source -> promote
+            db.add_edge(conn, from_canon=a, to_canon=b, relation=rel, tier=2,
+                        conditions=conditions, fix=t.get("fix", ""), evidence=[ev])
+            promoted.append((a, rel, b))
+            _mark_promoted(conn, a, b, rel)
+        else:  # single source so far -> queue (resolved canonicals)
+            db.add_review(conn, raw_a=a, raw_b=b, relation=rel, conditions=conditions, evidence_url=source_url)
+            queued.append((a, rel, b))
+    conn.commit()
+    return {"promoted": promoted, "queued": queued}
+
+
+def discover(conn, component, n=5, resolver=None, alias_index=None) -> dict:
+    """One full pass for a component: search -> scrape -> extract -> ingest.
+    Bright Data is the only external dependency."""
+    resolver = resolver or build_resolver(conn)
+    alias_index = alias_index or build_alias_index(conn)
+    queries = [
+        f'"{component}" training optimizer scheduler compatible OR incompatible',
+        f'{component} requires OR breaks OR works with fine-tuning',
+    ]
+    seen, total = set(), {"promoted": [], "queued": [], "pages": 0}
+    for q in queries:
+        for hit in search(q, n=n):
+            if hit["url"] in seen:
+                continue
+            seen.add(hit["url"])
+            md = fetch(hit["url"])
+            if not md or len(md) < 200:
+                continue
+            total["pages"] += 1
+            res = ingest(conn, extract(md, hit["url"], alias_index), hit["url"], resolver)
+            total["promoted"] += res["promoted"]
+            total["queued"] += res["queued"]
+    return total
+
+
+def feed(conn, n=10) -> list[dict]:
+    rows = conn.execute(
+        "SELECT e.relation, e.tier, e.created_at, n1.name AS a, n2.name AS b "
+        "FROM edges e JOIN nodes n1 ON n1.id=e.from_id JOIN nodes n2 ON n2.id=e.to_id "
+        "ORDER BY e.created_at DESC LIMIT ?", (n,),
+    ).fetchall()
+    return [dict(a=r["a"], relation=r["relation"], b=r["b"], tier=r["tier"], created_at=r["created_at"]) for r in rows]

forge/seed.py

@@ -0,0 +1,160 @@
+"""Seed the Forge graph.
+
+Three kinds of truth, kept honestly separate:
+  - NODES: the components.
+  - EDGES: real *relational* facts (composes / requires / breaks). Tiered.
+  - BENCHMARKS: real *performance* evidence (Rick's LR-scheduler benchmark).
+    Drives recommendations, NOT the grey-out graph.
+Unverified ecosystem claims go to review_queue, never asserted as live edges.
+"""
+from __future__ import annotations
+
+from . import db
+
+BENCH_URL = "https://huggingface.co/spaces/juiceb0xc0de/lr-scheduler-benchmark"
+MEMPALACE = "mempalace://chaos-injection-trainer-notes"
+
+# (canonical, type, display_name, aliases, description)
+NODES = [
+    # optimizers
+    ("adamw", "optimizer", "AdamW", ["adam", "adamw_torch"], "Decoupled weight-decay Adam. The benchmark's fixed optimizer."),
+    ("adamw_8bit", "optimizer", "AdamW 8-bit", ["adamw8bit", "bnb_adamw_8bit"], "bitsandbytes 8-bit AdamW. Default decay/no-decay param groups."),
+    ("paged_adamw_8bit", "optimizer", "Paged AdamW 8-bit", ["paged_adamw"], "Paged 8-bit AdamW; pairs with QLoRA in the QLoRA paper."),
+    ("muon", "optimizer", "Muon", [], "Orthogonalizing momentum optimizer for 2D weight matrices."),
+    # schedulers (subset; benchmark covers 25)
+    ("cosine", "scheduler", "Cosine", ["cosine_schedule"], "Cosine decay LR schedule."),
+    ("wsd", "scheduler", "WSD", ["warmup_stable_decay"], "Warmup-Stable-Decay schedule."),
+    ("constant", "scheduler", "Constant", ["constant_lr"], "Flat LR. Topped accuracy in the benchmark."),
+    ("linear", "scheduler", "Linear", ["linear_decay"], "Linear decay schedule."),
+    ("onecycle", "scheduler", "OneCycle", ["one_cycle"], "One-cycle policy. Clear underperformer on short classification finetune."),
+    ("deep_chaos_scheduler", "scheduler", "DeepChaosScheduler", ["lucky_pick", "lucky-pick-scheduler"], "Rick's scheduler. Top-tier accuracy in the benchmark."),
+    ("aecs", "scheduler", "AECS", [], "Rick's AECS scheduler. #3 on val_loss in the benchmark."),
+    ("dlrs", "scheduler", "DLRS", [], "Rick's dynamic LR scheduler. #1 on val_loss in the benchmark."),
+    ("greedy_lr", "scheduler", "GreedyLR", [], "Rick's greedy LR scheduler. #2 on val_loss in the benchmark."),
+    # techniques
+    ("lora", "technique", "LoRA", [], "Low-rank adaptation."),
+    ("qlora", "technique", "QLoRA", [], "LoRA on a 4-bit quantized base."),
+    ("fft", "technique", "Full Fine-Tune", ["full_finetune", "full_finetuning"], "Update all weights."),
+    ("gradient_checkpointing", "technique", "Gradient Checkpointing", ["grad_ckpt", "checkpointing"], "Trade compute for memory by recomputing activations."),
+    ("response_only", "technique", "Response-Only Training", ["completion_only", "response_only_training"], "Loss only on completion tokens."),
+    ("packed_sequences", "technique", "Packed Sequences", ["packing"], "Pack multiple samples per sequence."),
+    ("per_layer_lr_rotation", "technique", "Per-Layer LR Rotation", ["wavelength_rotation"], "Rotate LR across layer bands during training."),
+    # quantization
+    ("bnb_4bit", "quantization", "bnb 4-bit", ["nf4", "4bit"], "bitsandbytes 4-bit (NF4) base quantization."),
+    ("bnb_8bit", "quantization", "bnb 8-bit", ["8bit"], "bitsandbytes 8-bit quantization."),
+    # inference
+    ("vllm", "inference", "vLLM", [], "High-throughput inference/generation engine."),
+    # architectures
+    ("qwen2_5", "architecture", "Qwen2.5", ["qwen2.5", "qwen"], "Qwen2.5 family."),
+    ("llama3", "architecture", "Llama 3", ["llama-3"], "Llama 3 family."),
+    ("gemma2", "architecture", "Gemma 2", ["gemma"], "Gemma 2 family."),
+    ("distilbert", "architecture", "DistilBERT", ["distilbert-base-uncased"], "Benchmark model: DistilBERT on SST-2."),
+]
+
+# Real relational edges. tier 1 = Rick-verified; tier 2 = documented/definitional.
+EDGES = [
+    # --- tier 1: verified in Rick's mempalace / codebase ---
+    dict(from_canon="per_layer_lr_rotation", to_canon="adamw_8bit", relation="BREAKS", tier=1,
+         fix="Pass custom optimizer_grouped_parameters split by layer band, OR apply the LR as a per-param multiplier instead of relying on default groups.",
+         evidence=[dict(url=MEMPALACE, source_type="practitioner_run",
+                        quote="adamw_8bit produces decay/no-decay param groups by default, not layer-band groups; WavelengthRotationCallback maps params to layers but the plumbing doesn't reach the right target.")]),
+    dict(from_canon="deep_chaos_scheduler", to_canon="adamw", relation="COMPATIBLE", tier=1,
+         evidence=[dict(url=MEMPALACE, source_type="practitioner_run",
+                        quote="DeepChaosScheduler runs on top of AdamW; confirmed in Rick's codebase and the LR-scheduler benchmark.")]),
+
+    # --- tier 2: documented / definitional ---
+    dict(from_canon="qlora", to_canon="bnb_4bit", relation="REQUIRES", tier=2,
+         fix="QLoRA fine-tunes LoRA adapters over a 4-bit (NF4) frozen base by definition.",
+         evidence=[dict(url="https://arxiv.org/abs/2305.14314", source_type="paper",
+                        quote="QLoRA backpropagates gradients through a frozen, 4-bit quantized base model into LoRA adapters.")]),
+    dict(from_canon="qlora", to_canon="paged_adamw_8bit", relation="COMPATIBLE", tier=2,
+         evidence=[dict(url="https://arxiv.org/abs/2305.14314", source_type="paper",
+                        quote="QLoRA uses paged optimizers to manage memory spikes.")]),
+    dict(from_canon="qlora", to_canon="fft", relation="BREAKS", tier=2,
+         fix="QLoRA and full fine-tuning are mutually exclusive training modes for one run; pick one.",
+         evidence=[dict(url="https://arxiv.org/abs/2305.14314", source_type="paper",
+                        quote="QLoRA freezes the base model and trains only adapters; full fine-tuning updates all weights.")]),
+    dict(from_canon="response_only", to_canon="packed_sequences", relation="CONDITIONAL", tier=2,
+         conditions={"loss_mask": "packing_aware"},
+         fix="Use a completion-only loss mask that is packing-aware so loss isn't computed across packed sample boundaries.",
+         evidence=[dict(url="https://huggingface.co/docs/trl", source_type="docs",
+                        quote="Completion-only loss with packed sequences requires correct masking at sample boundaries.")]),
+    dict(from_canon="vllm", to_canon="gradient_checkpointing", relation="CONDITIONAL", tier=2,
+         conditions={"gradient_checkpointing": "enabled"},
+         fix="Keep gradient_checkpointing ENABLED — disabling it is not compatible with vLLM generation (TRL).",
+         evidence=[dict(url="https://huggingface.co/docs/trl", source_type="docs",
+                        quote="Disabling this option is not compatible with vLLM generation.")]),
+    dict(from_canon="gradient_checkpointing", to_canon="lora", relation="COMPATIBLE", tier=2,
+         evidence=[dict(url="https://huggingface.co/docs/peft", source_type="docs",
+                        quote="Gradient checkpointing is commonly combined with LoRA to cut activation memory.")]),
+]
+
+# Unverified ecosystem claims — proposed, NOT asserted. Sit in review_queue until
+# corroborated by 2+ sources or Rick approves.
+REVIEW = [
+    dict(raw_a="muon", raw_b="bnb_4bit", relation="CONDITIONAL",
+         conditions={"note": "Muon orthogonalizes 2D weight matrices; whether it composes cleanly with a 4-bit frozen base is unverified."},
+         evidence_url=""),
+    dict(raw_a="muon", raw_b="mup_scaling", relation="COMPATIBLE",
+         conditions={"note": "Claimed in 'Practical Efficiency of Muon' — needs a real source before promotion."},
+         evidence_url=""),
+]
+
+# Rick's LR-scheduler benchmark leaderboard. DistilBERT / SST-2, 3 seeds each.
+# tuple: (scheduler, val_loss_mean, val_loss_std, val_acc_mean, val_acc_std, steps_to_target)
+BENCH_MODEL, BENCH_TASK = "distilbert-base-uncased", "glue/sst2"
+BENCH_CONDITIONS = {"batch_size": 32, "num_epochs": 3, "lr": 2e-5, "weight_decay": 0.01,
+                    "warmup_fraction": 0.06, "target_loss": 0.35}
+LEADERBOARD = [
+    ("dlrs", 0.26528, 0.00207, 0.89029, 0.00369, 266.7),
+    ("greedy_lr", 0.26876, 0.00651, 0.89220, 0.00344, 266.7),
+    ("aecs", 0.29851, 0.00828, 0.90443, 0.00369, 400.0),
+    ("cosine_with_restarts", 0.30654, 0.01373, 0.90482, 0.00607, 266.7),
+    ("rex", 0.30660, 0.01280, 0.90405, 0.00265, 266.7),
+    ("exp_increasing", 0.31259, 0.06081, 0.89144, 0.00672, 1850.0),
+    ("step_decay", 0.31675, 0.00386, 0.90138, 0.00115, 266.7),
+    ("wsd_long", 0.31957, 0.01864, 0.90099, 0.00350, 266.7),
+    ("wsd", 0.32265, 0.01259, 0.90329, 0.00132, 266.7),
+    ("cyclic_lr", 0.33390, 0.00633, 0.90214, 0.00239, 250.0),
+    ("constant_with_warmup", 0.34331, 0.00169, 0.90023, 0.00413, 266.7),
+    ("polynomial", 0.34423, 0.00307, 0.90443, 0.00477, 266.7),
+    ("scaling_law_opt", 0.34616, 0.01730, 0.90482, 0.00229, 266.7),
+    ("plateau_reduction", 0.34947, 0.00682, 0.90176, 0.00662, 266.7),
+    ("cosine_annealing", 0.35219, 0.02189, 0.90405, 0.00701, 266.7),
+    ("constant", 0.35229, 0.03222, 0.90749, 0.00463, 150.0),
+    ("cosine", 0.35329, 0.01951, 0.90329, 0.00577, 266.7),
+    ("rlrs", 0.35473, 0.00483, 0.90214, 0.00350, 266.7),
+    ("sqrt_scheduler", 0.35477, 0.01790, 0.89985, 0.00066, 266.7),
+    ("inverse_sqrt", 0.35477, 0.01790, 0.89985, 0.00066, 266.7),
+    ("mnist_example", 0.35602, 0.03941, 0.90558, 0.00588, 150.0),
+    ("exponential", 0.35784, 0.01552, 0.90176, 0.00434, 266.7),
+    ("lucky_pick", 0.35881, 0.01650, 0.90635, 0.00239, 266.7),
+    ("linear", 0.35951, 0.01049, 0.90596, 0.00229, 266.7),
+    ("onecycle", 0.42844, 0.02122, 0.86430, 0.00403, 183.3),
+]
+
+
+def seed(path=db.DB_PATH):
+    conn = db.reset(path)
+    for canon, type_, name, aliases, desc in NODES:
+        db.add_node(conn, type=type_, name=name, canonical=canon, aliases=aliases, description=desc)
+    for e in EDGES:
+        db.add_edge(conn, **e)
+    for r in REVIEW:
+        db.add_review(conn, **r)
+    for sched, lm, ls, am, asd, stt in LEADERBOARD:
+        db.add_benchmark(conn, component=sched, model=BENCH_MODEL, task=BENCH_TASK,
+                         val_loss_mean=lm, val_loss_std=ls, val_acc_mean=am, val_acc_std=asd,
+                         steps_to_target=stt, n_seeds=3, conditions=BENCH_CONDITIONS,
+                         source_url=BENCH_URL, tier=1)
+    conn.commit()
+    return conn
+
+
+if __name__ == "__main__":
+    c = seed()
+    n = c.execute("SELECT COUNT(*) FROM nodes").fetchone()[0]
+    e = c.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+    b = c.execute("SELECT COUNT(*) FROM benchmarks").fetchone()[0]
+    q = c.execute("SELECT COUNT(*) FROM review_queue").fetchone()[0]
+    print(f"seeded: {n} nodes, {e} edges, {b} benchmark rows, {q} review-queue items")

forge/test_scraper.py

@@ -0,0 +1,61 @@
+"""Offline proof for piece 2: extractor + corroboration gate. No network, no keys.
+
+Run:  python -m forge.test_scraper
+Proves the graph-growth logic is sound before we spend a single Bright Data credit.
+"""
+from __future__ import annotations
+
+from . import seed as seed_mod
+from . import scraper
+
+C_GRN, C_YEL, C_DIM, C_RST = "\033[92m", "\033[93m", "\033[2m", "\033[0m"
+
+
+def main():
+    conn = seed_mod.seed()
+    alias_index = scraper.build_alias_index(conn)
+    resolver = scraper.build_resolver(conn)
+
+    # 1. extractor: longest-alias-wins + negation-aware classification
+    comps = scraper._find_components("training adamw8bit with a cosine schedule", alias_index)
+    assert "adamw_8bit" in comps and "adamw" not in comps, f"longest-alias-wins failed: {comps}"
+    assert scraper._classify("Muon is not compatible with 4bit") == "BREAKS"
+    assert scraper._classify("QLoRA works with LoRA adapters") == "COMPATIBLE"
+    assert scraper._classify("OneCycle requires a warmup phase and cosine") == "REQUIRES"
+    print(f"{C_GRN}✓ extractor: alias resolution + relation classification{C_RST}")
+
+    # 2. a single scraped page -> candidate triples (heuristic path, hermetic:
+    #    call _extract_heuristic directly so the test never depends on a live LLM server)
+    page1 = "In our runs, Muon is incompatible with 4bit quantization on consumer GPUs."
+    triples = scraper._extract_heuristic(page1, alias_index)
+    assert any(t["component_a"] == "muon" and t["relation"] == "BREAKS" and t["component_b"] == "bnb_4bit"
+               for t in triples), f"expected muon-BREAKS-bnb_4bit, got {triples}"
+    print(f"{C_GRN}✓ extract: found (muon, BREAKS, bnb_4bit) from scraped text{C_RST}")
+
+    # 3. THE GATE: one source queues, a second independent source promotes to an edge
+    before = conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+    r1 = scraper.ingest(conn, triples, "https://src-one.example/post", resolver)
+    assert r1["queued"] and not r1["promoted"], "first source must queue, not assert"
+    assert conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0] == before, "no edge from one source"
+    print(f"{C_YEL}◐ source 1: queued (not asserted) — {r1['queued']}{C_RST}")
+
+    page2 = "We confirmed Muon does not work with 4bit during fine-tuning."
+    triples2 = scraper._extract_heuristic(page2, alias_index)
+    r2 = scraper.ingest(conn, triples2, "https://src-two.example/thread", resolver)
+    assert ("muon", "BREAKS", "bnb_4bit") in r2["promoted"], f"second source should promote, got {r2}"
+    after = conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+    assert after == before + 1, "exactly one new edge after corroboration"
+    print(f"{C_GRN}● source 2 (independent): PROMOTED to tier-2 edge — {r2['promoted']}{C_RST}")
+
+    # 4. it shows up in the live feed
+    top = scraper.feed(conn, n=3)
+    assert any(f["a"] == "Muon" and f["b"] == "bnb 4-bit" for f in top), f"edge not in feed: {top}"
+    print(f"\n{C_DIM}── live feed (newest edges) ──{C_RST}")
+    for f in top:
+        print(f"  {f['a']} —{f['relation']}→ {f['b']}  (T{f['tier']})  {C_DIM}{f['created_at'][:19]}{C_RST}")
+
+    print(f"\n{C_GRN}all assertions passed — gate keeps single-source claims out of the graph.{C_RST}")
+
+
+if __name__ == "__main__":
+    main()

frontend/app.jsx

@@ -0,0 +1,309 @@
+// FORGE — main app
+// Wires the inventory, graph, recipe card, ticker, tooltip, and resolve state.
+
+const { useState, useEffect, useMemo, useCallback, useRef } = React;
+
+const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+  "showTicker": true,
+  "showSparks": true,
+  "sound": true,
+  "edgeIntensity": "balanced",
+  "demoMode": false,
+  "preset": "blank"
+}/*EDITMODE-END*/;
+
+function App() {
+  const nodes = window.FORGE_NODES;
+  const edges = window.FORGE_EDGES;
+
+  const [t, setTweak] = window.useTweaks(TWEAK_DEFAULTS);
+
+  const [selected, setSelected] = useState([]);
+  const [hover, setHover] = useState(null); // { node, edge, status, reasons, pos }
+
+  // Recompute resolved status whenever selection changes.
+  const resolved = useMemo(() => window.forgeResolve(selected), [selected]);
+  const recipe   = useMemo(() => window.forgeRecipe(selected), [selected]);
+
+  const toggleSelect = useCallback((canon) => {
+    setSelected(prev => {
+      // Don't allow selecting blocked nodes — give feedback by briefly shaking
+      const r = window.forgeResolve(prev);
+      const cur = r[canon];
+      if (cur && cur.status === "blocked" && !prev.includes(canon)) {
+        flashBlocked(canon);
+        window.forgeSound && window.forgeSound.sizzle();
+        return prev;
+      }
+      if (prev.includes(canon)) {
+        window.forgeSound && window.forgeSound.thud();
+        return prev.filter(x => x !== canon);
+      }
+      window.forgeSound && window.forgeSound.clang();
+      return [...prev, canon];
+    });
+  }, []);
+
+  const addOnly = useCallback((canon) => {
+    setSelected(prev => {
+      if (prev.includes(canon)) return prev;
+      window.forgeSound && window.forgeSound.chime();
+      return [...prev, canon];
+    });
+  }, []);
+
+  const removeOnly = useCallback((canon) => {
+    setSelected(prev => {
+      if (!prev.includes(canon)) return prev;
+      window.forgeSound && window.forgeSound.thud();
+      return prev.filter(x => x !== canon);
+    });
+  }, []);
+
+  // ── Hover handlers ──────────────────────────────────────────────────────
+  const onHoverNode = useCallback((node, ev) => {
+    if (!node) { setHover(null); return; }
+    const r = resolved[node.canonical] || { status: "available", reasons: [] };
+    setHover({
+      node,
+      status: selected.includes(node.canonical) ? "selected" : r.status,
+      reasons: r.reasons || [],
+      pos: { x: ev?.clientX ?? 100, y: ev?.clientY ?? 100 },
+    });
+  }, [resolved, selected]);
+
+  const onHoverEdge = useCallback((edge, ev) => {
+    if (!edge) { setHover(null); return; }
+    setHover({ edge, pos: { x: ev?.clientX ?? 100, y: ev?.clientY ?? 100 } });
+  }, []);
+
+  // Track cursor for tooltip following
+  useEffect(() => {
+    const move = (ev) => {
+      setHover(h => h ? { ...h, pos: { x: ev.clientX, y: ev.clientY } } : h);
+    };
+    window.addEventListener("mousemove", move);
+    return () => window.removeEventListener("mousemove", move);
+  }, []);
+
+  // ── Demo path: scripted Muon → QLoRA → bnb_4bit → DLRS ───────────────────
+  const demoTimer = useRef(null);
+  useEffect(() => {
+    if (!t.demoMode) {
+      if (demoTimer.current) { clearTimeout(demoTimer.current); demoTimer.current = null; }
+      return;
+    }
+    const steps = [
+      { at: 800,   action: () => setSelected(["muon"]) },
+      { at: 3200,  action: () => setSelected(["muon", "qlora"]) },
+      { at: 5800,  action: () => setSelected(["muon", "qlora", "bnb_4bit"]) },
+      { at: 8400,  action: () => setSelected(["muon", "qlora", "bnb_4bit", "lora", "llama3", "dlrs"]) },
+      { at: 14000, action: () => setSelected([]) },
+    ];
+    setSelected([]);
+    let cancelled = false;
+    let i = 0;
+    const tick = () => {
+      if (cancelled || i >= steps.length) return;
+      steps[i].action();
+      i++;
+      if (i < steps.length) {
+        demoTimer.current = setTimeout(tick, steps[i].at - (steps[i-1]?.at || 0));
+      } else {
+        // loop
+        demoTimer.current = setTimeout(() => { i = 0; tick(); }, 2000);
+      }
+    };
+    demoTimer.current = setTimeout(tick, steps[0].at);
+    return () => { cancelled = true; if (demoTimer.current) clearTimeout(demoTimer.current); };
+  }, [t.demoMode]);
+
+  // Sync sound mute state with the tweak
+  useEffect(() => {
+    if (window.forgeSound) window.forgeSound.setMuted(!t.sound);
+  }, [t.sound]);
+
+  // Apply presets from Tweaks
+  useEffect(() => {
+    if (t.preset === "blank") return;
+    const presets = {
+      "qlora-llama":   ["qlora", "lora", "bnb_4bit", "llama3", "dlrs"],
+      "muon-collide":  ["muon", "adamw_8bit"],
+      "rick-tier1":    ["per_layer_lr_rotation", "adamw_8bit"],
+      "vllm-ckpt":     ["grad_ckpt", "vllm", "qlora"],
+      "chaos":         ["chaos_inject", "jacobian_reg"],
+    };
+    if (presets[t.preset]) setSelected(presets[t.preset]);
+    // Reset the tweak so user can re-trigger
+    setTimeout(() => setTweak("preset", "blank"), 100);
+  }, [t.preset]);
+
+  return (
+    <div className="app">
+      {t.showSparks && <Sparks />}
+
+      <Topbar />
+
+      <div className="main">
+        <window.Inventory
+          nodes={nodes}
+          resolved={resolved}
+          selected={selected}
+          onToggleSelect={toggleSelect}
+          onHoverNode={onHoverNode}
+        />
+
+        <window.ForgeGraph
+          nodes={nodes}
+          edges={edges}
+          resolved={resolved}
+          selected={selected}
+          onToggleSelect={toggleSelect}
+          onHoverNode={onHoverNode}
+          onHoverEdge={onHoverEdge}
+        />
+
+        <window.RecipeCard
+          selected={selected}
+          nodes={nodes}
+          recipe={recipe}
+          onRemove={removeOnly}
+          onSelect={addOnly}
+          onHoverNode={onHoverNode}
+        />
+      </div>
+
+      {t.showTicker && <window.DiscoveriesTicker />}
+
+      <window.EvidenceTip payload={hover} />
+
+      <window.TweaksPanel title="Tweaks">
+        <window.TweakSection label="Demo">
+          <window.TweakToggle label="Auto-demo path" value={t.demoMode}
+                              onChange={v => setTweak("demoMode", v)} />
+          <window.TweakSelect
+            label="Preset build"
+            value={t.preset}
+            options={[
+              { value: "blank", label: "— pick —" },
+              { value: "qlora-llama",  label: "QLoRA · Llama-3 · DLRS" },
+              { value: "muon-collide", label: "Muon × AdamW 8-bit (breaks)" },
+              { value: "rick-tier1",   label: "Per-Layer LR × AdamW 8-bit (T1)" },
+              { value: "vllm-ckpt",    label: "vLLM × Grad Ckpt (breaks)" },
+              { value: "chaos",        label: "Chaos × Jacobian (breaks)" },
+            ]}
+            onChange={v => setTweak("preset", v)}
+          />
+        </window.TweakSection>
+        <window.TweakSection label="Atmosphere">
+          <window.TweakToggle label="Show ticker" value={t.showTicker} onChange={v => setTweak("showTicker", v)} />
+          <window.TweakToggle label="Background sparks" value={t.showSparks} onChange={v => setTweak("showSparks", v)} />
+          <window.TweakToggle label="Forge sounds" value={t.sound} onChange={v => setTweak("sound", v)} />
+        </window.TweakSection>
+      </window.TweaksPanel>
+    </div>
+  );
+}
+
+function Topbar() {
+  return (
+    <div className="topbar">
+      <div className="brand">
+        <div className="mark">
+          {/* Anvil + sparks emblem */}
+          <svg width="26" height="26" viewBox="0 0 32 32" fill="none">
+            <defs>
+              <linearGradient id="anvil-grad" x1="0" y1="0" x2="0" y2="1">
+                <stop offset="0" stopColor="#c4934e"/>
+                <stop offset="1" stopColor="#5a3818"/>
+              </linearGradient>
+            </defs>
+            {/* anvil silhouette */}
+            <path d="M5 14 h17 l3 -3 h4 v4 h-3 l-2 2 h-3 v4 h2 v3 h-13 v-3 h2 v-4 h-7 z"
+                  fill="url(#anvil-grad)" stroke="#2a1a08" strokeWidth="0.7" strokeLinejoin="round"/>
+            {/* base */}
+            <rect x="10" y="25" width="13" height="2" fill="#2a1a08"/>
+            {/* hot dot on anvil face */}
+            <circle cx="17" cy="15" r="1.3" fill="#ffba5e" opacity="0.95">
+              <animate attributeName="opacity" values="0.6;1;0.6" dur="2.2s" repeatCount="indefinite"/>
+            </circle>
+            {/* sparks */}
+            <circle cx="9" cy="8" r="0.9" fill="#ffba5e"/>
+            <circle cx="13" cy="5" r="0.6" fill="#ff8a3d"/>
+            <circle cx="20" cy="6" r="0.7" fill="#ffba5e"/>
+          </svg>
+        </div>
+        <div>
+          <div className="name">FORGE</div>
+          <div className="tag">a compatibility graph for ML training</div>
+        </div>
+      </div>
+
+      <div className="legend">
+        <span className="swatch"><span className="sw t1" /> T1 · Legendary</span>
+        <span className="swatch"><span className="sw t2" /> T2 · Rare</span>
+        <span className="swatch"><span className="sw t3" /> T3 · Common</span>
+      </div>
+
+      <div className="crumbs">
+        <span className="api-pill"><span className="dot" /> api · online</span>
+        <span style={{ color: "var(--bone-4)" }}>
+          {window.FORGE_NODES.length} nodes · {window.FORGE_EDGES.length} edges
+        </span>
+        <span style={{ color: "var(--bone-4)" }}>hf.co/spaces/forge</span>
+      </div>
+    </div>
+  );
+}
+
+// Sparks background — random spark spans positioned via JS
+function Sparks() {
+  const sparks = useMemo(() => {
+    return Array.from({ length: 18 }, () => ({
+      left: Math.random() * 100,
+      delay: Math.random() * 16,
+      dur: 14 + Math.random() * 18,
+      size: 0.6 + Math.random() * 1.6,
+    }));
+  }, []);
+  return (
+    <div className="sparks">
+      {sparks.map((s, i) => (
+        <span key={i} style={{
+          left: s.left + "%",
+          animationDuration: s.dur + "s",
+          animationDelay: -s.delay + "s",
+          transform: `scale(${s.size})`,
+        }} />
+      ))}
+    </div>
+  );
+}
+
+// briefly flash a node red on a blocked-click attempt
+function flashBlocked(canon) {
+  const svg = document.querySelector(`g.node[data-canon="${cssEscape(canon)}"]`);
+  if (!svg) return;
+  svg.animate(
+    [
+      { transform: svg.getAttribute("transform") + " translateX(0)" },
+      { transform: svg.getAttribute("transform") + " translateX(-3px)" },
+      { transform: svg.getAttribute("transform") + " translateX(3px)" },
+      { transform: svg.getAttribute("transform") + " translateX(-2px)" },
+      { transform: svg.getAttribute("transform") + " translateX(0)" },
+    ],
+    { duration: 220, easing: "ease-out" }
+  );
+}
+function cssEscape(s) {
+  if (window.CSS && window.CSS.escape) return window.CSS.escape(s);
+  return String(s).replace(/[^a-zA-Z0-9_-]/g, "\\$&");
+}
+
+// Fetch live data (or fall back to bundled mock) before first render.
+(window.forgeBootstrap ? window.forgeBootstrap() : Promise.resolve())
+  .catch(() => {})
+  .finally(() => {
+    if (window.FORGE_LIVE) console.info("[forge] live API graph loaded");
+    ReactDOM.createRoot(document.getElementById("root")).render(<App />);
+  });

frontend/data.js

@@ -0,0 +1,373 @@
+// Forge — mock graph + resolve engine
+// Matches the FastAPI shapes in the handoff doc, so swap to fetch() later.
+
+window.FORGE_NODES = [
+  // optimizers
+  { canonical: "adamw",        name: "AdamW",            type: "optimizer",    description: "Workhorse decoupled-weight-decay optimizer. Safe default.", tier: 1 },
+  { canonical: "adamw_8bit",   name: "AdamW 8-bit",      type: "optimizer",    description: "bitsandbytes 8-bit AdamW. Saves VRAM. Default param groups can fight per-layer LR tricks.", tier: 1 },
+  { canonical: "paged_adamw",  name: "Paged AdamW",      type: "optimizer",    description: "CPU-paged optimizer states. For when you really can't fit.", tier: 2 },
+  { canonical: "lion",         name: "Lion",             type: "optimizer",    description: "Sign-momentum optimizer. Lower memory than AdamW; needs lower LR.", tier: 2 },
+  { canonical: "muon",         name: "Muon",             type: "optimizer",    description: "Newton–Schulz orthogonalized momentum. Faster convergence on hidden weights.", tier: 2 },
+  { canonical: "sophia",       name: "Sophia-G",         type: "optimizer",    description: "Hessian-informed second-order. Promising for LLMs.", tier: 3 },
+  { canonical: "adafactor",    name: "Adafactor",        type: "optimizer",    description: "Memory-light. Tricky LR schedule.", tier: 2 },
+
+  // schedulers
+  { canonical: "cosine",       name: "Cosine",           type: "scheduler",    description: "Cosine decay with warmup. Boring; works.", tier: 1 },
+  { canonical: "onecycle",     name: "OneCycle",         type: "scheduler",    description: "Aggressive warm-then-anneal. Faster but can overshoot on long runs.", tier: 2 },
+  { canonical: "dlrs",         name: "DLRS",             type: "scheduler",    description: "Rick's dynamic LR scheduler. #1 on val_loss in the bench.", tier: 1 },
+  { canonical: "linear",       name: "Linear",           type: "scheduler",    description: "Linear warmup → linear decay.", tier: 1 },
+  { canonical: "wsd",          name: "WSD",              type: "scheduler",    description: "Warmup–Stable–Decay. Continual-pretrain friendly.", tier: 2 },
+  { canonical: "constant",     name: "Constant",         type: "scheduler",    description: "Flat. Combine with manual restarts.", tier: 1 },
+
+  // techniques
+  { canonical: "qlora",        name: "QLoRA",            type: "technique",    description: "4-bit base + LoRA adapters. Lets a 70B fit on one card.", tier: 1 },
+  { canonical: "lora",         name: "LoRA",             type: "technique",    description: "Low-rank adapters. Cheap, composable, the default PEFT.", tier: 1 },
+  { canonical: "fft",          name: "Full Fine-Tune",   type: "technique",    description: "Update every parameter. Hungry. Mutually exclusive with adapter methods.", tier: 1 },
+  { canonical: "grad_ckpt",    name: "Grad Checkpoint",  type: "technique",    description: "Trade FLOPs for VRAM. Must be off for vLLM gen during training.", tier: 1 },
+  { canonical: "per_layer_lr_rotation", name: "Per-Layer LR Rotation", type: "technique", description: "Rick's trick: rotate LR across layer bands per step. Needs custom param groups.", tier: 1 },
+  { canonical: "chaos_inject", name: "Chaos Injectors",  type: "technique",    description: "Activation perturbation at hidden layers. NaN-prone without staged melt-in.", tier: 1 },
+  { canonical: "jacobian_reg", name: "Jacobian Reg",     type: "technique",    description: "Smoothness penalty via Jacobian. Forward pass corrupts the injector cache.", tier: 1 },
+  { canonical: "fsdp",         name: "FSDP",             type: "technique",    description: "Fully-Sharded Data Parallel. Sharding for big models.", tier: 1 },
+  { canonical: "ddp",          name: "DDP",              type: "technique",    description: "Vanilla data-parallel. Cheap when the model fits.", tier: 1 },
+  { canonical: "deepspeed_z3", name: "DeepSpeed ZeRO-3", type: "technique",    description: "ZeRO stage 3 partitioning. Battle-tested.", tier: 1 },
+  { canonical: "unsloth",      name: "Unsloth",          type: "technique",    description: "Fused kernels for LoRA/QLoRA. PyTorch-only; tight coupling to bnb.", tier: 2 },
+
+  // quantization
+  { canonical: "bnb_4bit",     name: "bnb 4-bit",        type: "quantization", description: "bitsandbytes NF4. The QLoRA base.", tier: 1 },
+  { canonical: "bnb_8bit",     name: "bnb 8-bit",        type: "quantization", description: "LLM.int8(). Inference-leaning; training works.", tier: 1 },
+  { canonical: "gptq",         name: "GPTQ",             type: "quantization", description: "Post-training quant. Inference-only for our purposes.", tier: 2 },
+  { canonical: "awq",          name: "AWQ",              type: "quantization", description: "Activation-aware weight quant. Inference-time.", tier: 2 },
+
+  // architectures
+  { canonical: "llama3",       name: "Llama-3",          type: "architecture", description: "Llama-3 8B / 70B family.", tier: 1 },
+  { canonical: "mistral",      name: "Mistral",          type: "architecture", description: "Mistral / Mixtral.", tier: 1 },
+  { canonical: "qwen2",        name: "Qwen-2.5",         type: "architecture", description: "Strong open multilingual base.", tier: 1 },
+  { canonical: "distilbert",   name: "DistilBERT",       type: "architecture", description: "The bench model. SST-2 sandbox.", tier: 1 },
+
+  // inference
+  { canonical: "vllm",         name: "vLLM",             type: "inference",    description: "PagedAttention server. Needs grad-ckpt off during in-train generation.", tier: 1 },
+  { canonical: "sglang",       name: "SGLang",           type: "inference",    description: "Structured-gen server.", tier: 2 },
+];
+
+// edges. relations: REQUIRES, CONDITIONAL, COMPATIBLE, DEGRADES, BREAKS
+// Direction: from → to. For REQUIRES: "from needs to to work".
+// For BREAKS: symmetric in display but stored once.
+window.FORGE_EDGES = [
+  // --- T1 verified seed (from the backend doc) -----------------------------
+  { from: "per_layer_lr_rotation", to: "adamw_8bit", relation: "BREAKS", tier: 1, confidence: 1.0,
+    fix: "Pass custom optimizer_grouped_parameters — adamw_8bit's default decay/no-decay split overrides your per-layer LR bands.",
+    evidence: [{ url: "mempalace://chaos-injection-trainer-notes", quote: "adamw_8bit produces decay/no-decay param groups by default; per-layer LR rotation silently no-ops unless you pass optimizer_grouped_parameters yourself.", source_type: "practitioner_run", tier: 1 }] },
+
+  { from: "jacobian_reg", to: "chaos_inject", relation: "BREAKS", tier: 1, confidence: 1.0,
+    fix: "Jacobian-reg's extra forward pass corrupts the injector activation cache → ortho_loss is poisoned. Disable one.",
+    evidence: [{ url: "mempalace://chaos-injection-trainer-notes", quote: "the jacobian reg forward overwrites the activation cache that chaos_inject samples from; ortho_loss explodes.", source_type: "practitioner_run", tier: 1 }] },
+
+  { from: "chaos_inject", to: "staged_meltin", relation: "REQUIRES", tier: 1, confidence: 1.0,
+    fix: "Stage injectors in over ~100 steps; NaN at layer ~6 if injected from step 0.",
+    evidence: [{ url: "mempalace://chaos-injection-trainer-notes", quote: "NaN at injector layer ~6 if run from step 0; staged melt-in over 100 steps fixed it.", source_type: "practitioner_run", tier: 1 }] },
+
+  { from: "grad_ckpt", to: "vllm", relation: "BREAKS", tier: 1, confidence: 1.0,
+    fix: "Disable gradient_checkpointing for the in-train vLLM gen pass. TRL-documented.",
+    evidence: [{ url: "https://huggingface.co/docs/trl", quote: "gradient_checkpointing must be disabled when generating with vLLM during training.", source_type: "official_docs", tier: 1 }] },
+
+  // --- core technique mutex / requires -------------------------------------
+  { from: "qlora", to: "fft", relation: "BREAKS", tier: 1, confidence: 1.0,
+    fix: "QLoRA freezes the base model; Full Fine-Tune updates it. Pick one.",
+    evidence: [{ url: "https://arxiv.org/abs/2305.14314", quote: "QLoRA backprops gradients through a frozen 4-bit quantized model into low-rank adapters.", source_type: "paper", tier: 1 }] },
+
+  { from: "qlora", to: "bnb_4bit", relation: "REQUIRES", tier: 1, confidence: 1.0,
+    fix: "QLoRA is defined as 4-bit NF4 base + LoRA adapters — load the base in bnb 4-bit.",
+    evidence: [{ url: "https://huggingface.co/docs/peft", quote: "QLoRA fine-tunes a 4-bit quantized base model loaded via bitsandbytes NF4.", source_type: "official_docs", tier: 1 }] },
+
+  { from: "qlora", to: "lora", relation: "REQUIRES", tier: 1, confidence: 1.0,
+    fix: "QLoRA = 4-bit base + LoRA adapters. The adapter rank is your hyperparameter.",
+    evidence: [{ url: "https://arxiv.org/abs/2305.14314", quote: "QLoRA augments the frozen quantized model with Low-Rank Adapters.", source_type: "paper", tier: 1 }] },
+
+  { from: "lora", to: "fft", relation: "BREAKS", tier: 2, confidence: 0.85,
+    fix: "Adapter-method and full fine-tune are mutually exclusive within one run.",
+    evidence: [{ url: "https://huggingface.co/docs/peft", quote: "PEFT methods freeze the base; choose either full fine-tuning or a PEFT method per run.", source_type: "official_docs", tier: 2 }] },
+
+  // --- optimizer ↔ quantization --------------------------------------------
+  { from: "muon", to: "adamw_8bit", relation: "BREAKS", tier: 2, confidence: 0.8,
+    fix: "Muon owns the optimizer step for hidden weights; 8-bit AdamW state is incompatible with the Newton–Schulz update.",
+    evidence: [{ url: "https://kellerjordan.github.io/posts/muon/", quote: "Muon replaces the optimizer update for 2D weights; use AdamW for the rest, not its 8-bit variant.", source_type: "blog", tier: 2 }] },
+
+  { from: "muon", to: "adamw", relation: "REQUIRES", tier: 2, confidence: 0.9,
+    fix: "Muon only updates 2D hidden weights — embeddings + biases still need AdamW.",
+    evidence: [{ url: "https://kellerjordan.github.io/posts/muon/", quote: "non-hidden parameters (embeddings, scalars) are handled by a standard AdamW.", source_type: "blog", tier: 2 }] },
+
+  { from: "lion", to: "bnb_8bit", relation: "DEGRADES", tier: 3, confidence: 0.5,
+    fix: "Lion sign-update interacts poorly with 8-bit state quant — drop to 16-bit moments.",
+    evidence: [{ url: "https://github.com/bitsandbytes-foundation/bitsandbytes/issues", quote: "single user report: Lion+8-bit moments diverged at step 4k on a 7B base.", source_type: "issue", tier: 3 }] },
+
+  // --- unsloth / quant family ----------------------------------------------
+  { from: "unsloth", to: "bnb_4bit", relation: "REQUIRES", tier: 1, confidence: 1.0,
+    fix: "Unsloth's fused kernels assume a bnb 4-bit base.",
+    evidence: [{ url: "https://github.com/unslothai/unsloth", quote: "Unsloth supports 4-bit quantized models via bitsandbytes for QLoRA fine-tuning.", source_type: "official_docs", tier: 1 }] },
+
+  { from: "unsloth", to: "lora", relation: "REQUIRES", tier: 1, confidence: 1.0,
+    fix: "Unsloth's fast path is the LoRA / QLoRA path.",
+    evidence: [{ url: "https://github.com/unslothai/unsloth", quote: "Unsloth accelerates LoRA and QLoRA fine-tuning with custom Triton kernels.", source_type: "official_docs", tier: 1 }] },
+
+  { from: "unsloth", to: "fsdp", relation: "BREAKS", tier: 2, confidence: 0.8,
+    fix: "Unsloth's custom kernels don't compose with FSDP sharding hooks today.",
+    evidence: [{ url: "https://github.com/unslothai/unsloth/issues", quote: "FSDP is not currently supported alongside Unsloth's fused kernels.", source_type: "issue", tier: 2 }] },
+
+  // --- inference quants (category errors) ----------------------------------
+  { from: "awq", to: "fft", relation: "BREAKS", tier: 2, confidence: 0.85,
+    fix: "AWQ is an inference-time weight quant. You can't fine-tune through it.",
+    evidence: [{ url: "https://github.com/casper-hansen/AutoAWQ", quote: "AWQ is intended for post-training quantization for inference.", source_type: "official_docs", tier: 2 }] },
+
+  { from: "gptq", to: "fft", relation: "BREAKS", tier: 2, confidence: 0.85,
+    fix: "GPTQ is post-training quant — frozen base only.",
+    evidence: [{ url: "https://arxiv.org/abs/2210.17323", quote: "GPTQ is a one-shot post-training quantization method.", source_type: "paper", tier: 2 }] },
+
+  // --- distributed -----------------------------------------------------------
+  { from: "fsdp", to: "bnb_4bit", relation: "CONDITIONAL", tier: 2, confidence: 0.8, conditions: { plugin: "bnb-fsdp" },
+    fix: "Works only with the bnb-FSDP plugin; vanilla FSDP shards over uninitialized 4-bit weights.",
+    evidence: [{ url: "https://huggingface.co/docs/accelerate", quote: "FSDP + bitsandbytes 4-bit requires the bnb-fsdp wrap policy.", source_type: "official_docs", tier: 2 }] },
+
+  { from: "deepspeed_z3", to: "bnb_8bit", relation: "DEGRADES", tier: 3, confidence: 0.5,
+    fix: "Reports of slowdown / hangs on multi-node Z3 + 8-bit. Use bf16 weights, 8-bit optimizer states only.",
+    evidence: [{ url: "https://github.com/microsoft/DeepSpeed/issues", quote: "Z3 + 8-bit weights hang on the param-gather step in some configs.", source_type: "issue", tier: 3 }] },
+
+  // --- scheduler benchmark relations ---------------------------------------
+  { from: "dlrs", to: "distilbert", relation: "COMPATIBLE", tier: 1, confidence: 1.0,
+    fix: "DLRS #1 on the SST-2 bench: val_loss 0.2653, val_acc 0.890, steps_to_target 266.7 (n=3 seeds).",
+    evidence: [{ url: "https://huggingface.co/spaces/juiceb0xc0de/lr-scheduler-benchmark", quote: "DLRS leads on val_loss across 3 seeds on distilbert/sst2.", source_type: "benchmark", tier: 1 }] },
+
+  { from: "onecycle", to: "distilbert", relation: "DEGRADES", tier: 1, confidence: 1.0,
+    fix: "OneCycle underperforms on the SST-2 bench: val_loss 0.4284 vs cohort cutoff 0.4022.",
+    evidence: [{ url: "https://huggingface.co/spaces/juiceb0xc0de/lr-scheduler-benchmark", quote: "OneCycle val_loss 0.4284 is above the cohort cutoff 0.4022.", source_type: "benchmark", tier: 1 }] },
+
+  // --- compatible/positive edges (just so the graph isn't all conflict) ----
+  { from: "lora", to: "bnb_8bit",  relation: "COMPATIBLE", tier: 2, confidence: 0.8, fix: "", evidence: [] },
+  { from: "lora", to: "bnb_4bit",  relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "grad_ckpt", to: "fsdp", relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "grad_ckpt", to: "qlora",relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "cosine", to: "adamw",   relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "dlrs", to: "adamw",     relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "fsdp", to: "llama3",    relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "qlora", to: "llama3",   relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "qlora", to: "mistral",  relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "qlora", to: "qwen2",    relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "lora",  to: "distilbert", relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "vllm",  to: "llama3",   relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "vllm",  to: "mistral",  relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "deepspeed_z3", to: "fft", relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "fsdp", to: "fft",       relation: "COMPATIBLE", tier: 1, confidence: 1.0, fix: "", evidence: [] },
+  { from: "muon", to: "llama3",    relation: "COMPATIBLE", tier: 2, confidence: 0.8, fix: "", evidence: [] },
+];
+
+// add "staged melt-in" as a hidden technique reachable as a fix-target
+window.FORGE_NODES.push({
+  canonical: "staged_meltin", name: "Staged Melt-In", type: "technique",
+  description: "Linear ramp-in of chaos injectors over N steps. Prevents NaN at layer ~6.",
+  tier: 1,
+});
+
+// ============================================================================
+// RESOLVE ENGINE
+// ============================================================================
+// For each non-selected node N, look at edges between N and any selected S:
+//   BREAKS              → blocked (red)
+//   REQUIRES(S → N)     → S needs N; mark N "needed by S" (amber/conditional)
+//   REQUIRES(N → S)     → N needs S, S is selected → that requirement is satisfied (ignore)
+//   CONDITIONAL         → conditional (amber) with conditions
+//   DEGRADES            → available + warning
+//   COMPATIBLE          → available
+// Plus: if N has any REQUIRES(N → X) where X is *not* selected and X is also not
+//   universally optional, N is conditional ("needs X").
+
+window.forgeResolve = function (selectedCanons) {
+  const sel = new Set(selectedCanons);
+  const out = {};
+  const nodeByCanon = Object.fromEntries(window.FORGE_NODES.map(n => [n.canonical, n]));
+  const incoming = {};
+  const outgoing = {};
+  for (const e of window.FORGE_EDGES) {
+    (outgoing[e.from] = outgoing[e.from] || []).push(e);
+    (incoming[e.to]   = incoming[e.to]   || []).push(e);
+  }
+
+  for (const n of window.FORGE_NODES) {
+    if (sel.has(n.canonical)) {
+      out[n.canonical] = { status: "selected", reasons: [], warnings: [] };
+      continue;
+    }
+    const reasons = [];
+    const warnings = [];
+
+    // edges adjacent to n
+    const adj = [...(outgoing[n.canonical] || []), ...(incoming[n.canonical] || [])];
+
+    for (const e of adj) {
+      const otherCanon = e.from === n.canonical ? e.to : e.from;
+      const direction  = e.from === n.canonical ? "out" : "in"; // n -> other or other -> n
+      const other = nodeByCanon[otherCanon];
+      if (!other) continue;
+
+      if (sel.has(otherCanon)) {
+        if (e.relation === "BREAKS") {
+          reasons.push({
+            kind: "blocked",
+            label: `breaks with ${other.name}`,
+            fix: e.fix,
+            evidence: e.evidence,
+            tier: e.tier,
+            confidence: e.confidence,
+            otherCanon,
+          });
+        } else if (e.relation === "CONDITIONAL") {
+          reasons.push({
+            kind: "conditional",
+            label: `conditional on ${other.name}`,
+            fix: e.fix,
+            conditions: e.conditions,
+            evidence: e.evidence,
+            tier: e.tier,
+            otherCanon,
+          });
+        } else if (e.relation === "REQUIRES" && direction === "in") {
+          // other -> n  means "other requires n". other is selected, n is not.
+          // n is a missing ingredient.
+          reasons.push({
+            kind: "needed-by",
+            label: `needed by ${other.name}`,
+            fix: e.fix,
+            evidence: e.evidence,
+            tier: e.tier,
+            otherCanon,
+          });
+        } else if (e.relation === "DEGRADES") {
+          warnings.push({
+            label: `degrades with ${other.name}`,
+            fix: e.fix,
+            evidence: e.evidence,
+            tier: e.tier,
+            otherCanon,
+          });
+        }
+      }
+    }
+
+    let status = "available";
+    if (reasons.some(r => r.kind === "blocked"))       status = "blocked";
+    else if (reasons.some(r => r.kind === "conditional" || r.kind === "needed-by")) status = "conditional";
+
+    out[n.canonical] = { status, reasons, warnings };
+  }
+
+  return out;
+};
+
+// recipe payload
+window.forgeRecipe = function (selectedCanons) {
+  const sel = new Set(selectedCanons);
+  const nodeByCanon = Object.fromEntries(window.FORGE_NODES.map(n => [n.canonical, n]));
+  const conflicts = [];
+  const unmet = [];
+  const warnings = [];
+
+  for (const e of window.FORGE_EDGES) {
+    const a = sel.has(e.from), b = sel.has(e.to);
+    if (a && b) {
+      if (e.relation === "BREAKS") {
+        conflicts.push({ a: nodeByCanon[e.from].name, b: nodeByCanon[e.to].name, fix: e.fix, tier: e.tier, evidence: e.evidence });
+      }
+      if (e.relation === "DEGRADES") {
+        warnings.push({ a: nodeByCanon[e.from].name, b: nodeByCanon[e.to].name, fix: e.fix, tier: e.tier, evidence: e.evidence });
+      }
+    } else if (a && !b && e.relation === "REQUIRES") {
+      unmet.push({ from: nodeByCanon[e.from].name, missing: nodeByCanon[e.to].name, missingCanon: e.to, fix: e.fix, tier: e.tier, evidence: e.evidence });
+    } else if (!a && b && e.relation === "REQUIRES") {
+      // selected b but not a; the requires goes from a→b meaning a needs b. a not selected, so not unmet here.
+    }
+  }
+
+  // scheduler benchmark cohort (mock real bench data)
+  const scheduler_picks = [
+    { component: "DLRS",      val_loss: 0.26528, val_acc: 0.89029, steps_to_target: 266.7, n_seeds: 3,  source: "https://huggingface.co/spaces/juiceb0xc0de/lr-scheduler-benchmark", canonical: "dlrs" },
+    { component: "Cosine",    val_loss: 0.31417, val_acc: 0.87959, steps_to_target: 312.0, n_seeds: 3,  source: "https://huggingface.co/spaces/juiceb0xc0de/lr-scheduler-benchmark", canonical: "cosine" },
+    { component: "WSD",       val_loss: 0.34081, val_acc: 0.86790, steps_to_target: 348.3, n_seeds: 3,  source: "https://huggingface.co/spaces/juiceb0xc0de/lr-scheduler-benchmark", canonical: "wsd" },
+  ];
+  const scheduler_warnings = [
+    { component: "OneCycle",  val_loss: 0.42844, cutoff: 0.4022, canonical: "onecycle" },
+  ];
+
+  const valid = conflicts.length === 0 && unmet.length === 0;
+
+  return { selected: selectedCanons, valid, conflicts, unmet, warnings, scheduler_picks, scheduler_warnings };
+};
+
+// ============================================================================
+// LIVE DISCOVERIES FEED (mock SSE)
+// ============================================================================
+window.FORGE_DISCOVERIES = [
+  { a: "Gradient Checkpointing", relation: "COMPATIBLE", b: "LoRA",          tier: 2, source: "huggingface.co/docs/peft",    ts_offset: -8 },
+  { a: "Muon",                   relation: "REQUIRES",   b: "AdamW",         tier: 2, source: "kellerjordan.github.io",       ts_offset: -22 },
+  { a: "DeepSpeed ZeRO-3",       relation: "DEGRADES",   b: "bnb 8-bit",     tier: 3, source: "github.com/microsoft/DeepSpeed", ts_offset: -41 },
+  { a: "QLoRA",                  relation: "COMPATIBLE", b: "Qwen-2.5",      tier: 2, source: "qwenlm.github.io",             ts_offset: -67 },
+  { a: "FSDP",                   relation: "CONDITIONAL",b: "bnb 4-bit",     tier: 2, source: "huggingface.co/docs/accelerate", ts_offset: -94 },
+  { a: "Sophia-G",               relation: "DEGRADES",   b: "bnb 8-bit",     tier: 3, source: "github.com/Liuhong99/Sophia",  ts_offset: -128 },
+  { a: "WSD",                    relation: "COMPATIBLE", b: "Continual PT",  tier: 2, source: "arxiv.org/abs/2404.06395",     ts_offset: -171 },
+  { a: "Unsloth",                relation: "BREAKS",     b: "FSDP",          tier: 2, source: "github.com/unslothai/unsloth", ts_offset: -210 },
+  { a: "AWQ",                    relation: "BREAKS",     b: "Full Fine-Tune",tier: 2, source: "github.com/casper-hansen/AutoAWQ", ts_offset: -266 },
+  { a: "OneCycle",               relation: "DEGRADES",   b: "distilbert/sst2", tier: 1, source: "hf.co/spaces/juiceb0xc0de/lr-scheduler-benchmark", ts_offset: -311 },
+];
+
+// new live discoveries that stream in over time (offsets in seconds from "now")
+window.FORGE_FUTURE_DISCOVERIES = [
+  { a: "Per-Layer LR Rotation", relation: "BREAKS",     b: "AdamW 8-bit", tier: 1, source: "mempalace://rick-notes" },
+  { a: "Jacobian Reg",          relation: "BREAKS",     b: "Chaos Injectors", tier: 1, source: "mempalace://rick-notes" },
+  { a: "Lion",                  relation: "DEGRADES",   b: "bnb 8-bit",   tier: 3, source: "github.com/bitsandbytes-foundation/bitsandbytes" },
+  { a: "Paged AdamW",           relation: "COMPATIBLE", b: "QLoRA",       tier: 2, source: "huggingface.co/docs/transformers" },
+  { a: "DLRS",                  relation: "COMPATIBLE", b: "WSD",         tier: 2, source: "hf.co/spaces/juiceb0xc0de/lr-scheduler-benchmark" },
+  { a: "Cosine",                relation: "COMPATIBLE", b: "AdamW",       tier: 1, source: "pytorch.org/docs" },
+  { a: "FlashAttention-3",      relation: "COMPATIBLE", b: "Llama-3",     tier: 2, source: "github.com/Dao-AILab/flash-attention" },
+  { a: "Liger Kernel",          relation: "COMPATIBLE", b: "Unsloth",     tier: 3, source: "github.com/linkedin/Liger-Kernel" },
+];
+
+// ============================================================================
+// LIVE API BOOTSTRAP — prefer the live Forge API; fall back to the bundled mock.
+// Default base is same-origin (the API serves this frontend in prod).
+// Split-port dev: ?api=http://localhost:8010
+// ============================================================================
+window.FORGE_API = (function () {
+  const m = location.search.match(/[?&]api=([^&]+)/);
+  return m ? decodeURIComponent(m[1]) : "";
+})();
+window.FORGE_LIVE = false;
+window.forgeBootstrap = async function () {
+  const base = window.FORGE_API.replace(/\/$/, "");
+  try {
+    const g = await (await fetch(base + "/graph", { cache: "no-store" })).json();
+    if (g && Array.isArray(g.nodes) && g.nodes.length && Array.isArray(g.edges)) {
+      const tierByNode = {};
+      for (const e of g.edges) {
+        for (const c of [e.from_canon, e.to_canon]) {
+          tierByNode[c] = Math.min(tierByNode[c] == null ? 9 : tierByNode[c], e.tier || 2);
+        }
+      }
+      window.FORGE_NODES = g.nodes.map(n => ({
+        canonical: n.canonical, name: n.name, type: n.type,
+        description: n.description || "", tier: tierByNode[n.canonical] || 2,
+      }));
+      window.FORGE_EDGES = g.edges.map(e => ({
+        from: e.from_canon, to: e.to_canon, relation: e.relation, tier: e.tier,
+        confidence: e.confidence, fix: e.fix || "", conditions: e.conditions || {},
+        evidence: e.evidence || [],
+      }));
+      window.FORGE_LIVE = true;
+    }
+    const feed = await (await fetch(base + "/feed?n=12", { cache: "no-store" })).json();
+    if (Array.isArray(feed) && feed.length) {
+      window.FORGE_DISCOVERIES = feed.map(f => ({
+        a: f.a, relation: f.relation, b: f.b, tier: f.tier, source: "bright data", ts_offset: 0,
+      }));
+    }
+  } catch (err) {
+    console.warn("[forge] live API unavailable, using bundled mock:", err.message);
+  }
+  return window.FORGE_LIVE;
+};

frontend/graph.jsx

@@ -0,0 +1,447 @@
+// Force-directed graph — the centerpiece.
+// Uses d3-force (loaded from CDN in index.html) for the simulation. SVG render
+// for the visual layer so state transitions are CSS-driven.
+
+const { useEffect, useRef, useState, useMemo, useCallback } = React;
+
+window.ForgeGraph = function ForgeGraph({
+  nodes,
+  edges,
+  resolved,
+  selected,
+  hoveredCanon,
+  onToggleSelect,
+  onHoverNode,
+  onHoverEdge,
+}) {
+  const svgRef = useRef(null);
+  const containerRef = useRef(null);
+  const simRef = useRef(null);
+  const [size, setSize] = useState({ w: 1000, h: 700 });
+  const [transform, setTransform] = useState({ x: 0, y: 0, k: 1 });
+  const transformRef = useRef(transform);
+  transformRef.current = transform;
+
+  // resize observer
+  useEffect(() => {
+    if (!containerRef.current) return;
+    const ro = new ResizeObserver(([e]) => {
+      const r = e.contentRect;
+      setSize({ w: Math.max(400, r.width), h: Math.max(400, r.height) });
+    });
+    ro.observe(containerRef.current);
+    return () => ro.disconnect();
+  }, []);
+
+  // Build simulation. Pin nodes by canonical so they keep identity across re-renders.
+  const simNodesRef = useRef(new Map());
+
+  useEffect(() => {
+    // (re)initialise simulation when node list size changes
+    const w = size.w, h = size.h;
+    const simNodes = nodes.map(n => {
+      const existing = simNodesRef.current.get(n.canonical);
+      if (existing) {
+        existing.node = n;
+        return existing;
+      }
+      const fresh = {
+        canonical: n.canonical,
+        node: n,
+        x: w / 2 + (Math.random() - 0.5) * 200,
+        y: h / 2 + (Math.random() - 0.5) * 200,
+        vx: 0, vy: 0,
+      };
+      simNodesRef.current.set(n.canonical, fresh);
+      return fresh;
+    });
+
+    const simEdges = edges.map(e => ({
+      source: e.from,
+      target: e.to,
+      relation: e.relation,
+    }));
+
+    const sim = d3.forceSimulation(simNodes)
+      .force("link", d3.forceLink(simEdges)
+        .id(d => d.canonical)
+        .distance(l => {
+          // Tight cluster for compatible/requires, push apart for breaks
+          if (l.relation === "BREAKS") return 230;
+          if (l.relation === "REQUIRES") return 140;
+          if (l.relation === "CONDITIONAL") return 160;
+          if (l.relation === "DEGRADES") return 200;
+          return 170;
+        })
+        .strength(l => {
+          if (l.relation === "REQUIRES") return 0.6;
+          if (l.relation === "BREAKS") return 0.15;
+          return 0.25;
+        })
+      )
+      .force("charge", d3.forceManyBody().strength(-580).distanceMax(450))
+      .force("center", d3.forceCenter(w / 2, h / 2).strength(0.04))
+      .force("collide", d3.forceCollide().radius(54).strength(0.9))
+      // Group similar types together vertically
+      .force("typeY", d3.forceY(d => typeYTarget(d.node.type, h)).strength(0.06))
+      .alpha(1)
+      .alphaDecay(0.025);
+
+    simRef.current = sim;
+
+    const renderTick = () => {
+      // direct DOM update for perf
+      const svg = svgRef.current;
+      if (!svg) return;
+      for (const n of simNodes) {
+        const el = svg.querySelector(`g.node[data-canon="${cssEscape(n.canonical)}"]`);
+        if (el) el.setAttribute("transform", `translate(${n.x.toFixed(2)},${n.y.toFixed(2)})`);
+      }
+      for (let i = 0; i < simEdges.length; i++) {
+        const e = simEdges[i];
+        const path = svg.querySelector(`g.edge[data-id="${i}"] path.edge-path`);
+        if (path && e.source.x != null) {
+          const x1 = e.source.x, y1 = e.source.y;
+          const x2 = e.target.x, y2 = e.target.y;
+          const dx = x2 - x1, dy = y2 - y1;
+          const len = Math.sqrt(dx*dx + dy*dy) || 1;
+          // perpendicular unit vector × offset amount (slight molten droop)
+          const nx = -dy / len, ny = dx / len;
+          const sag = Math.min(40, len * 0.18) * ((i % 2) ? 1 : -1) * (e.relation === "BREAKS" ? 0.6 : 1);
+          const cx = (x1 + x2) / 2 + nx * sag;
+          const cy = (y1 + y2) / 2 + ny * sag;
+          const d = `M ${x1.toFixed(1)} ${y1.toFixed(1)} Q ${cx.toFixed(1)} ${cy.toFixed(1)} ${x2.toFixed(1)} ${y2.toFixed(1)}`;
+          path.setAttribute("d", d);
+          const glow = svg.querySelector(`g.edge[data-id="${i}"] path.edge-glow`);
+          if (glow) glow.setAttribute("d", d);
+        }
+      }
+    };
+    sim.on("tick", renderTick);
+
+    // Pre-tick a chunk so the layout settles before the first paint,
+    // and so we have a fallback layout even if d3.timer doesn't fire
+    // in this preview iframe.
+    for (let i = 0; i < 80; i++) sim.tick();
+    renderTick();
+
+    // Belt-and-braces: drive ticks via a manual rAF loop in case d3.timer
+    // is paused (some preview iframes throttle d3-timer).
+    let rafHandle;
+    const loop = () => {
+      if (sim.alpha() > sim.alphaMin()) {
+        sim.tick();
+        renderTick();
+      }
+      rafHandle = requestAnimationFrame(loop);
+    };
+    rafHandle = requestAnimationFrame(loop);
+
+    return () => { sim.stop(); cancelAnimationFrame(rafHandle); };
+  }, [nodes.length, edges.length, size.w, size.h]);
+
+  // Kick the simulation when selection changes so layout adapts to highlighted edges.
+  useEffect(() => {
+    if (simRef.current) {
+      simRef.current.alpha(0.35).restart();
+    }
+  }, [selected.length]);
+
+  // Pan & zoom (basic)
+  useEffect(() => {
+    const svg = svgRef.current;
+    if (!svg) return;
+    let dragging = false;
+    let last = null;
+    const onDown = (ev) => {
+      // Only pan when target is not a node card
+      if (ev.target.closest("g.node")) return;
+      dragging = true;
+      last = { x: ev.clientX, y: ev.clientY };
+      svg.style.cursor = "grabbing";
+    };
+    const onMove = (ev) => {
+      if (!dragging) return;
+      const dx = ev.clientX - last.x;
+      const dy = ev.clientY - last.y;
+      last = { x: ev.clientX, y: ev.clientY };
+      setTransform(t => ({ ...t, x: t.x + dx, y: t.y + dy }));
+    };
+    const onUp = () => { dragging = false; svg.style.cursor = "grab"; };
+    const onWheel = (ev) => {
+      ev.preventDefault();
+      const dir = ev.deltaY < 0 ? 1.1 : 1 / 1.1;
+      setTransform(t => {
+        const k = Math.max(0.4, Math.min(2.2, t.k * dir));
+        // zoom centered on cursor
+        const rect = svg.getBoundingClientRect();
+        const cx = ev.clientX - rect.left;
+        const cy = ev.clientY - rect.top;
+        const dx = (cx - t.x) * (1 - dir);
+        const dy = (cy - t.y) * (1 - dir);
+        return { x: t.x + dx, y: t.y + dy, k };
+      });
+    };
+    svg.addEventListener("mousedown", onDown);
+    window.addEventListener("mousemove", onMove);
+    window.addEventListener("mouseup", onUp);
+    svg.addEventListener("wheel", onWheel, { passive: false });
+    return () => {
+      svg.removeEventListener("mousedown", onDown);
+      window.removeEventListener("mousemove", onMove);
+      window.removeEventListener("mouseup", onUp);
+      svg.removeEventListener("wheel", onWheel);
+    };
+  }, []);
+
+  const resetView = () => setTransform({ x: 0, y: 0, k: 1 });
+  const zoom = (dir) => setTransform(t => ({ ...t, k: Math.max(0.4, Math.min(2.2, t.k * dir)) }));
+
+  const selectedSet = useMemo(() => new Set(selected), [selected]);
+
+  // map edges to their indices so the simulation can find them
+  const edgeData = useMemo(() => edges.map((e, i) => ({ ...e, _i: i })), [edges]);
+
+  // Which edges are "hot" — incident to a selected node
+  const hotEdge = (e) => selectedSet.has(e.from) || selectedSet.has(e.to);
+
+  // For "needs-by" rendering: which nodes are amber because some selected node requires them?
+  const neededBy = useMemo(() => {
+    const m = {};
+    for (const e of edges) {
+      if (e.relation === "REQUIRES" && selectedSet.has(e.from) && !selectedSet.has(e.to)) {
+        (m[e.to] = m[e.to] || []).push(e.from);
+      }
+    }
+    return m;
+  }, [edges, selectedSet]);
+
+  // Helpers
+  function classFor(canon) {
+    const r = resolved[canon];
+    if (!r) return "s-available";
+    return "s-" + r.status;
+  }
+
+  return (
+    <div className="stage" ref={containerRef}>
+      <svg
+        ref={svgRef}
+        className="graph"
+        width={size.w} height={size.h}
+        viewBox={`0 0 ${size.w} ${size.h}`}
+        preserveAspectRatio="xMidYMid meet"
+      >
+        <defs>
+          {/* Molten plate gradient — the "just-forged" red-hot interior */}
+          <radialGradient id="grad-molten-plate" cx="50%" cy="55%" r="65%">
+            <stop offset="0%"  stopColor="#5a1f0a" />
+            <stop offset="35%" stopColor="#3a1408" />
+            <stop offset="70%" stopColor="#1a0807" />
+            <stop offset="100%" stopColor="#0a0303" />
+          </radialGradient>
+          {/* Forge ember glow filter (used on selected plates) */}
+          <filter id="node-ember-glow" x="-50%" y="-50%" width="200%" height="200%">
+            <feGaussianBlur stdDeviation="2.6" result="blur" />
+            <feFlood floodColor="#ff6a1f" floodOpacity="0.55" />
+            <feComposite in2="blur" operator="in" />
+            <feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge>
+          </filter>
+          {/* Painterly noise overlay for plate backgrounds */}
+          <filter id="plate-grain" x="0" y="0" width="100%" height="100%">
+            <feTurbulence type="fractalNoise" baseFrequency="0.9" numOctaves="2" seed="3" />
+            <feColorMatrix values="0 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 0.15 0" />
+            <feComposite in2="SourceGraphic" operator="in" />
+          </filter>
+          {/* Arrow for REQUIRES edges */}
+          <marker id="arrow-requires" viewBox="0 0 10 10" refX="9" refY="5"
+                  markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+            <path d="M0 0 L10 5 L0 10 z" fill="rgba(212,164,68,0.7)" />
+          </marker>
+          {/* Tier-rarity coin gradients — T1 legendary, T2 rare, T3 common */}
+          <radialGradient id="brass-t1" cx="40%" cy="35%" r="75%">
+            <stop offset="0%"  stopColor="#ffd09a" />
+            <stop offset="45%" stopColor="#ff8a3d" />
+            <stop offset="100%" stopColor="#6a2a08" />
+          </radialGradient>
+          <radialGradient id="brass-t2" cx="40%" cy="35%" r="75%">
+            <stop offset="0%"  stopColor="#b8d4f0" />
+            <stop offset="45%" stopColor="#5b9bd8" />
+            <stop offset="100%" stopColor="#1c3a5a" />
+          </radialGradient>
+          <radialGradient id="brass-t3" cx="40%" cy="35%" r="75%">
+            <stop offset="0%"  stopColor="#cac4b6" />
+            <stop offset="45%" stopColor="#9a9285" />
+            <stop offset="100%" stopColor="#3a3528" />
+          </radialGradient>
+        </defs>
+
+        <g transform={`translate(${transform.x},${transform.y}) scale(${transform.k})`}>
+          {/* Edges */}
+          <g className="edges">
+            {edgeData.map((e, i) => {
+              const hot = hotEdge(e);
+              const anySelected = selectedSet.size > 0;
+              const faded = anySelected && !hot && e.relation !== "BREAKS";
+              const relCls = e.relation.toLowerCase();
+              return (
+                <g key={i}
+                   className={`edge ${relCls} ${hot ? "hot" : ""} ${faded ? "faded" : ""}`}
+                   data-id={i}
+                   onMouseEnter={ev => onHoverEdge && onHoverEdge(e, ev)}
+                   onMouseLeave={() => onHoverEdge && onHoverEdge(null)}
+                >
+                  {/* glow overlay drawn first (under) for hot edges */}
+                  <path className="edge-glow" />
+                  <path className="edge-path"
+                        markerEnd={e.relation === "REQUIRES" ? "url(#arrow-requires)" : undefined} />
+                </g>
+              );
+            })}
+          </g>
+
+          {/* Nodes — ornate brass-framed runestone plaques */}
+          <g className="nodes">
+            {nodes.map(n => {
+              const meta = window.TYPE_META[n.type] || window.TYPE_META.technique;
+              const status = (resolved[n.canonical] || {}).status || "available";
+              const needs = neededBy[n.canonical] || [];
+              const isSel = selectedSet.has(n.canonical);
+              const cls = isSel ? "s-selected" : ("s-" + status);
+
+              // Octagon vertices (flat-top, 64×64). Computed once below.
+              const OCT_OUTER = "-13.3,-32 13.3,-32 32,-13.3 32,13.3 13.3,32 -13.3,32 -32,13.3 -32,-13.3";
+              const OCT_BRASS = "-11.2,-27 11.2,-27 27,-11.2 27,11.2 11.2,27 -11.2,27 -27,11.2 -27,-11.2";
+              const OCT_HILT  = "-9.5,-23 9.5,-23 23,-9.5 23,9.5 9.5,23 -9.5,23 -23,9.5 -23,-9.5";
+              // Four corner stud positions (on the diagonal short edges)
+              const STUDS = [[-22.6,-22.6], [22.6,-22.6], [22.6,22.6], [-22.6,22.6]];
+              const tierGrad = `url(#brass-t${n.tier})`;
+
+              const needsLabel = needs.length > 0 ? `needs ${truncate(displayName(needs[0]), 14)}` : "";
+              const chipW = Math.max(70, needsLabel.length * 5 + 16);
+
+              return (
+                <g
+                  key={n.canonical}
+                  className={`node ${cls}`}
+                  data-canon={n.canonical}
+                  style={{ ["--type-color"]: meta.color }}
+                  onClick={() => onToggleSelect(n.canonical)}
+                  onMouseEnter={ev => onHoverNode(n, ev)}
+                  onMouseLeave={() => onHoverNode(null)}
+                >
+                  {/* outer pulse halo (only visible per state) */}
+                  <polygon className="node-aura" points={OCT_OUTER}
+                           transform="scale(1.25)" />
+
+                  {/* outer black/iron bezel */}
+                  <polygon className="node-frame-outer" points={OCT_OUTER} />
+
+                  {/* the stone plate (interior) */}
+                  <polygon className="node-plate" points={OCT_BRASS} />
+
+                  {/* type-colored gem glow behind icon */}
+                  <ellipse className="node-gem" cx="0" cy="-2" rx="14" ry="11" />
+
+                  {/* brass frame ring */}
+                  <polygon className="node-frame" points={OCT_BRASS} />
+                  <polygon className="node-frame-inner" points={OCT_HILT} />
+
+                  {/* brass corner studs */}
+                  {STUDS.map(([sx,sy], si) => (
+                    <circle key={si} className="node-stud" cx={sx} cy={sy} r="1.8" />
+                  ))}
+
+                  {/* icon — type glyph */}
+                  <g className="node-icon" transform="translate(-12,-14) scale(1.0)"
+                     dangerouslySetInnerHTML={{ __html: meta.icon }} />
+
+                  {/* name ribbon below the plate */}
+                  <path className="node-ribbon"
+                        d="M -33 33 L -38 47 L -28 44 L -22 48 L -16 44 L -10 48 L -4 44 L 2 48 L 8 44 L 14 48 L 20 44 L 26 48 L 34 47 L 33 33 Z" />
+                  <text className="node-name" y="44.5">{truncate(n.name, 14)}</text>
+
+                  {/* tier wax-seal medallion top-right */}
+                  <g className="node-seal" transform="translate(22,-22)">
+                    <circle className="node-seal-disc" r="8.5" fill={tierGrad} />
+                    <circle r="6.5" fill="none" stroke="rgba(0,0,0,0.4)" strokeWidth="0.5" />
+                    <text y="2.5">T{n.tier}</text>
+                  </g>
+
+                  {/* lock graphic for blocked state — over the icon, ominous */}
+                  <g className="node-lock" transform="translate(0,-2)">
+                    <path className="lock-shackle" d="M -5 -2 v -4 a 5 5 0 0 1 10 0 v 4" />
+                    <rect className="lock-body" x="-7" y="-2" width="14" height="11" rx="1.5" />
+                    <circle className="lock-keyhole" cx="0" cy="2" r="1.4" />
+                    <rect className="lock-keyhole" x="-0.5" y="2" width="1" height="3.5" />
+                  </g>
+
+                  {/* "needs X" pinned scroll-tag for conditional */}
+                  {(status === "conditional" && needs.length > 0) && (
+                    <g className="needs-chip" transform="translate(0,60)">
+                      <rect x={-chipW/2} y="-7" width={chipW} height="14" rx="2" />
+                      <circle className="chip-pin" cx={-chipW/2} cy="0" r="1.5" />
+                      <circle className="chip-pin" cx={chipW/2}  cy="0" r="1.5" />
+                      <text y="2.5">{needsLabel}</text>
+                    </g>
+                  )}
+                </g>
+              );
+            })}
+          </g>
+        </g>
+      </svg>
+
+      {/* corner controls */}
+      <div className="stage-controls">
+        <button className="ctrl" onClick={() => zoom(1.15)} title="Zoom in">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.3-4.3M8 11h6M11 8v6"/></svg>
+        </button>
+        <button className="ctrl" onClick={() => zoom(1/1.15)} title="Zoom out">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.3-4.3M8 11h6"/></svg>
+        </button>
+        <button className="ctrl" onClick={resetView} title="Reset view">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><path d="M3 12a9 9 0 1 0 3-6.7L3 8M3 3v5h5"/></svg>
+        </button>
+      </div>
+
+      <div className="stage-toolbar">
+        <span className="pill"><span className="dot" style={{ background: "var(--ember-1)", boxShadow: "0 0 6px var(--ember-1)"}}/>The Forge</span>
+        <span className="pill" title="API base URL">
+          api · localhost:8010
+        </span>
+      </div>
+
+      {selectedSet.size === 0 && (
+        <div className="stage-hint">
+          <div className="ring" />
+          <h3>Lay an ingredient on the anvil</h3>
+          <p>Pick a component from the inventory.<br/>Incompatible nodes will grey out with citations.</p>
+        </div>
+      )}
+
+      <div className="anvil-watermark">forge · 2026</div>
+    </div>
+  );
+};
+
+// helpers
+function typeYTarget(type, h) {
+  const order = ["architecture", "technique", "optimizer", "scheduler", "quantization", "inference"];
+  const i = order.indexOf(type);
+  if (i === -1) return h / 2;
+  // distribute around vertical center with mild attraction
+  const span = h * 0.55;
+  return (h / 2) + (i - (order.length - 1) / 2) * (span / order.length);
+}
+
+function cssEscape(s) {
+  if (window.CSS && window.CSS.escape) return window.CSS.escape(s);
+  return String(s).replace(/[^a-zA-Z0-9_-]/g, "\\$&");
+}
+
+function displayName(canon) {
+  const n = (window.FORGE_NODES || []).find(x => x.canonical === canon);
+  return n ? n.name : canon;
+}
+function truncate(s, n) { return s && s.length > n ? s.slice(0, n - 1) + "…" : s; }

frontend/icons.js

@@ -0,0 +1,53 @@
+// Icons for component types — hand-drawn SVG paths that read as D&D iconography
+// at small sizes (24x24 viewBox). Used both in the inventory rail and graph nodes.
+
+window.TYPE_META = {
+  optimizer: {
+    label: "Optimizer",
+    color: "var(--t-optimizer)",
+    glow:  "var(--t-optimizer-glow)",
+    // a forge gear — toothed wheel
+    icon: `<g><circle cx="12" cy="12" r="3.2"/><path d="M12 3v3M12 18v3M3 12h3M18 12h3M5.6 5.6l2.1 2.1M16.3 16.3l2.1 2.1M5.6 18.4l2.1-2.1M16.3 7.7l2.1-2.1"/></g>`,
+  },
+  scheduler: {
+    label: "Scheduler",
+    color: "var(--t-scheduler)",
+    glow:  "var(--t-scheduler-glow)",
+    // an hourglass/clock
+    icon: `<g><circle cx="12" cy="12" r="8"/><path d="M12 7v5l3 2"/></g>`,
+  },
+  technique: {
+    label: "Technique",
+    color: "var(--t-technique)",
+    glow:  "var(--t-technique-glow)",
+    // arcane sigil — diamond inside triangle
+    icon: `<g><path d="M12 3l9 16H3z"/><path d="M12 9l4 7H8z"/></g>`,
+  },
+  quantization: {
+    label: "Quantization",
+    color: "var(--t-quantization)",
+    glow:  "var(--t-quantization-glow)",
+    // stacked bars compressed
+    icon: `<g><rect x="4"  y="13" width="3" height="7" rx="0.5"/><rect x="10.5" y="9"  width="3" height="11" rx="0.5"/><rect x="17" y="5"  width="3" height="15" rx="0.5"/></g>`,
+  },
+  architecture: {
+    label: "Architecture",
+    color: "var(--t-architecture)",
+    glow:  "var(--t-architecture-glow)",
+    // temple pillars / colonnade
+    icon: `<g><path d="M3 7l9-4 9 4"/><path d="M5 7v12M19 7v12M12 7v12"/><path d="M3 21h18"/></g>`,
+  },
+  inference: {
+    label: "Inference",
+    color: "var(--t-inference)",
+    glow:  "var(--t-inference-glow)",
+    // arrow with spark
+    icon: `<g><path d="M4 12h13"/><path d="M13 6l6 6-6 6"/></g>`,
+  },
+};
+
+// helper: render the inline icon path inside an SVG <g> with stroke set by callers.
+window.renderTypeIcon = function (type, props) {
+  const meta = window.TYPE_META[type] || window.TYPE_META.technique;
+  return { html: meta.icon };
+};

frontend/index.html

@@ -0,0 +1,45 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Forge — ML training compatibility graph</title>
+
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Cinzel:wght@400;500;600;700&family=Cormorant+Garamond:ital,wght@0,400;0,500;0,600;1,400;1,500&family=Geist:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+
+<link rel="stylesheet" href="styles.css">
+
+<!-- React + Babel (pinned) -->
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+
+<!-- d3 (force simulation) -->
+<script src="https://unpkg.com/d3@7.9.0/dist/d3.min.js"></script>
+
+</head>
+<body>
+<div id="root"></div>
+
+<!-- Mock data + resolver (matches FastAPI /resolve, /recipe shapes) -->
+<script src="data.js"></script>
+<!-- Type icons / metadata -->
+<script src="icons.js"></script>
+<!-- Forge sounds (Web Audio, no assets) -->
+<script src="sound.js"></script>
+
+<!-- Tweaks shell (host protocol + form controls) -->
+<script type="text/babel" src="tweaks-panel.jsx"></script>
+
+<!-- App pieces -->
+<script type="text/babel" src="graph.jsx"></script>
+<script type="text/babel" src="inventory.jsx"></script>
+<script type="text/babel" src="recipe.jsx"></script>
+<script type="text/babel" src="ticker.jsx"></script>
+<script type="text/babel" src="tooltip.jsx"></script>
+<script type="text/babel" src="app.jsx"></script>
+
+</body>
+</html>

frontend/inventory.jsx

@@ -0,0 +1,139 @@
+// Left rail — the "inventory". Filterable component palette.
+
+window.Inventory = function Inventory({
+  nodes,
+  resolved,
+  selected,
+  onToggleSelect,
+  onHoverNode,
+}) {
+  const [filter, setFilter] = React.useState("all");
+  const [q, setQ] = React.useState("");
+  const selectedSet = React.useMemo(() => new Set(selected), [selected]);
+
+  // Group nodes by type, ordered.
+  const typeOrder = ["optimizer", "scheduler", "technique", "quantization", "architecture", "inference"];
+  const counts = React.useMemo(() => {
+    const c = { all: nodes.length };
+    for (const t of typeOrder) c[t] = 0;
+    for (const n of nodes) c[n.type] = (c[n.type] || 0) + 1;
+    return c;
+  }, [nodes]);
+
+  const filtered = React.useMemo(() => {
+    const lq = q.trim().toLowerCase();
+    return nodes.filter(n => {
+      if (filter !== "all" && n.type !== filter) return false;
+      if (lq && !(n.name.toLowerCase().includes(lq) || n.canonical.includes(lq))) return false;
+      return true;
+    });
+  }, [nodes, filter, q]);
+
+  const grouped = React.useMemo(() => {
+    const g = {};
+    for (const n of filtered) (g[n.type] = g[n.type] || []).push(n);
+    return g;
+  }, [filtered]);
+
+  return (
+    <div className="rail-left">
+      <div className="rail-head">
+        <h2>Inventory</h2>
+        <div className="sub">{nodes.length} components</div>
+      </div>
+
+      <div className="filters">
+        <button className={"chip " + (filter === "all" ? "on" : "")}
+                onClick={() => setFilter("all")}>
+          All <span className="ct">{counts.all}</span>
+        </button>
+        {typeOrder.map(t => (
+          counts[t] > 0 && (
+            <button key={t}
+                    className={"chip " + (filter === t ? "on" : "")}
+                    onClick={() => setFilter(t)}>
+              {window.TYPE_META[t].label}
+              <span className="ct">{counts[t]}</span>
+            </button>
+          )
+        ))}
+      </div>
+
+      <div className="search">
+        <input
+          type="text"
+          placeholder="search components…"
+          value={q}
+          onChange={e => setQ(e.target.value)}
+        />
+      </div>
+
+      <div className="inv-list">
+        {typeOrder.map(t => {
+          const list = grouped[t];
+          if (!list || list.length === 0) return null;
+          return (
+            <div key={t} style={{ marginBottom: 6 }}>
+              <div className="inv-group-title">
+                {window.TYPE_META[t].label}
+              </div>
+              {list.map(n => {
+                const r = resolved[n.canonical] || {};
+                const isSelected = selectedSet.has(n.canonical);
+                const cls = [
+                  "inv-row",
+                  `tier-${n.tier}`,
+                  isSelected ? "selected" : "",
+                  r.status === "blocked" ? "blocked" : "",
+                  r.status === "conditional" ? "dim" : "",
+                ].filter(Boolean).join(" ");
+                const meta = window.TYPE_META[n.type];
+                const metaText =
+                  isSelected ? "equipped"
+                  : r.status === "blocked" ? `blocked · ${r.reasons[0]?.label || "breaks"}`
+                  : r.status === "conditional" ? (r.reasons[0]?.label || "awaiting")
+                  : null;
+                return (
+                  <div
+                    key={n.canonical}
+                    className={cls}
+                    style={{ ["--type-color"]: meta.color }}
+                    onClick={() => onToggleSelect(n.canonical)}
+                    onMouseEnter={e => onHoverNode(n, e)}
+                    onMouseLeave={() => onHoverNode(null)}
+                  >
+                    <div className="type-ic">
+                      <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8"
+                           strokeLinecap="round" strokeLinejoin="round"
+                           dangerouslySetInnerHTML={{ __html: meta.icon }} />
+                    </div>
+                    <div>
+                      <div className="inv-name">{n.name}</div>
+                      <div className="inv-meta">
+                        {metaText ? (
+                          <span style={{
+                            color: isSelected ? "var(--ember-2)"
+                                  : r.status === "blocked" ? "var(--rust)"
+                                  : "var(--amber)"
+                          }}>{metaText}</span>
+                        ) : (
+                          <span className="canon">{n.canonical}</span>
+                        )}
+                      </div>
+                    </div>
+                    <div className={`tier-pip t${n.tier}`} title={`Tier ${n.tier}`}>T{n.tier}</div>
+                  </div>
+                );
+              })}
+            </div>
+          );
+        })}
+        {filtered.length === 0 && (
+          <div style={{ padding: "32px 16px", textAlign: "center", color: "var(--bone-4)", fontSize: 11, fontFamily: "var(--f-mono)" }}>
+            no components match
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};

frontend/recipe.jsx

@@ -0,0 +1,238 @@
+// Right rail — the Recipe Card.
+
+window.RecipeCard = function RecipeCard({
+  selected,
+  nodes,
+  recipe,
+  onRemove,
+  onSelect,
+  onHoverNode,
+}) {
+  const byCanon = React.useMemo(() => Object.fromEntries(nodes.map(n => [n.canonical, n])), [nodes]);
+  const empty = selected.length === 0;
+  const conflicts = recipe.conflicts || [];
+  const unmet     = recipe.unmet || [];
+  const warnings  = recipe.warnings || [];
+
+  let statusCls = "empty", statusText = "no build";
+  if (!empty) {
+    if (conflicts.length > 0) { statusCls = "broken"; statusText = "conflicts"; }
+    else if (unmet.length > 0) { statusCls = "warn";  statusText = "incomplete"; }
+    else { statusCls = "valid"; statusText = "valid"; }
+  }
+
+  return (
+    <div className="rail-right">
+      <div className="rail-head">
+        <div>
+          <h2>Recipe</h2>
+          <div className="sub">your build</div>
+        </div>
+        <div className={`recipe-status ${statusCls}`}>{statusText}</div>
+      </div>
+
+      <div className="recipe-body">
+        {/* Build chips */}
+        <div className="section">
+          <h3>Selected <span className="ct">{selected.length}</span></h3>
+          {empty ? (
+            <div className="empty-state" style={{ padding: "20px 6px 12px" }}>
+              <div className="glyph">
+                <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+                  <path d="M12 3l9 5v8l-9 5-9-5V8z"/>
+                  <path d="M3 8l9 5 9-5M12 13v9"/>
+                </svg>
+              </div>
+              <div className="ttl">Empty anvil</div>
+              <div className="sub">pick from inventory</div>
+            </div>
+          ) : (
+            <div className="build-chips">
+              {selected.map(c => {
+                const n = byCanon[c];
+                if (!n) return null;
+                const meta = window.TYPE_META[n.type];
+                return (
+                  <div
+                    key={c}
+                    className="build-chip"
+                    onMouseEnter={e => onHoverNode(n, e)}
+                    onMouseLeave={() => onHoverNode(null)}
+                    onClick={() => onRemove(c)}
+                  >
+                    <span className="dot" style={{ background: meta.color }} />
+                    {n.name}
+                    <span className="x">×</span>
+                  </div>
+                );
+              })}
+            </div>
+          )}
+        </div>
+
+        {/* Conflicts */}
+        {conflicts.length > 0 && (
+          <div className="section">
+            <h3>Conflicts <span className="ct">{conflicts.length}</span></h3>
+            {conflicts.map((c, i) => (
+              <div key={i} className="entry conflict">
+                <div className="title conflict">
+                  <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                    <path d="M12 9v4M12 17h.01"/>
+                    <path d="M10.3 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/>
+                  </svg>
+                  {c.a} <span style={{ color: "var(--bone-4)" }}>↔</span> {c.b}
+                </div>
+                <div className="fix">{c.fix}</div>
+                <div className="meta">
+                  <span className={`tier-badge t${c.tier}`}>T{c.tier}</span>
+                  {c.evidence && c.evidence[0] && (
+                    <a href={c.evidence[0].url} target="_blank" rel="noopener">
+                      {prettySource(c.evidence[0].url)}
+                    </a>
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+
+        {/* Unmet requirements */}
+        {unmet.length > 0 && (
+          <div className="section">
+            <h3>Unmet requirements <span className="ct">{unmet.length}</span></h3>
+            {unmet.map((u, i) => (
+              <div key={i} className="entry unmet">
+                <div className="title unmet">
+                  <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                    <circle cx="12" cy="12" r="9"/>
+                    <path d="M12 8v4M12 16h.01"/>
+                  </svg>
+                  {u.from} needs <strong style={{ color: "var(--bone-1)" }}>{u.missing}</strong>
+                </div>
+                <div className="fix">{u.fix}</div>
+                <div className="meta">
+                  <span className={`tier-badge t${u.tier}`}>T{u.tier}</span>
+                  {u.evidence && u.evidence[0] && (
+                    <a href={u.evidence[0].url} target="_blank" rel="noopener">
+                      {prettySource(u.evidence[0].url)}
+                    </a>
+                  )}
+                </div>
+                <button className="add-btn" onClick={() => onSelect(u.missingCanon)}>
+                  <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5"><path d="M12 5v14M5 12h14"/></svg>
+                  add {u.missing}
+                </button>
+              </div>
+            ))}
+          </div>
+        )}
+
+        {/* Soft warnings */}
+        {warnings.length > 0 && (
+          <div className="section">
+            <h3>Warnings <span className="ct">{warnings.length}</span></h3>
+            {warnings.map((w, i) => (
+              <div key={i} className="entry warning">
+                <div className="title warning">{w.a} ↔ {w.b}</div>
+                <div className="fix">{w.fix}</div>
+              </div>
+            ))}
+          </div>
+        )}
+
+        {/* Scheduler bench */}
+        {!empty && (
+          <div className="section">
+            <h3>Scheduler picks
+              <span style={{ marginLeft: 6, fontFamily: "var(--f-mono)", fontSize: 8.5, color: "var(--bone-4)", letterSpacing: "0.16em" }}>
+                · distilbert/sst2 · n=3 seeds
+              </span>
+            </h3>
+            <div className="bench-table">
+              <div className="br head">
+                <div>component</div>
+                <div className="val">val_loss</div>
+                <div className="val">val_acc</div>
+              </div>
+              {(recipe.scheduler_picks || []).map((s, i) => (
+                <div key={s.canonical} className={"br " + (i === 0 ? "best" : "")}
+                     onMouseEnter={e => onHoverNode(byCanon[s.canonical], e)}
+                     onMouseLeave={() => onHoverNode(null)}
+                     onClick={() => onSelect(s.canonical)}
+                     style={{ cursor: "pointer" }}
+                >
+                  <div>{s.component}</div>
+                  <div className="val">{s.val_loss.toFixed(4)}</div>
+                  <div className="val">{(s.val_acc * 100).toFixed(2)}%</div>
+                </div>
+              ))}
+              {(recipe.scheduler_warnings || []).map((s, i) => (
+                <div key={s.canonical} className="br warn"
+                     onMouseEnter={e => onHoverNode(byCanon[s.canonical], e)}
+                     onMouseLeave={() => onHoverNode(null)}
+                >
+                  <div>{s.component} <span style={{ color: "var(--rust)", fontSize: 9, marginLeft: 4 }}>(above cohort cutoff)</span></div>
+                  <div className="val">{s.val_loss.toFixed(4)}</div>
+                  <div className="val">—</div>
+                </div>
+              ))}
+            </div>
+            <div style={{ marginTop: 8, fontFamily: "var(--f-mono)", fontSize: 9, color: "var(--bone-4)", letterSpacing: "0.12em" }}>
+              ★ leader · benchmark from hf.co/spaces/juiceb0xc0de/lr-scheduler-benchmark
+            </div>
+          </div>
+        )}
+
+        {/* Config snippet */}
+        {!empty && conflicts.length === 0 && unmet.length === 0 && (
+          <div className="section" style={{ borderBottom: "none" }}>
+            <h3>Config snippet</h3>
+            <pre style={{
+              margin: 0,
+              fontFamily: "var(--f-mono)",
+              fontSize: 11,
+              lineHeight: 1.6,
+              color: "var(--bone-2)",
+              background: "var(--coal-0)",
+              border: "1px solid var(--coal-5)",
+              borderRadius: 4,
+              padding: "10px 12px",
+              overflowX: "auto",
+              whiteSpace: "pre",
+            }}>{configSnippet(selected, byCanon)}</pre>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+function prettySource(url) {
+  if (!url) return "";
+  if (url.startsWith("mempalace://")) return "mempalace · rick";
+  try {
+    const u = new URL(url);
+    return u.hostname.replace(/^www\./, "") + (u.pathname.length > 1 ? u.pathname.split("/").slice(0,2).join("/") : "");
+  } catch {
+    return url;
+  }
+}
+
+function configSnippet(selected, byCanon) {
+  const lines = ["# forge.recipe.yaml"];
+  const byType = {};
+  for (const c of selected) {
+    const n = byCanon[c]; if (!n) continue;
+    (byType[n.type] = byType[n.type] || []).push(n);
+  }
+  const order = ["architecture", "technique", "optimizer", "scheduler", "quantization", "inference"];
+  for (const t of order) {
+    if (!byType[t]) continue;
+    lines.push(`${t}:`);
+    for (const n of byType[t]) {
+      lines.push(`  - ${n.canonical}  # ${n.name}`);
+    }
+  }
+  return lines.join("\n");
+}

frontend/sound.js

@@ -0,0 +1,131 @@
+// Forge sound — synthesised metallic clangs, sizzles, and bell chimes.
+// No assets, no preload — just short Web Audio bursts on demand.
+
+(function () {
+  let ctx = null;
+  let muted = false;
+
+  function ensure() {
+    if (!ctx) {
+      try { ctx = new (window.AudioContext || window.webkitAudioContext)(); } catch { return null; }
+    }
+    if (ctx.state === "suspended") ctx.resume().catch(() => {});
+    return ctx;
+  }
+
+  // Damped sinusoid hit — "metal strike" feel
+  function envelope(node, attack, decay, sustain, release, peak = 1.0) {
+    const t0 = ctx.currentTime;
+    node.gain.cancelScheduledValues(t0);
+    node.gain.setValueAtTime(0, t0);
+    node.gain.linearRampToValueAtTime(peak, t0 + attack);
+    node.gain.exponentialRampToValueAtTime(Math.max(0.001, sustain), t0 + attack + decay);
+    node.gain.exponentialRampToValueAtTime(0.001, t0 + attack + decay + release);
+  }
+
+  // ── CLANG (on add) — two stacked sines with metallic inharmonic ratios
+  function clang() {
+    if (!ensure() || muted) return;
+    const out = ctx.createGain();
+    out.gain.value = 0.18;
+    out.connect(ctx.destination);
+
+    const partials = [
+      { f: 320, mul: 1.0,  d: 0.6 },
+      { f: 740, mul: 0.55, d: 0.45 },
+      { f: 1240, mul: 0.30, d: 0.35 },
+      { f: 1980, mul: 0.18, d: 0.22 },
+    ];
+    for (const p of partials) {
+      const o = ctx.createOscillator();
+      const g = ctx.createGain();
+      o.type = "sine";
+      o.frequency.value = p.f * (0.99 + Math.random() * 0.02);
+      o.connect(g).connect(out);
+      envelope(g, 0.003, 0.03, p.mul * 0.18, p.d, p.mul);
+      const t0 = ctx.currentTime;
+      o.start(t0);
+      o.stop(t0 + 0.7);
+    }
+    // bright transient (noise burst, very short)
+    const buf = ctx.createBuffer(1, ctx.sampleRate * 0.06, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < data.length; i++) data[i] = (Math.random() * 2 - 1) * Math.pow(1 - i/data.length, 2);
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    const hp = ctx.createBiquadFilter();
+    hp.type = "highpass";
+    hp.frequency.value = 1800;
+    const tg = ctx.createGain();
+    tg.gain.value = 0.35;
+    src.connect(hp).connect(tg).connect(out);
+    src.start();
+  }
+
+  // ── THUD (on remove) — low boom, no metallic ring
+  function thud() {
+    if (!ensure() || muted) return;
+    const o = ctx.createOscillator();
+    const g = ctx.createGain();
+    o.type = "sine";
+    const t0 = ctx.currentTime;
+    o.frequency.setValueAtTime(140, t0);
+    o.frequency.exponentialRampToValueAtTime(50, t0 + 0.25);
+    g.gain.setValueAtTime(0, t0);
+    g.gain.linearRampToValueAtTime(0.18, t0 + 0.005);
+    g.gain.exponentialRampToValueAtTime(0.001, t0 + 0.28);
+    o.connect(g).connect(ctx.destination);
+    o.start(t0); o.stop(t0 + 0.32);
+  }
+
+  // ── SIZZLE (on blocked attempt) — filtered noise hiss
+  function sizzle() {
+    if (!ensure() || muted) return;
+    const dur = 0.32;
+    const buf = ctx.createBuffer(1, ctx.sampleRate * dur, ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < data.length; i++) {
+      const env = Math.pow(1 - i/data.length, 1.4);
+      data[i] = (Math.random() * 2 - 1) * env;
+    }
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    const bp = ctx.createBiquadFilter();
+    bp.type = "bandpass";
+    bp.frequency.value = 1800;
+    bp.Q.value = 1.4;
+    const g = ctx.createGain();
+    g.gain.value = 0.20;
+    src.connect(bp).connect(g).connect(ctx.destination);
+    const t0 = ctx.currentTime;
+    src.start(t0);
+    bp.frequency.setValueAtTime(1800, t0);
+    bp.frequency.exponentialRampToValueAtTime(600, t0 + dur);
+  }
+
+  // ── CHIME (on something positive resolving) — soft bell
+  function chime() {
+    if (!ensure() || muted) return;
+    const out = ctx.createGain();
+    out.gain.value = 0.12;
+    out.connect(ctx.destination);
+    const partials = [880, 1320, 1760];
+    for (let i = 0; i < partials.length; i++) {
+      const o = ctx.createOscillator();
+      const g = ctx.createGain();
+      o.type = "triangle";
+      o.frequency.value = partials[i];
+      o.connect(g).connect(out);
+      envelope(g, 0.005, 0.04, 0.08, 0.6 - i*0.1, 0.55 - i*0.15);
+      const t0 = ctx.currentTime;
+      o.start(t0);
+      o.stop(t0 + 0.7);
+    }
+  }
+
+  window.forgeSound = {
+    clang, thud, sizzle, chime,
+    setMuted(v) { muted = !!v; },
+    isMuted() { return muted; },
+  };
+})();

frontend/styles.css

@@ -0,0 +1,1407 @@
+/* ============================================================================
+   FORGE — Compatibility Graph for ML Training Components
+   Aesthetic: dark coal + ember glow + tactile cards. D&D character sheet
+   meets a modern dev tool. Smoothness is the point.
+   ============================================================================ */
+
+:root {
+  /* Coal & steel base */
+  --coal-0: #07090c;        /* pitch — under everything */
+  --coal-1: #0b0e13;        /* canvas */
+  --coal-2: #11151c;        /* rail / panel */
+  --coal-3: #161b25;        /* card body */
+  --coal-4: #1d2330;        /* card hover */
+  --coal-5: #262d3d;        /* divider */
+  --steel-1: #2a3346;       /* border on cards */
+  --steel-2: #3a455c;       /* border bright */
+  --steel-3: #5a6580;       /* dim icon */
+
+  /* Forge palette */
+  --ember-1: #ff6a1f;       /* hot iron */
+  --ember-2: #ff8a3d;       /* sparks */
+  --ember-3: #ffba5e;       /* slag */
+  --ember-glow: rgba(255, 106, 31, 0.45);
+  /* Rarity / tier palette (Diablo-style loot)
+     T1 = legendary orange · T2 = rare blue · T3 = common grey */
+  --brass-1: #ff8a3d;       /* tier 1 — legendary ember */
+  --brass-2: #5b9bd8;       /* tier 2 — rare cobalt   */
+  --brass-3: #9a9285;       /* tier 3 — common bone   */
+  --tier1-glow: rgba(255, 138, 61, 0.55);
+  --tier2-glow: rgba(91, 155, 216, 0.55);
+  --tier3-glow: rgba(154, 146, 133, 0.40);
+  --rust:    #c8403c;       /* blocked / breaks */
+  --rust-2:  #8a2520;
+  --amber:   #e0a13c;       /* conditional */
+  --amber-2: #b07a1f;
+  --bone-1:  #efeae0;       /* text bright */
+  --bone-2:  #cfc8b8;
+  --bone-3:  #8c8676;       /* dim */
+  --bone-4:  #5e5a4f;       /* very dim */
+
+  /* Type palette (component categories) */
+  --t-optimizer:    #d4a444;  /* brass */
+  --t-scheduler:    #5fb3d4;  /* sky steel */
+  --t-technique:    #a78bfa;  /* arcane violet */
+  --t-quantization: #ff6a1f;  /* hot iron */
+  --t-architecture: #6ec7a0;  /* patina */
+  --t-inference:    #e16d8e;  /* magenta steel */
+
+  /* Type glow (same hue, low alpha) */
+  --t-optimizer-glow:    rgba(212, 164, 68,   0.55);
+  --t-scheduler-glow:    rgba(95, 179, 212,   0.55);
+  --t-technique-glow:    rgba(167, 139, 250,  0.55);
+  --t-quantization-glow: rgba(255, 106, 31,   0.55);
+  --t-architecture-glow: rgba(110, 199, 160,  0.55);
+  --t-inference-glow:    rgba(225, 109, 142,  0.55);
+
+  /* Type families for the available "ready" state — desaturated steel-blue. */
+  --steel-glow: rgba(120, 156, 200, 0.18);
+
+  /* Type */
+  --f-display: "Cinzel", "Cormorant Garamond", Georgia, serif;
+  --f-serif: "Cormorant Garamond", Georgia, serif;
+  --f-ui: "Geist", "Space Grotesk", -apple-system, system-ui, sans-serif;
+  --f-mono: "JetBrains Mono", "IBM Plex Mono", ui-monospace, Menlo, monospace;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+html, body, #root { height: 100%; overflow: hidden; }
+
+body {
+  background: var(--coal-1);
+  color: var(--bone-1);
+  font-family: var(--f-ui);
+  font-size: 13px;
+  line-height: 1.45;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+/* ── Atmosphere: subtle hex grid + corner ember bloom ─────────────────────── */
+body::before {
+  content: "";
+  position: fixed; inset: 0;
+  background-image:
+    /* molten heart at bottom-center of viewport */
+    radial-gradient(circle at 50% 92%, rgba(255, 60, 30, 0.18) 0%, transparent 30%),
+    radial-gradient(circle at 50% 102%, rgba(180, 30, 10, 0.35) 0%, transparent 16%),
+    /* hearth-glow + cold corner */
+    radial-gradient(ellipse at 8% 85%, rgba(255, 106, 31, 0.10), transparent 45%),
+    radial-gradient(ellipse at 92% 10%, rgba(95, 100, 140, 0.06), transparent 55%),
+    /* deep vignette */
+    radial-gradient(ellipse at 50% 50%, transparent 30%, rgba(0,0,0,0.55) 110%);
+  pointer-events: none;
+  z-index: 0;
+}
+body::after {
+  content: "";
+  position: fixed; inset: 0;
+  /* painterly canvas grain — SVG turbulence baked into a data URI */
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='240' height='240'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch' seed='4'/><feColorMatrix values='0 0 0 0 0.55  0 0 0 0 0.35  0 0 0 0 0.15  0 0 0 0.20 0'/></filter><rect width='100%25' height='100%25' filter='url(%23n)'/></svg>");
+  background-size: 220px 220px;
+  opacity: 0.55;
+  mix-blend-mode: overlay;
+  pointer-events: none;
+  z-index: 0;
+}
+
+/* Light sparks falling in the background (cheap CSS) */
+.sparks {
+  position: fixed; inset: 0; pointer-events: none; z-index: 0;
+  overflow: hidden;
+}
+.sparks span {
+  position: absolute;
+  width: 2px; height: 2px; border-radius: 50%;
+  background: var(--ember-2);
+  box-shadow: 0 0 6px var(--ember-1);
+  opacity: 0;
+  animation: spark-fall linear infinite;
+}
+@keyframes spark-fall {
+  0%   { transform: translateY(-10vh); opacity: 0; }
+  15%  { opacity: 0.7; }
+  85%  { opacity: 0.4; }
+  100% { transform: translateY(110vh); opacity: 0; }
+}
+
+/* ── App shell ───────────────────────────────────────────────────────────── */
+#root { position: relative; z-index: 1; }
+
+.app {
+  display: grid;
+  grid-template-rows: 64px 1fr;
+  height: 100vh;
+}
+
+/* ── Top bar ─────────────────────────────────────────────────────────────── */
+.topbar {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+  padding: 0 22px;
+  border-bottom: 1px solid #1a1208;
+  background:
+    url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='200' height='200'><filter id='g'><feTurbulence type='fractalNoise' baseFrequency='0.7' numOctaves='2' stitchTiles='stitch' seed='2'/><feColorMatrix values='0 0 0 0 0.20  0 0 0 0 0.15  0 0 0 0 0.08  0 0 0 0.15 0'/></filter><rect width='100%25' height='100%25' filter='url(%23g)'/></svg>"),
+    linear-gradient(180deg, #1a1208 0%, #0f0a05 50%, #1a1208 100%);
+  background-blend-mode: overlay, normal;
+  position: relative;
+  z-index: 5;
+  box-shadow: 0 1px 0 rgba(212, 164, 68, 0.18), 0 4px 16px rgba(0,0,0,0.6);
+}
+.topbar::before {
+  content: "";
+  position: absolute; left: 0; right: 0; bottom: 0;
+  height: 1px;
+  background: linear-gradient(90deg, transparent 0%, rgba(212, 164, 68, 0.35) 50%, transparent 100%);
+  pointer-events: none;
+}
+.topbar .brand {
+  display: flex; align-items: center; gap: 14px;
+}
+.topbar .brand .mark {
+  width: 36px; height: 36px;
+  display: grid; place-items: center;
+  border-radius: 0;
+  background:
+    radial-gradient(circle at 50% 65%, #4a1c0a 0%, #0f0805 70%);
+  border: 1px solid #5a3010;
+  box-shadow:
+    inset 0 0 14px rgba(255, 106, 31, 0.55),
+    inset 0 -2px 0 rgba(255, 138, 61, 0.4),
+    0 0 12px rgba(255,106,31,0.25);
+  position: relative;
+}
+.topbar .brand .mark svg { display: block; }
+.topbar .brand .name {
+  font-family: var(--f-display);
+  font-size: 26px;
+  font-weight: 600;
+  letter-spacing: 0.16em;
+  color: #f6e4c8;
+  text-shadow:
+    0 0 1px #000,
+    0 1px 0 #000,
+    0 0 10px rgba(255, 138, 61, 0.30);
+}
+.topbar .brand .tag {
+  font-family: var(--f-serif);
+  font-style: italic;
+  font-size: 11px;
+  letter-spacing: 0.04em;
+  color: var(--brass-2);
+  padding-top: 4px;
+}
+
+.topbar .crumbs {
+  display: flex; align-items: center; gap: 12px;
+  margin-left: auto;
+  font-family: var(--f-mono);
+  font-size: 11px;
+  color: var(--bone-3);
+}
+.topbar .crumbs .api-pill {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 4px 8px;
+  border: 1px solid var(--coal-5);
+  border-radius: 4px;
+  background: var(--coal-2);
+}
+.topbar .crumbs .dot {
+  width: 6px; height: 6px; border-radius: 50%;
+  background: var(--t-architecture);
+  box-shadow: 0 0 6px var(--t-architecture);
+  animation: pulse-dot 2s ease-in-out infinite;
+}
+@keyframes pulse-dot { 0%,100% { opacity: 1; } 50% { opacity: 0.5; } }
+
+.topbar .legend {
+  display: flex; align-items: center; gap: 18px;
+  font-family: var(--f-display);
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  color: var(--bone-3);
+}
+.topbar .legend .swatch {
+  display: inline-flex; align-items: center; gap: 7px;
+}
+.topbar .legend .sw {
+  width: 11px; height: 11px; border-radius: 50%;
+  border: 1px solid rgba(0,0,0,0.55);
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.2);
+}
+.topbar .legend .sw.t1 { background: radial-gradient(circle at 35% 30%, #ffd09a, #ff8a3d 50%, #6a2a08); box-shadow: 0 0 8px var(--tier1-glow), inset 0 1px 0 rgba(255,255,255,0.2); }
+.topbar .legend .sw.t2 { background: radial-gradient(circle at 35% 30%, #b8d4f0, #5b9bd8 50%, #1c3a5a); box-shadow: 0 0 6px var(--tier2-glow), inset 0 1px 0 rgba(255,255,255,0.2); }
+.topbar .legend .sw.t3 { background: radial-gradient(circle at 35% 30%, #cac4b6, #9a9285 50%, #3a3528); box-shadow: 0 0 3px var(--tier3-glow), inset 0 1px 0 rgba(255,255,255,0.2); }
+
+/* ── Main grid ───────────────────────────────────────────────────────────── */
+.main {
+  display: grid;
+  grid-template-columns: 280px 1fr 360px;
+  height: 100%;
+  min-height: 0;
+}
+
+/* ── Left rail: inventory ────────────────────────────────────────────────── */
+.rail-left {
+  border-right: 1px solid var(--coal-5);
+  background:
+    /* parchment grain */
+    url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='180' height='180'><filter id='p'><feTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='2' stitchTiles='stitch' seed='7'/><feColorMatrix values='0 0 0 0 0.40  0 0 0 0 0.30  0 0 0 0 0.18  0 0 0 0.12 0'/></filter><rect width='100%25' height='100%25' filter='url(%23p)'/></svg>"),
+    linear-gradient(180deg, var(--coal-2) 0%, var(--coal-1) 100%);
+  background-blend-mode: overlay, normal;
+  display: flex; flex-direction: column;
+  min-height: 0;
+  position: relative;
+}
+.rail-left::before,
+.rail-right::before {
+  /* hammered-iron seam down the inner edge */
+  content: "";
+  position: absolute; top: 0; bottom: 0;
+  width: 1px;
+  background: linear-gradient(180deg, transparent 0%, rgba(212,164,68,0.25) 15%, rgba(212,164,68,0.25) 85%, transparent 100%);
+  pointer-events: none;
+}
+.rail-left::before  { right: 0; }
+.rail-right::before { left: 0; }
+.rail-left .rail-head {
+  padding: 16px 18px 12px;
+  border-bottom: 1px solid var(--coal-5);
+  position: relative;
+}
+.rail-left .rail-head::after,
+.rail-right .rail-head::after {
+  /* filigree ornament under the section header */
+  content: "";
+  position: absolute; left: 18px; right: 18px; bottom: -1px;
+  height: 1px;
+  background:
+    linear-gradient(90deg, transparent 0%, rgba(212,164,68,0.5) 50%, transparent 100%);
+}
+.rail-left .rail-head h2,
+.rail-right .rail-head h2 {
+  font-family: var(--f-display);
+  font-size: 19px;
+  font-weight: 500;
+  margin: 0 0 3px;
+  letter-spacing: 0.10em;
+  text-transform: uppercase;
+  color: var(--bone-1);
+  text-shadow: 0 1px 0 rgba(0,0,0,0.7);
+}
+.rail-left .rail-head .sub {
+  font-family: var(--f-serif);
+  font-style: italic;
+  font-size: 12px;
+  letter-spacing: 0.02em;
+  color: var(--bone-3);
+}
+.rail-left .filters {
+  display: flex; flex-wrap: wrap; gap: 5px;
+  padding: 12px 14px 10px;
+  border-bottom: 1px solid var(--coal-5);
+}
+.rail-left .filters .chip {
+  font-family: var(--f-display);
+  font-size: 10.5px;
+  letter-spacing: 0.10em;
+  text-transform: uppercase;
+  padding: 4px 9px;
+  border-radius: 0;
+  background: var(--coal-1);
+  border: 1px solid var(--coal-5);
+  border-top-color: rgba(255,255,255,0.05);
+  color: var(--bone-3);
+  cursor: pointer;
+  transition: all 140ms ease;
+  font-weight: 500;
+}
+.rail-left .filters .chip:hover { color: var(--bone-1); border-color: var(--brass-3); }
+.rail-left .filters .chip.on {
+  color: var(--coal-0);
+  background: linear-gradient(180deg, var(--brass-1) 0%, #c46822 100%);
+  border-color: var(--brass-1);
+  box-shadow: 0 0 8px rgba(255, 138, 61, 0.4), inset 0 1px 0 rgba(255,255,255,0.2);
+}
+.rail-left .filters .chip .ct {
+  margin-left: 5px;
+  opacity: 0.7;
+  font-family: var(--f-mono);
+  font-size: 9.5px;
+}
+
+.rail-left .search {
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--coal-5);
+}
+.rail-left .search input {
+  width: 100%;
+  background: var(--coal-0);
+  border: 1px solid var(--coal-5);
+  border-top-color: rgba(0,0,0,0.6);
+  border-radius: 0;
+  padding: 7px 12px;
+  color: var(--bone-1);
+  font-family: var(--f-serif);
+  font-style: italic;
+  font-size: 13px;
+  outline: none;
+  box-shadow: inset 0 1px 3px rgba(0,0,0,0.5);
+}
+.rail-left .search input::placeholder { color: var(--bone-4); }
+.rail-left .search input:focus { border-color: var(--brass-1); box-shadow: inset 0 1px 3px rgba(0,0,0,0.5), 0 0 0 1px rgba(255, 138, 61, 0.25); }
+
+/* ── Loot-sidebar item cards ────────────────────────────────────────────── */
+.rail-left .inv-list {
+  flex: 1; min-height: 0;
+  overflow-y: auto;
+  padding: 4px 10px 100px;
+}
+.inv-group-title {
+  font-family: var(--f-display);
+  font-size: 10px;
+  letter-spacing: 0.30em;
+  text-transform: uppercase;
+  color: var(--brass-2);
+  padding: 14px 4px 6px;
+  display: flex; align-items: center; gap: 8px;
+}
+.inv-group-title::before, .inv-group-title::after {
+  content: "";
+  flex: 1; height: 1px;
+  background: linear-gradient(90deg, transparent, rgba(91,155,216,0.35), transparent);
+}
+
+.rail-left .inv-row {
+  display: grid;
+  grid-template-columns: 36px 1fr auto;
+  gap: 10px;
+  align-items: center;
+  padding: 8px 10px;
+  margin-bottom: 5px;
+  border-radius: 0;
+  cursor: pointer;
+  position: relative;
+  background:
+    linear-gradient(180deg, rgba(40,30,18,0.25) 0%, rgba(15,12,8,0.65) 100%);
+  border: 1px solid var(--coal-5);
+  border-left: 2px solid var(--rarity, var(--brass-3));
+  transition: background 160ms ease, border-color 160ms ease, box-shadow 200ms ease, transform 120ms ease;
+}
+/* rarity colors set per row (T1/T2/T3) */
+.rail-left .inv-row.tier-1 { --rarity: var(--brass-1); }
+.rail-left .inv-row.tier-2 { --rarity: var(--brass-2); }
+.rail-left .inv-row.tier-3 { --rarity: var(--brass-3); }
+
+.rail-left .inv-row::before {
+  /* glint along the top edge */
+  content: "";
+  position: absolute; left: 0; right: 0; top: 0; height: 1px;
+  background: linear-gradient(90deg, transparent, var(--rarity), transparent);
+  opacity: 0.35;
+}
+.rail-left .inv-row:hover {
+  background: linear-gradient(180deg, rgba(60,42,22,0.35) 0%, rgba(20,14,10,0.7) 100%);
+  border-color: var(--rarity);
+  box-shadow: inset 0 0 0 1px rgba(255,255,255,0.04), 0 0 14px -2px var(--rarity);
+  transform: translateX(1px);
+}
+.rail-left .inv-row.selected {
+  background:
+    linear-gradient(180deg, rgba(255,106,31,0.18) 0%, rgba(60,18,8,0.55) 100%);
+  border-color: var(--ember-1);
+  border-left-color: var(--ember-1);
+  box-shadow:
+    inset 0 0 0 1px rgba(255,160,80,0.18),
+    0 0 18px -2px var(--ember-glow);
+}
+.rail-left .inv-row.selected::after {
+  content: "❖";
+  position: absolute; left: -8px; top: 50%;
+  transform: translateY(-50%);
+  color: var(--ember-1);
+  font-size: 10px;
+  text-shadow: 0 0 6px var(--ember-1);
+}
+.rail-left .inv-row.dim { opacity: 0.40; filter: grayscale(80%); }
+.rail-left .inv-row.dim:hover { opacity: 0.95; filter: grayscale(20%); }
+.rail-left .inv-row.blocked { opacity: 0.35; filter: grayscale(100%) brightness(0.65); }
+.rail-left .inv-row.blocked .inv-name { color: var(--rust); text-decoration: line-through; text-decoration-color: rgba(200,64,60,0.5); }
+
+/* item icon — ornate brass frame */
+.rail-left .inv-row .type-ic {
+  width: 34px; height: 34px;
+  display: grid; place-items: center;
+  background:
+    radial-gradient(circle at 50% 40%, rgba(255,255,255,0.06) 0%, transparent 60%),
+    var(--coal-0);
+  border: 1px solid var(--rarity, var(--brass-3));
+  position: relative;
+  color: var(--type-color, var(--bone-3));
+  box-shadow: inset 0 0 8px rgba(0,0,0,0.6);
+}
+.rail-left .inv-row .type-ic::before,
+.rail-left .inv-row .type-ic::after {
+  /* brass corner notches */
+  content: "";
+  position: absolute;
+  width: 4px; height: 4px;
+  border: 1px solid var(--rarity, var(--brass-3));
+}
+.rail-left .inv-row .type-ic::before { top: -1px; left: -1px; border-right: none; border-bottom: none; }
+.rail-left .inv-row .type-ic::after  { bottom: -1px; right: -1px; border-left: none; border-top: none; }
+
+.rail-left .inv-row .inv-name {
+  font-family: var(--f-display);
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--bone-1);
+  letter-spacing: 0.02em;
+  line-height: 1.2;
+  margin-bottom: 2px;
+}
+.rail-left .inv-row.tier-1 .inv-name { color: var(--brass-1); }
+.rail-left .inv-row.tier-2 .inv-name { color: var(--brass-2); }
+.rail-left .inv-row.tier-3 .inv-name { color: #c8c0b0; }
+.rail-left .inv-row.selected .inv-name { color: #fff5e8; }
+
+.rail-left .inv-row .inv-meta {
+  font-family: var(--f-serif);
+  font-style: italic;
+  font-size: 11px;
+  letter-spacing: 0.01em;
+  color: var(--bone-4);
+}
+.rail-left .inv-row .inv-meta .canon {
+  font-family: var(--f-mono);
+  font-style: normal;
+  font-size: 9.5px;
+  letter-spacing: 0;
+  opacity: 0.7;
+}
+.rail-left .inv-row .tier-pip {
+  width: 22px; height: 22px;
+  border-radius: 50%;
+  display: grid; place-items: center;
+  font-family: var(--f-display);
+  font-size: 10px;
+  font-weight: 600;
+  color: var(--coal-0);
+  border: 1px solid rgba(0,0,0,0.5);
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.18), 0 1px 2px rgba(0,0,0,0.6);
+  letter-spacing: 0;
+}
+.rail-left .inv-row .tier-pip.t1 { background: radial-gradient(circle at 35% 30%, #ffd09a, #ff8a3d 50%, #6a2a08); }
+.rail-left .inv-row .tier-pip.t2 { background: radial-gradient(circle at 35% 30%, #b8d4f0, #5b9bd8 50%, #1c3a5a); }
+.rail-left .inv-row .tier-pip.t3 { background: radial-gradient(circle at 35% 30%, #cac4b6, #9a9285 50%, #3a3528); }
+
+/* ── Center: graph stage ─────────────────────────────────────────────────── */
+.stage {
+  position: relative;
+  min-height: 0;
+  overflow: hidden;
+  background:
+    radial-gradient(ellipse at 50% 65%, rgba(255, 106, 31, 0.07) 0%, transparent 55%),
+    var(--coal-1);
+}
+.stage svg.graph {
+  position: absolute; inset: 0;
+  width: 100%; height: 100%;
+  cursor: grab;
+  user-select: none;
+}
+.stage svg.graph:active { cursor: grabbing; }
+
+/* anvil-mark watermark at bottom center of stage */
+.stage .anvil-watermark {
+  position: absolute;
+  left: 50%; bottom: 18px;
+  transform: translateX(-50%);
+  font-family: var(--f-mono);
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 0.4em;
+  color: var(--bone-4);
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+/* Empty hint overlay */
+.stage .stage-hint {
+  position: absolute;
+  left: 50%; top: 26%;
+  transform: translateX(-50%);
+  text-align: center;
+  pointer-events: none;
+  z-index: 2;
+  max-width: 380px;
+  background: none;
+  padding: 0;
+  opacity: 0.6;
+}
+.stage .stage-hint .ring {
+  width: 40px; height: 40px;
+  border: 1px dashed rgba(255,255,255,0.10);
+  border-radius: 50%;
+  margin: 0 auto 10px;
+  position: relative;
+  animation: gentle-rotate 40s linear infinite;
+}
+@keyframes gentle-rotate { to { transform: rotate(360deg); } }
+.stage .stage-hint .ring::before, .stage .stage-hint .ring::after {
+  content: ""; position: absolute; inset: 12px;
+  border: 1px dashed rgba(255,255,255,0.05);
+  border-radius: 50%;
+}
+.stage .stage-hint .ring::after { inset: 24px; border-style: dotted; }
+.stage .stage-hint h3 {
+  font-family: var(--f-display);
+  font-size: 17px;
+  font-weight: 400;
+  margin: 0 0 4px;
+  letter-spacing: 0.01em;
+  color: var(--bone-2);
+}
+.stage .stage-hint p {
+  font-family: var(--f-mono);
+  font-size: 11px;
+  letter-spacing: 0.04em;
+  color: var(--bone-3);
+  margin: 0;
+}
+
+/* Stage chrome: controls in the corners */
+.stage .stage-controls {
+  position: absolute; top: 12px; left: 12px;
+  display: flex; flex-direction: column; gap: 6px;
+  z-index: 4;
+}
+.stage .stage-controls .ctrl {
+  width: 32px; height: 32px;
+  display: grid; place-items: center;
+  background: var(--coal-2);
+  border: 1px solid var(--coal-5);
+  border-radius: 4px;
+  color: var(--bone-3);
+  cursor: pointer;
+  transition: all 120ms ease;
+}
+.stage .stage-controls .ctrl:hover {
+  color: var(--bone-1);
+  border-color: var(--steel-2);
+  background: var(--coal-3);
+}
+
+.stage .stage-toolbar {
+  position: absolute; top: 12px; right: 12px;
+  display: flex; gap: 6px;
+  z-index: 4;
+  font-family: var(--f-mono);
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+}
+.stage .stage-toolbar .pill {
+  padding: 5px 10px;
+  background: var(--coal-2);
+  border: 1px solid var(--coal-5);
+  border-radius: 3px;
+  color: var(--bone-3);
+  display: inline-flex; align-items: center; gap: 6px;
+}
+.stage .stage-toolbar .pill .dot {
+  width: 6px; height: 6px; border-radius: 50%;
+}
+
+/* ── Node visuals — arcane brass-framed plaques ──────────────────────────── */
+g.node { cursor: pointer; }
+g.node * { transition: opacity 240ms ease, fill 220ms ease, stroke 220ms ease, filter 240ms ease; }
+
+/* outer halo — only visible on hover/selected/conditional */
+g.node .node-aura {
+  fill: none;
+  stroke: none;
+  pointer-events: none;
+  opacity: 0;
+}
+
+/* the stone plate sitting behind the brass frame */
+g.node .node-plate {
+  fill: var(--coal-2);
+  stroke: rgba(0,0,0,0.5);
+  stroke-width: 1.5;
+}
+
+/* the gem behind the icon — type-colored glow */
+g.node .node-gem {
+  fill: var(--type-color);
+  opacity: 0.18;
+  filter: blur(2px);
+}
+
+/* the ornate brass frame — outer + inner stroke for a beveled look */
+g.node .node-frame-outer { fill: none; stroke: #2a2017; stroke-width: 2.2; }
+g.node .node-frame       { fill: none; stroke: #6b5026; stroke-width: 1.2; }
+g.node .node-frame-inner { fill: none; stroke: rgba(255,200,120,0.18); stroke-width: 0.7; }
+
+/* corner studs — tiny brass rivets */
+g.node .node-stud {
+  fill: #8a6a32;
+  stroke: #2a2017;
+  stroke-width: 0.6;
+}
+
+/* the icon glyph */
+g.node .node-icon {
+  fill: none;
+  stroke-width: 1.6;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  pointer-events: none;
+  stroke: var(--type-color, var(--bone-2));
+}
+
+/* the name on its etched ribbon below */
+g.node .node-ribbon {
+  fill: rgba(11,14,19,0.85);
+  stroke: rgba(107, 80, 38, 0.7);
+  stroke-width: 0.7;
+}
+g.node .node-name {
+  fill: var(--bone-1);
+  font-family: var(--f-display);
+  font-size: 10.5px;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-anchor: middle;
+  pointer-events: none;
+}
+
+/* tier wax-seal medallion top-right */
+g.node .node-seal {
+  pointer-events: none;
+}
+g.node .node-seal-disc {
+  stroke: #1a1208;
+  stroke-width: 1;
+  filter: drop-shadow(0 1px 1px rgba(0,0,0,0.7));
+}
+g.node .node-seal text {
+  font-family: var(--f-display);
+  font-size: 7.5px;
+  font-weight: 700;
+  text-anchor: middle;
+  fill: #1a1208;
+  letter-spacing: 0.04em;
+}
+
+/* ─── STATE: available ─── cool steel, ready to be set on the anvil */
+g.node.s-available .node-plate { fill: var(--coal-2); }
+g.node.s-available .node-icon { opacity: 0.9; }
+g.node.s-available:hover .node-plate { fill: var(--coal-3); }
+g.node.s-available:hover .node-aura {
+  opacity: 0.6;
+  stroke: var(--type-color);
+  stroke-width: 1.2;
+  fill: none;
+}
+g.node.s-available:hover .node-gem { opacity: 0.32; }
+g.node.s-available:hover .node-frame { stroke: #9a7434; }
+
+/* ─── STATE: selected ─── molten, just-forged, red-hot ─────────────────── */
+g.node.s-selected .node-plate {
+  fill: url(#grad-molten-plate);
+  filter: url(#node-ember-glow);
+}
+g.node.s-selected .node-frame       { stroke: #d4a049; stroke-width: 1.5; }
+g.node.s-selected .node-frame-outer { stroke: #3a1a08; }
+g.node.s-selected .node-frame-inner { stroke: rgba(255,200,120,0.45); }
+g.node.s-selected .node-stud { fill: #d4a049; stroke: #3a1a08; }
+g.node.s-selected .node-gem  { fill: var(--ember-1); opacity: 0.55; }
+g.node.s-selected .node-icon { stroke: #fff5e8; opacity: 1; filter: drop-shadow(0 0 3px var(--ember-1)); }
+g.node.s-selected .node-name { fill: #fff5e8; }
+g.node.s-selected .node-ribbon { stroke: #d4a049; fill: rgba(40,15,5,0.92); }
+g.node.s-selected .node-aura {
+  opacity: 1;
+  stroke: var(--ember-1);
+  stroke-width: 1.5;
+  fill: none;
+  animation: pulse-ring 2.6s ease-in-out infinite;
+}
+@keyframes pulse-ring {
+  0%,100% { opacity: 0.85; stroke-width: 1.5; }
+  50%     { opacity: 0.25; stroke-width: 4; }
+}
+
+/* ─── STATE: conditional ─── cold ash, dimmed, dashed amber rim ────────── */
+g.node.s-conditional .node-plate {
+  fill: var(--coal-1);
+  filter: grayscale(85%) brightness(0.7);
+}
+g.node.s-conditional .node-frame { stroke: #3a2f1c; }
+g.node.s-conditional .node-frame-outer { stroke: #1a1208; }
+g.node.s-conditional .node-frame-inner { stroke: rgba(255,200,120,0.05); }
+g.node.s-conditional .node-stud { fill: #3a2f1c; }
+g.node.s-conditional .node-gem { opacity: 0.05; }
+g.node.s-conditional .node-icon { stroke: var(--bone-4); opacity: 0.5; }
+g.node.s-conditional .node-name { fill: var(--bone-4); }
+g.node.s-conditional .node-ribbon { fill: rgba(11,14,19,0.6); stroke: rgba(60,60,60,0.4); }
+g.node.s-conditional .node-aura {
+  opacity: 0.7;
+  stroke: var(--amber);
+  stroke-width: 1;
+  stroke-dasharray: 3 4;
+  fill: none;
+  animation: spin-dashes 22s linear infinite;
+}
+@keyframes spin-dashes { to { stroke-dashoffset: -100; } }
+g.node.s-conditional:hover .node-plate { filter: grayscale(50%) brightness(0.95); }
+g.node.s-conditional:hover .node-icon { opacity: 0.85; }
+g.node.s-conditional:hover .node-name { fill: var(--bone-2); }
+
+/* ─── STATE: blocked ─── rusted, chained ───────────────────────────────── */
+g.node.s-blocked .node-plate {
+  fill: var(--coal-1);
+  filter: grayscale(100%) brightness(0.55);
+}
+g.node.s-blocked .node-frame { stroke: var(--rust-2); }
+g.node.s-blocked .node-frame-outer { stroke: #1a0808; }
+g.node.s-blocked .node-frame-inner { stroke: rgba(200,64,60,0.2); }
+g.node.s-blocked .node-stud { fill: var(--rust-2); }
+g.node.s-blocked .node-gem { opacity: 0; }
+g.node.s-blocked .node-icon { stroke: var(--rust); opacity: 0.45; }
+g.node.s-blocked .node-name { fill: var(--rust); opacity: 0.7; }
+g.node.s-blocked .node-ribbon { fill: rgba(15,5,5,0.85); stroke: rgba(138,37,32,0.5); }
+g.node.s-blocked .node-aura {
+  opacity: 0.85;
+  stroke: var(--rust);
+  stroke-width: 1.2;
+  fill: none;
+}
+g.node.s-blocked:hover .node-plate { filter: grayscale(60%) brightness(0.85); }
+g.node.s-blocked:hover .node-icon { opacity: 0.85; }
+
+/* Lock chain + padlock (drawn in JSX) */
+g.node .node-lock { opacity: 0; }
+g.node.s-blocked .node-lock { opacity: 1; }
+g.node .node-lock .lock-body { fill: var(--rust-2); stroke: var(--bone-3); stroke-width: 0.6; }
+g.node .node-lock .lock-shackle { fill: none; stroke: var(--bone-3); stroke-width: 1.1; stroke-linecap: round; }
+g.node .node-lock .lock-keyhole { fill: var(--coal-0); }
+
+/* "needs X" tag for conditional */
+g.node .needs-chip { opacity: 0; pointer-events: none; }
+g.node.s-conditional .needs-chip { opacity: 1; }
+g.node .needs-chip rect {
+  fill: rgba(40, 26, 8, 0.9);
+  stroke: var(--amber);
+  stroke-width: 0.7;
+}
+g.node .needs-chip .chip-pin {
+  fill: var(--amber);
+}
+g.node .needs-chip text {
+  fill: var(--amber);
+  font-family: var(--f-mono);
+  font-size: 7.5px;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  text-anchor: middle;
+}
+
+/* ── Edges — molten veins / etched-iron chains ──────────────────────────── */
+g.edge path { fill: none; transition: stroke 220ms ease, opacity 220ms ease, stroke-width 220ms ease; }
+g.edge path.edge-glow { display: none; }
+g.edge path.edge-path { stroke-linecap: round; }
+
+/* base relations */
+g.edge.compatible  .edge-path { stroke: rgba(212, 164, 68, 0.20); stroke-width: 1.1; }
+g.edge.requires    .edge-path { stroke: rgba(255, 160, 60, 0.50); stroke-width: 1.4; }
+g.edge.conditional .edge-path { stroke: rgba(224, 161, 60, 0.45); stroke-width: 1.2; stroke-dasharray: 4 5; }
+g.edge.degrades    .edge-path { stroke: rgba(225, 109, 142, 0.40); stroke-width: 1; stroke-dasharray: 1 4; }
+g.edge.breaks .edge-path {
+  stroke: var(--rust);
+  stroke-width: 1.6;
+  opacity: 0.95;
+  filter: drop-shadow(0 0 4px rgba(200,64,60,0.7));
+}
+
+/* hot edges (incident to a selection) — molten ember overlay */
+g.edge.hot path.edge-glow {
+  display: inline;
+  fill: none;
+  stroke-linecap: round;
+}
+g.edge.hot.requires .edge-path {
+  stroke: var(--ember-2);
+  stroke-width: 2.2;
+  stroke-dasharray: 8 6;
+  filter: drop-shadow(0 0 6px var(--ember-glow));
+  animation: edge-march 1.2s linear infinite;
+}
+g.edge.hot.requires .edge-glow {
+  stroke: rgba(255, 138, 61, 0.35);
+  stroke-width: 7;
+  filter: blur(2.2px);
+}
+@keyframes edge-march { to { stroke-dashoffset: -28; } }
+
+g.edge.hot.breaks .edge-path {
+  stroke: var(--rust);
+  stroke-width: 2.4;
+  filter: drop-shadow(0 0 7px rgba(200,64,60,1));
+  animation: edge-pulse-rust 1.6s ease-in-out infinite;
+}
+g.edge.hot.breaks .edge-glow {
+  stroke: rgba(200, 64, 60, 0.45);
+  stroke-width: 9;
+  filter: blur(3px);
+  animation: edge-pulse-rust 1.6s ease-in-out infinite;
+}
+@keyframes edge-pulse-rust {
+  0%,100% { opacity: 0.65; }
+  50%     { opacity: 1; }
+}
+
+g.edge.hot.conditional .edge-path,
+g.edge.hot.compatible  .edge-path {
+  stroke: rgba(255, 191, 90, 0.85);
+  stroke-width: 1.8;
+  filter: drop-shadow(0 0 4px rgba(255, 138, 61, 0.5));
+}
+g.edge.hot.conditional .edge-glow,
+g.edge.hot.compatible  .edge-glow {
+  stroke: rgba(255, 138, 61, 0.30);
+  stroke-width: 5;
+  filter: blur(2px);
+}
+
+/* faded edges */
+g.edge.faded .edge-path { opacity: 0.10; }
+g.edge.faded .edge-glow { display: none; }
+
+/* ── Right rail: recipe card ─────────────────────────────────────────────── */
+.rail-right {
+  border-left: 1px solid var(--coal-5);
+  background:
+    url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='180' height='180'><filter id='p'><feTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='2' stitchTiles='stitch' seed='12'/><feColorMatrix values='0 0 0 0 0.40  0 0 0 0 0.30  0 0 0 0 0.18  0 0 0 0.12 0'/></filter><rect width='100%25' height='100%25' filter='url(%23p)'/></svg>"),
+    linear-gradient(180deg, var(--coal-2) 0%, var(--coal-1) 100%);
+  background-blend-mode: overlay, normal;
+  display: flex; flex-direction: column;
+  min-height: 0;
+  position: relative;
+}
+.rail-right .rail-head {
+  padding: 16px 18px 12px;
+  border-bottom: 1px solid var(--coal-5);
+  display: flex; align-items: flex-end; justify-content: space-between; gap: 8px;
+  position: relative;
+}
+.rail-right .rail-head .sub {
+  font-family: var(--f-serif);
+  font-style: italic;
+  font-size: 12px;
+  letter-spacing: 0.02em;
+  color: var(--bone-3);
+}
+.rail-right .recipe-status {
+  font-family: var(--f-display);
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.22em;
+  padding: 4px 10px;
+  border-radius: 0;
+  font-weight: 500;
+  text-shadow: 0 1px 0 rgba(0,0,0,0.5);
+}
+.recipe-status.valid    { background: rgba(110,199,160,0.10); color: var(--t-architecture); border: 1px solid rgba(110,199,160,0.4); }
+.recipe-status.warn     { background: rgba(224,161,60,0.10);  color: var(--amber);          border: 1px solid rgba(224,161,60,0.4); }
+.recipe-status.broken   { background: rgba(200,64,60,0.12);   color: var(--rust);           border: 1px solid rgba(200,64,60,0.45); }
+.recipe-status.empty    { background: var(--coal-1); color: var(--bone-4); border: 1px solid var(--coal-5); }
+
+.rail-right .recipe-body {
+  flex: 1; min-height: 0;
+  overflow-y: auto;
+}
+
+.section {
+  padding: 16px 18px;
+  border-bottom: 1px solid var(--coal-5);
+  position: relative;
+}
+.section + .section::before {
+  content: "❖";
+  position: absolute; left: 50%; top: -8px;
+  transform: translateX(-50%);
+  font-size: 9px;
+  color: var(--brass-2);
+  background: var(--coal-1);
+  padding: 0 6px;
+  letter-spacing: 0.6em;
+  opacity: 0.7;
+}
+.section h3 {
+  font-family: var(--f-display);
+  font-size: 11px;
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: var(--brass-2);
+  font-weight: 500;
+  margin: 0 0 12px;
+  display: flex; align-items: center; gap: 10px;
+  text-shadow: 0 1px 0 rgba(0,0,0,0.5);
+}
+.section h3::before {
+  content: "";
+  width: 14px; height: 1px;
+  background: linear-gradient(90deg, transparent, var(--brass-2));
+}
+.section h3::after {
+  content: "";
+  flex: 1; height: 1px;
+  background: linear-gradient(90deg, rgba(212,164,68,0.25), transparent);
+}
+.section h3 .ct {
+  display: inline-grid; place-items: center;
+  min-width: 20px; height: 18px;
+  padding: 0 6px;
+  background: var(--coal-0);
+  border: 1px solid var(--brass-3);
+  border-radius: 0;
+  font-family: var(--f-mono);
+  font-size: 9px;
+  color: var(--brass-1);
+  letter-spacing: 0;
+}
+
+/* selected build chips — equipped item slots */
+.build-chips { display: flex; flex-wrap: wrap; gap: 6px; }
+.build-chip {
+  display: inline-flex; align-items: center; gap: 7px;
+  padding: 6px 8px 6px 6px;
+  background:
+    linear-gradient(180deg, rgba(60,30,8,0.4) 0%, rgba(15,8,4,0.7) 100%);
+  border: 1px solid var(--ember-1);
+  border-radius: 0;
+  font-family: var(--f-display);
+  font-size: 12.5px;
+  letter-spacing: 0.02em;
+  color: #fff5e8;
+  cursor: pointer;
+  position: relative;
+  box-shadow:
+    inset 0 0 8px rgba(255, 106, 31, 0.18),
+    0 0 6px var(--ember-glow);
+  transition: transform 120ms ease, box-shadow 200ms ease;
+}
+.build-chip:hover {
+  transform: translateY(-1px);
+  box-shadow: inset 0 0 10px rgba(255,138,61,0.25), 0 0 12px var(--ember-1);
+}
+.build-chip .dot {
+  width: 9px; height: 9px;
+  border-radius: 50%;
+  border: 1px solid rgba(0,0,0,0.4);
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.25);
+}
+.build-chip .x {
+  color: var(--bone-4);
+  margin-left: 3px;
+  font-size: 14px;
+  line-height: 1;
+  font-family: var(--f-mono);
+}
+.build-chip:hover .x { color: var(--rust); }
+
+/* conflict / unmet entries — scribed crafting warnings */
+.entry {
+  position: relative;
+  padding: 10px 12px 11px 14px;
+  border-radius: 0;
+  margin-bottom: 7px;
+  background:
+    linear-gradient(180deg, rgba(40,18,8,0.25) 0%, rgba(15,8,4,0.65) 100%);
+  border: 1px solid rgba(60, 38, 18, 0.7);
+  border-left-width: 2px;
+  font-size: 12px;
+}
+.entry.conflict { border-left-color: var(--rust);  box-shadow: 0 0 10px -2px rgba(200,64,60,0.25); }
+.entry.unmet    { border-left-color: var(--amber); box-shadow: 0 0 10px -2px rgba(224,161,60,0.25); }
+.entry.warning  { border-left-color: var(--t-inference); }
+.entry .title {
+  font-family: var(--f-display);
+  font-size: 13px;
+  font-weight: 500;
+  letter-spacing: 0.01em;
+  margin-bottom: 5px;
+  display: flex; align-items: center; gap: 6px;
+}
+.entry .title.conflict { color: var(--rust); }
+.entry .title.unmet    { color: var(--amber); }
+.entry .title.warning  { color: var(--t-inference); }
+.entry .fix {
+  font-family: var(--f-serif);
+  font-style: italic;
+  font-size: 12.5px;
+  line-height: 1.5;
+  color: var(--bone-2);
+  letter-spacing: 0.005em;
+}
+.entry .meta {
+  margin-top: 7px;
+  display: flex; align-items: center; gap: 8px;
+  font-family: var(--f-mono);
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+  color: var(--bone-4);
+}
+.entry .meta a { color: var(--bone-3); text-decoration: none; border-bottom: 1px dotted var(--bone-4); }
+.entry .meta a:hover { color: var(--ember-2); border-color: var(--ember-2); }
+.entry .add-btn {
+  margin-top: 9px;
+  font-family: var(--f-display);
+  font-size: 11px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  padding: 6px 11px;
+  background: linear-gradient(180deg, rgba(224,161,60,0.18) 0%, rgba(120,80,20,0.18) 100%);
+  color: var(--amber);
+  border: 1px solid var(--amber);
+  border-radius: 0;
+  cursor: pointer;
+  display: inline-flex; align-items: center; gap: 7px;
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.08), 0 0 8px rgba(224,161,60,0.18);
+}
+.entry .add-btn:hover {
+  background: linear-gradient(180deg, rgba(224,161,60,0.30) 0%, rgba(120,80,20,0.30) 100%);
+  color: #fff5e8;
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.14), 0 0 14px var(--ember-glow);
+}
+
+/* scheduler picks table */
+.bench-table {
+  display: grid;
+  grid-template-columns: 1fr auto auto;
+  font-family: var(--f-mono);
+  font-size: 11px;
+  border: 1px solid var(--coal-5);
+  border-radius: 4px;
+  overflow: hidden;
+}
+.bench-table .br {
+  display: contents;
+}
+.bench-table .br > * {
+  padding: 7px 10px;
+  border-bottom: 1px solid var(--coal-5);
+  background: var(--coal-2);
+  color: var(--bone-2);
+}
+.bench-table .br.head > * {
+  background: var(--coal-3);
+  color: var(--bone-4);
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+}
+.bench-table .br:last-child > * { border-bottom: none; }
+.bench-table .br > *:first-child { color: var(--bone-1); }
+.bench-table .br .val {
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+.bench-table .br.best > *:first-child::before {
+  content: "★";
+  color: var(--brass-1);
+  margin-right: 6px;
+}
+.bench-table .br.warn .val { color: var(--rust); }
+
+/* empty state */
+.empty-state {
+  padding: 30px 18px;
+  text-align: center;
+  color: var(--bone-4);
+}
+.empty-state .glyph {
+  width: 64px; height: 64px;
+  margin: 0 auto 12px;
+  display: grid; place-items: center;
+  border-radius: 50%;
+  border: 1px dashed var(--coal-5);
+  color: var(--bone-4);
+}
+.empty-state .ttl {
+  font-family: var(--f-display);
+  font-size: 16px;
+  color: var(--bone-2);
+  margin-bottom: 4px;
+}
+.empty-state .sub {
+  font-family: var(--f-mono);
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+}
+
+/* ── Live Discoveries ticker (bottom-center floating) ────────────────────── */
+.ticker {
+  position: fixed;
+  bottom: 0;
+  left: 50%;
+  transform: translateX(-50%);
+  width: min(600px, calc(100% - 660px));
+  max-width: 600px;
+  z-index: 10;
+  pointer-events: none;
+  padding-bottom: 14px;
+}
+.ticker::before {
+  /* the hearth itself — a glowing mouth at the very bottom */
+  content: "";
+  position: absolute; left: 10%; right: 10%; bottom: 0;
+  height: 14px;
+  background:
+    radial-gradient(ellipse at 50% 100%, rgba(255, 138, 61, 0.7) 0%, rgba(180, 30, 10, 0.5) 35%, transparent 70%);
+  filter: blur(4px);
+  pointer-events: none;
+}
+.ticker .ticker-head {
+  display: flex; align-items: center; gap: 10px;
+  font-family: var(--f-display);
+  font-size: 10.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.28em;
+  color: var(--brass-1);
+  margin-bottom: 8px;
+  padding: 0 6px;
+  text-shadow: 0 0 8px var(--ember-glow);
+}
+.ticker .ticker-head .dot {
+  width: 7px; height: 7px; border-radius: 50%;
+  background: var(--ember-1);
+  box-shadow: 0 0 8px var(--ember-1), 0 0 16px var(--ember-2);
+  animation: pulse-dot 1.4s ease-in-out infinite;
+}
+.ticker .ticker-head .label { color: var(--brass-1); }
+.ticker .ticker-head .src {
+  color: var(--bone-4);
+  font-family: var(--f-serif);
+  font-style: italic;
+  text-transform: none;
+  letter-spacing: 0.02em;
+  font-size: 11px;
+}
+.ticker .ticker-head .feed {
+  margin-left: auto;
+  font-family: var(--f-mono);
+  font-size: 9.5px;
+  letter-spacing: 0.05em;
+  color: var(--bone-3);
+  text-transform: none;
+  text-shadow: none;
+}
+
+.ticker .ticker-list {
+  display: flex; flex-direction: column-reverse;
+  gap: 5px;
+  pointer-events: auto;
+  max-height: 158px;
+  overflow: hidden;
+  mask-image: linear-gradient(to top, black 65%, transparent 100%);
+}
+
+.disc-row {
+  display: grid;
+  grid-template-columns: auto 1fr auto auto;
+  align-items: center;
+  gap: 10px;
+  padding: 7px 11px;
+  background: rgba(15, 12, 9, 0.85);
+  backdrop-filter: blur(6px);
+  border: 1px solid rgba(70, 50, 28, 0.6);
+  border-left-width: 2px;
+  border-radius: 0;
+  font-family: var(--f-mono);
+  font-size: 11px;
+  color: var(--bone-2);
+  animation: ember-rise 700ms cubic-bezier(0.16, 0.92, 0.30, 1.05);
+  position: relative;
+}
+.disc-row::before {
+  content: "";
+  position: absolute; left: -1px; top: -1px; bottom: -1px;
+  width: 1px;
+  background: linear-gradient(180deg, transparent, var(--ember-2), transparent);
+  opacity: 0.7;
+  animation: ember-fade 1800ms ease-out forwards;
+}
+.disc-row.r-breaks      { border-left-color: var(--rust); }
+.disc-row.r-conditional { border-left-color: var(--amber); }
+.disc-row.r-requires    { border-left-color: var(--ember-1); }
+.disc-row.r-degrades    { border-left-color: var(--t-inference); }
+.disc-row.r-compatible  { border-left-color: var(--brass-1); }
+
+@keyframes ember-rise {
+  0%   { opacity: 0; transform: translateY(28px) scale(0.94); filter: brightness(1.6) drop-shadow(0 0 12px var(--ember-1)); }
+  40%  { opacity: 1; filter: brightness(1.3) drop-shadow(0 0 8px var(--ember-1)); }
+  100% { opacity: 1; transform: translateY(0) scale(1); filter: brightness(1) drop-shadow(0 0 0 transparent); }
+}
+@keyframes ember-fade {
+  0%   { opacity: 1; }
+  100% { opacity: 0.3; }
+}
+
+.disc-row .rel {
+  font-family: var(--f-mono);
+  font-size: 9px;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  padding: 2px 5px;
+  border-radius: 2px;
+  background: var(--coal-3);
+}
+.disc-row.r-breaks      .rel { color: var(--rust);  background: rgba(200,64,60,0.10); }
+.disc-row.r-conditional .rel { color: var(--amber); background: rgba(224,161,60,0.10); }
+.disc-row.r-requires    .rel { color: var(--ember-2);background: rgba(255,106,31,0.10); }
+.disc-row.r-degrades    .rel { color: var(--t-inference); background: rgba(225,109,142,0.10); }
+.disc-row.r-compatible  .rel { color: var(--t-architecture); background: rgba(110,199,160,0.10); }
+
+.disc-row .pair {
+  white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis;
+  font-family: var(--f-display);
+  font-size: 12px;
+  letter-spacing: 0.01em;
+}
+.disc-row .pair .a, .disc-row .pair .b { color: var(--bone-1); }
+.disc-row .pair .arr { color: var(--brass-2); margin: 0 6px; }
+
+.disc-row .src {
+  color: var(--bone-4);
+  font-size: 9.5px;
+  white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis;
+  max-width: 140px;
+}
+.disc-row .ts {
+  color: var(--bone-4);
+  font-size: 9px;
+  letter-spacing: 0.08em;
+  font-variant-numeric: tabular-nums;
+}
+
+/* ── Evidence tooltip (positioned absolutely by JS) ──────────────────────── */
+.evidence-tip {
+  position: fixed;
+  z-index: 100;
+  pointer-events: none;
+  max-width: 320px;
+  background: rgba(11, 14, 19, 0.96);
+  border: 1px solid var(--steel-1);
+  border-radius: 6px;
+  padding: 12px 14px;
+  box-shadow: 0 12px 36px rgba(0,0,0,0.6), 0 0 0 1px rgba(255,106,31,0.06);
+  font-size: 12px;
+  animation: tip-in 160ms ease;
+}
+@keyframes tip-in { from { opacity: 0; transform: translateY(4px); } to { opacity: 1; transform: translateY(0); } }
+.evidence-tip .tip-head {
+  display: flex; align-items: center; gap: 8px;
+  margin-bottom: 8px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--coal-5);
+}
+.evidence-tip .tip-name {
+  font-family: var(--f-display);
+  font-size: 15px;
+  color: var(--bone-1);
+}
+.evidence-tip .tip-status {
+  margin-left: auto;
+  font-family: var(--f-mono);
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+  padding: 2px 6px;
+  border-radius: 2px;
+}
+.tip-status.blocked     { color: var(--rust);  background: rgba(200,64,60,0.12); }
+.tip-status.conditional { color: var(--amber); background: rgba(224,161,60,0.12); }
+.tip-status.selected    { color: var(--ember-2); background: rgba(255,106,31,0.12); }
+.tip-status.available   { color: var(--t-architecture); background: rgba(110,199,160,0.12); }
+
+.evidence-tip .tip-reason {
+  margin-bottom: 8px;
+}
+.evidence-tip .tip-reason-label {
+  font-family: var(--f-mono);
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+  color: var(--bone-4);
+  margin-bottom: 3px;
+}
+.evidence-tip .tip-reason-fix {
+  font-size: 12px;
+  color: var(--bone-2);
+  line-height: 1.5;
+}
+.evidence-tip .quote {
+  font-family: Georgia, serif;
+  font-style: italic;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--bone-2);
+  border-left: 2px solid var(--brass-1);
+  padding-left: 10px;
+  margin: 6px 0 8px;
+}
+.evidence-tip .tip-foot {
+  display: flex; align-items: center; justify-content: space-between; gap: 8px;
+  font-family: var(--f-mono);
+  font-size: 9.5px;
+  color: var(--bone-4);
+  margin-top: 6px;
+}
+.evidence-tip .src-link {
+  color: var(--bone-3);
+  text-decoration: none;
+  border-bottom: 1px dotted var(--bone-4);
+  white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis;
+  max-width: 200px;
+}
+.evidence-tip .tier-badge {
+  font-weight: 600;
+  padding: 2px 5px;
+  border-radius: 2px;
+  color: var(--coal-0);
+}
+.tier-badge.t1 { background: var(--brass-1); }
+.tier-badge.t2 { background: var(--brass-2); }
+.tier-badge.t3 { background: var(--brass-3); }
+
+/* ── Scrollbars ─────────────────────────────────────────────────────────── */
+::-webkit-scrollbar { width: 8px; height: 8px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb {
+  background: var(--coal-5);
+  border-radius: 4px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+::-webkit-scrollbar-thumb:hover { background: var(--steel-1); background-clip: padding-box; }
+
+/* ── Type colors injected via inline style on node group ─────────────────── */
+/* They use --type-color which is set on the <g class="node"> element. */
+
+/* ── Responsive guard for narrow viewports ──────────────────────────────── */
+@media (max-width: 1100px) {
+  .main { grid-template-columns: 260px 1fr 320px; }
+  .ticker { width: min(440px, calc(100% - 600px)); }
+}

frontend/ticker.jsx

@@ -0,0 +1,59 @@
+// Live Discoveries ticker. Items animate in from the bottom.
+// Simulates new edges arriving from the Bright Data scraper.
+
+window.DiscoveriesTicker = function DiscoveriesTicker() {
+  const seed = window.FORGE_DISCOVERIES;
+  const futures = window.FORGE_FUTURE_DISCOVERIES;
+  const [items, setItems] = React.useState(seed.slice(0, 6).map((d, i) => ({ ...d, _id: i, _t: Date.now() + d.ts_offset * 1000 })));
+  const idRef = React.useRef(seed.length);
+  const futIdxRef = React.useRef(0);
+
+  React.useEffect(() => {
+    const interval = setInterval(() => {
+      const next = futures[futIdxRef.current % futures.length];
+      futIdxRef.current += 1;
+      const item = { ...next, _id: idRef.current++, _t: Date.now() };
+      setItems(prev => [item, ...prev].slice(0, 6));
+    }, 5200);
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <div className="ticker">
+      <div className="ticker-head">
+        <span className="dot" />
+        <span className="label">Live Discoveries</span>
+        <span>— scraper · bright data SERP</span>
+        <span className="feed">
+          <span style={{ color: "var(--bone-3)" }}>{items.length}</span>
+          <span>new this minute</span>
+        </span>
+      </div>
+      <div className="ticker-list">
+        {items.map((d) => (
+          <div key={d._id} className={`disc-row r-${d.relation.toLowerCase()}`}>
+            <span className="rel">{d.relation}</span>
+            <span className="pair">
+              <span className="a">{d.a}</span>
+              <span className="arr">→</span>
+              <span className="b">{d.b}</span>
+            </span>
+            <span className="src" title={d.source}>{d.source}</span>
+            <span className={`tier-badge t${d.tier}`}>T{d.tier}</span>
+            <span className="ts" style={{ gridColumn: "1 / -1", color: "var(--bone-4)", marginTop: -1 }}>
+              {relativeTime(d._t)}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+function relativeTime(t) {
+  const dt = Math.floor((Date.now() - t) / 1000);
+  if (dt < 5) return "just now";
+  if (dt < 60) return `${dt}s ago`;
+  if (dt < 3600) return `${Math.floor(dt/60)}m ago`;
+  return `${Math.floor(dt/3600)}h ago`;
+}

frontend/tooltip.jsx

@@ -0,0 +1,97 @@
+// Evidence tooltip — appears on hover over a node or edge, anchored to cursor.
+
+window.EvidenceTip = function EvidenceTip({ payload }) {
+  if (!payload) return null;
+  const { node, edge, status, reasons, pos } = payload;
+
+  const W = 320;
+  let left = pos.x + 16;
+  let top = pos.y + 14;
+  if (typeof window !== "undefined") {
+    if (left + W > window.innerWidth - 12) left = pos.x - W - 16;
+    if (top + 220 > window.innerHeight - 12) top = pos.y - 220;
+    if (top < 12) top = 12;
+  }
+
+  return (
+    <div className="evidence-tip" style={{ left, top, width: W }}>
+      {node && (
+        <>
+          <div className="tip-head">
+            <span className="tip-name">{node.name}</span>
+            <span className={`tip-status ${status}`}>{status}</span>
+          </div>
+          <div style={{ fontSize: 11.5, color: "var(--bone-3)", lineHeight: 1.5, marginBottom: 8 }}>
+            {node.description}
+          </div>
+          {reasons && reasons.length > 0 && (
+            <>
+              {reasons.slice(0, 2).map((r, i) => {
+                const ev = (r.evidence && r.evidence[0]) || null;
+                return (
+                  <div className="tip-reason" key={i}>
+                    <div className="tip-reason-label" style={{
+                      color: r.kind === "blocked" ? "var(--rust)"
+                           : r.kind === "needed-by" ? "var(--amber)"
+                           : "var(--amber)"
+                    }}>
+                      {r.label}
+                    </div>
+                    {r.fix && <div className="tip-reason-fix">{r.fix}</div>}
+                    {ev && ev.quote && <div className="quote">“{ev.quote}”</div>}
+                    {ev && (
+                      <div className="tip-foot">
+                        <a className="src-link" href={ev.url} target="_blank" rel="noopener">{prettyUrl(ev.url)}</a>
+                        <span className={`tier-badge t${ev.tier || r.tier || 1}`}>T{ev.tier || r.tier || 1}</span>
+                      </div>
+                    )}
+                  </div>
+                );
+              })}
+            </>
+          )}
+          {(!reasons || reasons.length === 0) && (
+            <div className="tip-foot">
+              <span style={{ color: "var(--bone-4)" }}>type · {node.type}</span>
+              <span className={`tier-badge t${node.tier}`}>T{node.tier}</span>
+            </div>
+          )}
+        </>
+      )}
+      {edge && (
+        <>
+          <div className="tip-head">
+            <span className="tip-name" style={{ fontSize: 13 }}>
+              {displayName(edge.from)} <span style={{ color: "var(--bone-4)", margin: "0 6px" }}>→</span> {displayName(edge.to)}
+            </span>
+            <span className={`tip-status ${edge.relation === "BREAKS" ? "blocked" : "conditional"}`}>{edge.relation}</span>
+          </div>
+          {edge.fix && <div className="tip-reason-fix" style={{ marginBottom: 8 }}>{edge.fix}</div>}
+          {edge.evidence && edge.evidence[0] && (
+            <>
+              <div className="quote">“{edge.evidence[0].quote}”</div>
+              <div className="tip-foot">
+                <a className="src-link" href={edge.evidence[0].url} target="_blank" rel="noopener">{prettyUrl(edge.evidence[0].url)}</a>
+                <span className={`tier-badge t${edge.tier}`}>T{edge.tier}</span>
+              </div>
+            </>
+          )}
+        </>
+      )}
+    </div>
+  );
+};
+
+function displayName(c) {
+  const n = (window.FORGE_NODES || []).find(x => x.canonical === c);
+  return n ? n.name : c;
+}
+
+function prettyUrl(url) {
+  if (!url) return "";
+  if (url.startsWith("mempalace://")) return "mempalace · rick";
+  try {
+    const u = new URL(url);
+    return u.hostname.replace(/^www\./, "") + u.pathname;
+  } catch { return url; }
+}

frontend/tweaks-panel.jsx

@@ -0,0 +1,530 @@
+
+// tweaks-panel.jsx
+// Reusable Tweaks shell + form-control helpers.
+//
+// Owns the host protocol (listens for __activate_edit_mode / __deactivate_edit_mode,
+// posts __edit_mode_available / __edit_mode_set_keys / __edit_mode_dismissed) so
+// individual prototypes don't re-roll it. Ships a consistent set of controls so you
+// don't hand-draw <input type="range">, segmented radios, steppers, etc.
+//
+// Usage (in an HTML file that loads React + Babel):
+//
+//   const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+//     "primaryColor": "#D97757",
+//     "palette": ["#D97757", "#29261b", "#f6f4ef"],
+//     "fontSize": 16,
+//     "density": "regular",
+//     "dark": false
+//   }/*EDITMODE-END*/;
+//
+//   function App() {
+//     const [t, setTweak] = useTweaks(TWEAK_DEFAULTS);
+//     return (
+//       <div style={{ fontSize: t.fontSize, color: t.primaryColor }}>
+//         Hello
+//         <TweaksPanel>
+//           <TweakSection label="Typography" />
+//           <TweakSlider label="Font size" value={t.fontSize} min={10} max={32} unit="px"
+//                        onChange={(v) => setTweak('fontSize', v)} />
+//           <TweakRadio  label="Density" value={t.density}
+//                        options={['compact', 'regular', 'comfy']}
+//                        onChange={(v) => setTweak('density', v)} />
+//           <TweakSection label="Theme" />
+//           <TweakColor  label="Primary" value={t.primaryColor}
+//                        options={['#D97757', '#2A6FDB', '#1F8A5B', '#7A5AE0']}
+//                        onChange={(v) => setTweak('primaryColor', v)} />
+//           <TweakColor  label="Palette" value={t.palette}
+//                        options={[['#D97757', '#29261b', '#f6f4ef'],
+//                                  ['#475569', '#0f172a', '#f1f5f9']]}
+//                        onChange={(v) => setTweak('palette', v)} />
+//           <TweakToggle label="Dark mode" value={t.dark}
+//                        onChange={(v) => setTweak('dark', v)} />
+//         </TweaksPanel>
+//       </div>
+//     );
+//   }
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+const __TWEAKS_STYLE = `
+  .twk-panel{position:fixed;right:16px;bottom:16px;z-index:2147483646;width:280px;
+    max-height:calc(100vh - 32px);display:flex;flex-direction:column;
+    transform:scale(var(--dc-inv-zoom,1));transform-origin:bottom right;
+    background:rgba(250,249,247,.78);color:#29261b;
+    -webkit-backdrop-filter:blur(24px) saturate(160%);backdrop-filter:blur(24px) saturate(160%);
+    border:.5px solid rgba(255,255,255,.6);border-radius:14px;
+    box-shadow:0 1px 0 rgba(255,255,255,.5) inset,0 12px 40px rgba(0,0,0,.18);
+    font:11.5px/1.4 ui-sans-serif,system-ui,-apple-system,sans-serif;overflow:hidden}
+  .twk-hd{display:flex;align-items:center;justify-content:space-between;
+    padding:10px 8px 10px 14px;cursor:move;user-select:none}
+  .twk-hd b{font-size:12px;font-weight:600;letter-spacing:.01em}
+  .twk-x{appearance:none;border:0;background:transparent;color:rgba(41,38,27,.55);
+    width:22px;height:22px;border-radius:6px;cursor:default;font-size:13px;line-height:1}
+  .twk-x:hover{background:rgba(0,0,0,.06);color:#29261b}
+  .twk-body{padding:2px 14px 14px;display:flex;flex-direction:column;gap:10px;
+    overflow-y:auto;overflow-x:hidden;min-height:0;
+    scrollbar-width:thin;scrollbar-color:rgba(0,0,0,.15) transparent}
+  .twk-body::-webkit-scrollbar{width:8px}
+  .twk-body::-webkit-scrollbar-track{background:transparent;margin:2px}
+  .twk-body::-webkit-scrollbar-thumb{background:rgba(0,0,0,.15);border-radius:4px;
+    border:2px solid transparent;background-clip:content-box}
+  .twk-body::-webkit-scrollbar-thumb:hover{background:rgba(0,0,0,.25);
+    border:2px solid transparent;background-clip:content-box}
+  .twk-row{display:flex;flex-direction:column;gap:5px}
+  .twk-row-h{flex-direction:row;align-items:center;justify-content:space-between;gap:10px}
+  .twk-lbl{display:flex;justify-content:space-between;align-items:baseline;
+    color:rgba(41,38,27,.72)}
+  .twk-lbl>span:first-child{font-weight:500}
+  .twk-val{color:rgba(41,38,27,.5);font-variant-numeric:tabular-nums}
+
+  .twk-sect{font-size:10px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;
+    color:rgba(41,38,27,.45);padding:10px 0 0}
+  .twk-sect:first-child{padding-top:0}
+
+  .twk-field{appearance:none;box-sizing:border-box;width:100%;min-width:0;height:26px;padding:0 8px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:7px;
+    background:rgba(255,255,255,.6);color:inherit;font:inherit;outline:none}
+  .twk-field:focus{border-color:rgba(0,0,0,.25);background:rgba(255,255,255,.85)}
+  select.twk-field{padding-right:22px;
+    background-image:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'><path fill='rgba(0,0,0,.5)' d='M0 0h10L5 6z'/></svg>");
+    background-repeat:no-repeat;background-position:right 8px center}
+
+  .twk-slider{appearance:none;-webkit-appearance:none;width:100%;height:4px;margin:6px 0;
+    border-radius:999px;background:rgba(0,0,0,.12);outline:none}
+  .twk-slider::-webkit-slider-thumb{-webkit-appearance:none;appearance:none;
+    width:14px;height:14px;border-radius:50%;background:#fff;
+    border:.5px solid rgba(0,0,0,.12);box-shadow:0 1px 3px rgba(0,0,0,.2);cursor:default}
+  .twk-slider::-moz-range-thumb{width:14px;height:14px;border-radius:50%;
+    background:#fff;border:.5px solid rgba(0,0,0,.12);box-shadow:0 1px 3px rgba(0,0,0,.2);cursor:default}
+
+  .twk-seg{position:relative;display:flex;padding:2px;border-radius:8px;
+    background:rgba(0,0,0,.06);user-select:none}
+  .twk-seg-thumb{position:absolute;top:2px;bottom:2px;border-radius:6px;
+    background:rgba(255,255,255,.9);box-shadow:0 1px 2px rgba(0,0,0,.12);
+    transition:left .15s cubic-bezier(.3,.7,.4,1),width .15s}
+  .twk-seg.dragging .twk-seg-thumb{transition:none}
+  .twk-seg button{appearance:none;position:relative;z-index:1;flex:1;border:0;
+    background:transparent;color:inherit;font:inherit;font-weight:500;min-height:22px;
+    border-radius:6px;cursor:default;padding:4px 6px;line-height:1.2;
+    overflow-wrap:anywhere}
+
+  .twk-toggle{position:relative;width:32px;height:18px;border:0;border-radius:999px;
+    background:rgba(0,0,0,.15);transition:background .15s;cursor:default;padding:0}
+  .twk-toggle[data-on="1"]{background:#34c759}
+  .twk-toggle i{position:absolute;top:2px;left:2px;width:14px;height:14px;border-radius:50%;
+    background:#fff;box-shadow:0 1px 2px rgba(0,0,0,.25);transition:transform .15s}
+  .twk-toggle[data-on="1"] i{transform:translateX(14px)}
+
+  .twk-num{display:flex;align-items:center;box-sizing:border-box;min-width:0;height:26px;padding:0 0 0 8px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:7px;background:rgba(255,255,255,.6)}
+  .twk-num-lbl{font-weight:500;color:rgba(41,38,27,.6);cursor:ew-resize;
+    user-select:none;padding-right:8px}
+  .twk-num input{flex:1;min-width:0;height:100%;border:0;background:transparent;
+    font:inherit;font-variant-numeric:tabular-nums;text-align:right;padding:0 8px 0 0;
+    outline:none;color:inherit;-moz-appearance:textfield}
+  .twk-num input::-webkit-inner-spin-button,.twk-num input::-webkit-outer-spin-button{
+    -webkit-appearance:none;margin:0}
+  .twk-num-unit{padding-right:8px;color:rgba(41,38,27,.45)}
+
+  .twk-btn{appearance:none;height:26px;padding:0 12px;border:0;border-radius:7px;
+    background:rgba(0,0,0,.78);color:#fff;font:inherit;font-weight:500;cursor:default}
+  .twk-btn:hover{background:rgba(0,0,0,.88)}
+  .twk-btn.secondary{background:rgba(0,0,0,.06);color:inherit}
+  .twk-btn.secondary:hover{background:rgba(0,0,0,.1)}
+
+  .twk-swatch{appearance:none;-webkit-appearance:none;width:56px;height:22px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:6px;padding:0;cursor:default;
+    background:transparent;flex-shrink:0}
+  .twk-swatch::-webkit-color-swatch-wrapper{padding:0}
+  .twk-swatch::-webkit-color-swatch{border:0;border-radius:5.5px}
+  .twk-swatch::-moz-color-swatch{border:0;border-radius:5.5px}
+
+  .twk-chips{display:flex;gap:6px}
+  .twk-chip{position:relative;appearance:none;flex:1;min-width:0;height:46px;
+    padding:0;border:0;border-radius:6px;overflow:hidden;cursor:default;
+    box-shadow:0 0 0 .5px rgba(0,0,0,.12),0 1px 2px rgba(0,0,0,.06);
+    transition:transform .12s cubic-bezier(.3,.7,.4,1),box-shadow .12s}
+  .twk-chip:hover{transform:translateY(-1px);
+    box-shadow:0 0 0 .5px rgba(0,0,0,.18),0 4px 10px rgba(0,0,0,.12)}
+  .twk-chip[data-on="1"]{box-shadow:0 0 0 1.5px rgba(0,0,0,.85),
+    0 2px 6px rgba(0,0,0,.15)}
+  .twk-chip>span{position:absolute;top:0;bottom:0;right:0;width:34%;
+    display:flex;flex-direction:column;box-shadow:-1px 0 0 rgba(0,0,0,.1)}
+  .twk-chip>span>i{flex:1;box-shadow:0 -1px 0 rgba(0,0,0,.1)}
+  .twk-chip>span>i:first-child{box-shadow:none}
+  .twk-chip svg{position:absolute;top:6px;left:6px;width:13px;height:13px;
+    filter:drop-shadow(0 1px 1px rgba(0,0,0,.3))}
+`;
+
+// ── useTweaks ───────────────────────────────────────────────────────────────
+// Single source of truth for tweak values. setTweak persists via the host
+// (__edit_mode_set_keys → host rewrites the EDITMODE block on disk).
+function useTweaks(defaults) {
+  const [values, setValues] = React.useState(defaults);
+  // Accepts either setTweak('key', value) or setTweak({ key: value, ... }) so a
+  // useState-style call doesn't write a "[object Object]" key into the persisted
+  // JSON block.
+  const setTweak = React.useCallback((keyOrEdits, val) => {
+    const edits = typeof keyOrEdits === 'object' && keyOrEdits !== null
+      ? keyOrEdits : { [keyOrEdits]: val };
+    setValues((prev) => ({ ...prev, ...edits }));
+    window.parent.postMessage({ type: '__edit_mode_set_keys', edits }, '*');
+    // Same-window signal so in-page listeners (deck-stage rail thumbnails)
+    // can react — the parent message only reaches the host, not peers.
+    window.dispatchEvent(new CustomEvent('tweakchange', { detail: edits }));
+  }, []);
+  return [values, setTweak];
+}
+
+// ── TweaksPanel ─────────────────────────────────────────────────────────────
+// Floating shell. Registers the protocol listener BEFORE announcing
+// availability — if the announce ran first, the host's activate could land
+// before our handler exists and the toolbar toggle would silently no-op.
+// The close button posts __edit_mode_dismissed so the host's toolbar toggle
+// flips off in lockstep; the host echoes __deactivate_edit_mode back which
+// is what actually hides the panel.
+function TweaksPanel({ title = 'Tweaks', children }) {
+  const [open, setOpen] = React.useState(false);
+  const dragRef = React.useRef(null);
+  const offsetRef = React.useRef({ x: 16, y: 16 });
+  const PAD = 16;
+
+  const clampToViewport = React.useCallback(() => {
+    const panel = dragRef.current;
+    if (!panel) return;
+    const w = panel.offsetWidth, h = panel.offsetHeight;
+    const maxRight = Math.max(PAD, window.innerWidth - w - PAD);
+    const maxBottom = Math.max(PAD, window.innerHeight - h - PAD);
+    offsetRef.current = {
+      x: Math.min(maxRight, Math.max(PAD, offsetRef.current.x)),
+      y: Math.min(maxBottom, Math.max(PAD, offsetRef.current.y)),
+    };
+    panel.style.right = offsetRef.current.x + 'px';
+    panel.style.bottom = offsetRef.current.y + 'px';
+  }, []);
+
+  React.useEffect(() => {
+    if (!open) return;
+    clampToViewport();
+    if (typeof ResizeObserver === 'undefined') {
+      window.addEventListener('resize', clampToViewport);
+      return () => window.removeEventListener('resize', clampToViewport);
+    }
+    const ro = new ResizeObserver(clampToViewport);
+    ro.observe(document.documentElement);
+    return () => ro.disconnect();
+  }, [open, clampToViewport]);
+
+  React.useEffect(() => {
+    const onMsg = (e) => {
+      const t = e?.data?.type;
+      if (t === '__activate_edit_mode') setOpen(true);
+      else if (t === '__deactivate_edit_mode') setOpen(false);
+    };
+    window.addEventListener('message', onMsg);
+    window.parent.postMessage({ type: '__edit_mode_available' }, '*');
+    return () => window.removeEventListener('message', onMsg);
+  }, []);
+
+  const dismiss = () => {
+    setOpen(false);
+    window.parent.postMessage({ type: '__edit_mode_dismissed' }, '*');
+  };
+
+  const onDragStart = (e) => {
+    const panel = dragRef.current;
+    if (!panel) return;
+    const r = panel.getBoundingClientRect();
+    const sx = e.clientX, sy = e.clientY;
+    const startRight = window.innerWidth - r.right;
+    const startBottom = window.innerHeight - r.bottom;
+    const move = (ev) => {
+      offsetRef.current = {
+        x: startRight - (ev.clientX - sx),
+        y: startBottom - (ev.clientY - sy),
+      };
+      clampToViewport();
+    };
+    const up = () => {
+      window.removeEventListener('mousemove', move);
+      window.removeEventListener('mouseup', up);
+    };
+    window.addEventListener('mousemove', move);
+    window.addEventListener('mouseup', up);
+  };
+
+  if (!open) return null;
+  return (
+    <>
+      <style>{__TWEAKS_STYLE}</style>
+      <div ref={dragRef} className="twk-panel" data-omelette-chrome=""
+           style={{ right: offsetRef.current.x, bottom: offsetRef.current.y }}>
+        <div className="twk-hd" onMouseDown={onDragStart}>
+          <b>{title}</b>
+          <button className="twk-x" aria-label="Close tweaks"
+                  onMouseDown={(e) => e.stopPropagation()}
+                  onClick={dismiss}>✕</button>
+        </div>
+        <div className="twk-body">
+          {children}
+        </div>
+      </div>
+    </>
+  );
+}
+
+// ── Layout helpers ──────────────────────────────────────────────────────────
+
+function TweakSection({ label, children }) {
+  return (
+    <>
+      <div className="twk-sect">{label}</div>
+      {children}
+    </>
+  );
+}
+
+function TweakRow({ label, value, children, inline = false }) {
+  return (
+    <div className={inline ? 'twk-row twk-row-h' : 'twk-row'}>
+      <div className="twk-lbl">
+        <span>{label}</span>
+        {value != null && <span className="twk-val">{value}</span>}
+      </div>
+      {children}
+    </div>
+  );
+}
+
+// ── Controls ────────────────────────────────────────────────────────────────
+
+function TweakSlider({ label, value, min = 0, max = 100, step = 1, unit = '', onChange }) {
+  return (
+    <TweakRow label={label} value={`${value}${unit}`}>
+      <input type="range" className="twk-slider" min={min} max={max} step={step}
+             value={value} onChange={(e) => onChange(Number(e.target.value))} />
+    </TweakRow>
+  );
+}
+
+function TweakToggle({ label, value, onChange }) {
+  return (
+    <div className="twk-row twk-row-h">
+      <div className="twk-lbl"><span>{label}</span></div>
+      <button type="button" className="twk-toggle" data-on={value ? '1' : '0'}
+              role="switch" aria-checked={!!value}
+              onClick={() => onChange(!value)}><i /></button>
+    </div>
+  );
+}
+
+function TweakRadio({ label, value, options, onChange }) {
+  const trackRef = React.useRef(null);
+  const [dragging, setDragging] = React.useState(false);
+  // The active value is read by pointer-move handlers attached for the lifetime
+  // of a drag — ref it so a stale closure doesn't fire onChange for every move.
+  const valueRef = React.useRef(value);
+  valueRef.current = value;
+
+  // Segments wrap mid-word once per-segment width runs out. The track is
+  // ~248px (280 panel − 28 body pad − 4 seg pad), each button loses 12px
+  // to its own padding, and 11.5px system-ui averages ~6.3px/char — so 2
+  // options fit ~16 chars each, 3 fit ~10. Past that (or >3 options), fall
+  // back to a dropdown rather than wrap.
+  const labelLen = (o) => String(typeof o === 'object' ? o.label : o).length;
+  const maxLen = options.reduce((m, o) => Math.max(m, labelLen(o)), 0);
+  const fitsAsSegments = maxLen <= ({ 2: 16, 3: 10 }[options.length] ?? 0);
+  if (!fitsAsSegments) {
+    // <select> emits strings — map back to the original option value so the
+    // fallback stays type-preserving (numbers, booleans) like the segment path.
+    const resolve = (s) => {
+      const m = options.find((o) => String(typeof o === 'object' ? o.value : o) === s);
+      return m === undefined ? s : typeof m === 'object' ? m.value : m;
+    };
+    return <TweakSelect label={label} value={value} options={options}
+                        onChange={(s) => onChange(resolve(s))} />;
+  }
+  const opts = options.map((o) => (typeof o === 'object' ? o : { value: o, label: o }));
+  const idx = Math.max(0, opts.findIndex((o) => o.value === value));
+  const n = opts.length;
+
+  const segAt = (clientX) => {
+    const r = trackRef.current.getBoundingClientRect();
+    const inner = r.width - 4;
+    const i = Math.floor(((clientX - r.left - 2) / inner) * n);
+    return opts[Math.max(0, Math.min(n - 1, i))].value;
+  };
+
+  const onPointerDown = (e) => {
+    setDragging(true);
+    const v0 = segAt(e.clientX);
+    if (v0 !== valueRef.current) onChange(v0);
+    const move = (ev) => {
+      if (!trackRef.current) return;
+      const v = segAt(ev.clientX);
+      if (v !== valueRef.current) onChange(v);
+    };
+    const up = () => {
+      setDragging(false);
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', up);
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+  };
+
+  return (
+    <TweakRow label={label}>
+      <div ref={trackRef} role="radiogroup" onPointerDown={onPointerDown}
+           className={dragging ? 'twk-seg dragging' : 'twk-seg'}>
+        <div className="twk-seg-thumb"
+             style={{ left: `calc(2px + ${idx} * (100% - 4px) / ${n})`,
+                      width: `calc((100% - 4px) / ${n})` }} />
+        {opts.map((o) => (
+          <button key={o.value} type="button" role="radio" aria-checked={o.value === value}>
+            {o.label}
+          </button>
+        ))}
+      </div>
+    </TweakRow>
+  );
+}
+
+function TweakSelect({ label, value, options, onChange }) {
+  return (
+    <TweakRow label={label}>
+      <select className="twk-field" value={value} onChange={(e) => onChange(e.target.value)}>
+        {options.map((o) => {
+          const v = typeof o === 'object' ? o.value : o;
+          const l = typeof o === 'object' ? o.label : o;
+          return <option key={v} value={v}>{l}</option>;
+        })}
+      </select>
+    </TweakRow>
+  );
+}
+
+function TweakText({ label, value, placeholder, onChange }) {
+  return (
+    <TweakRow label={label}>
+      <input className="twk-field" type="text" value={value} placeholder={placeholder}
+             onChange={(e) => onChange(e.target.value)} />
+    </TweakRow>
+  );
+}
+
+function TweakNumber({ label, value, min, max, step = 1, unit = '', onChange }) {
+  const clamp = (n) => {
+    if (min != null && n < min) return min;
+    if (max != null && n > max) return max;
+    return n;
+  };
+  const startRef = React.useRef({ x: 0, val: 0 });
+  const onScrubStart = (e) => {
+    e.preventDefault();
+    startRef.current = { x: e.clientX, val: value };
+    const decimals = (String(step).split('.')[1] || '').length;
+    const move = (ev) => {
+      const dx = ev.clientX - startRef.current.x;
+      const raw = startRef.current.val + dx * step;
+      const snapped = Math.round(raw / step) * step;
+      onChange(clamp(Number(snapped.toFixed(decimals))));
+    };
+    const up = () => {
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', up);
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+  };
+  return (
+    <div className="twk-num">
+      <span className="twk-num-lbl" onPointerDown={onScrubStart}>{label}</span>
+      <input type="number" value={value} min={min} max={max} step={step}
+             onChange={(e) => onChange(clamp(Number(e.target.value)))} />
+      {unit && <span className="twk-num-unit">{unit}</span>}
+    </div>
+  );
+}
+
+// Relative-luminance contrast pick — checkmarks drawn over a swatch need to
+// read on both #111 and #fafafa without per-option configuration. Hex input
+// only (#rgb / #rrggbb); named or rgb()/hsl() colors fall through to "light".
+function __twkIsLight(hex) {
+  const h = String(hex).replace('#', '');
+  const x = h.length === 3 ? h.replace(/./g, (c) => c + c) : h.padEnd(6, '0');
+  const n = parseInt(x.slice(0, 6), 16);
+  if (Number.isNaN(n)) return true;
+  const r = (n >> 16) & 255, g = (n >> 8) & 255, b = n & 255;
+  return r * 299 + g * 587 + b * 114 > 148000;
+}
+
+const __TwkCheck = ({ light }) => (
+  <svg viewBox="0 0 14 14" aria-hidden="true">
+    <path d="M3 7.2 5.8 10 11 4.2" fill="none" strokeWidth="2.2"
+          strokeLinecap="round" strokeLinejoin="round"
+          stroke={light ? 'rgba(0,0,0,.78)' : '#fff'} />
+  </svg>
+);
+
+// TweakColor — curated color/palette picker. Each option is either a single
+// hex string or an array of 1-5 hex strings; the card adapts — a lone color
+// renders solid, a palette renders colors[0] as the hero (left ~2/3) with the
+// rest stacked in a sharp column on the right. onChange emits the
+// option in the shape it was passed (string stays string, array stays array).
+// Without options it falls back to the native color input for back-compat.
+function TweakColor({ label, value, options, onChange }) {
+  if (!options || !options.length) {
+    return (
+      <div className="twk-row twk-row-h">
+        <div className="twk-lbl"><span>{label}</span></div>
+        <input type="color" className="twk-swatch" value={value}
+               onChange={(e) => onChange(e.target.value)} />
+      </div>
+    );
+  }
+  // Native <input type=color> emits lowercase hex per the HTML spec, so
+  // compare case-insensitively. String() guards JSON.stringify(undefined),
+  // which returns the primitive undefined (no .toLowerCase).
+  const key = (o) => String(JSON.stringify(o)).toLowerCase();
+  const cur = key(value);
+  return (
+    <TweakRow label={label}>
+      <div className="twk-chips" role="radiogroup">
+        {options.map((o, i) => {
+          const colors = Array.isArray(o) ? o : [o];
+          const [hero, ...rest] = colors;
+          const sup = rest.slice(0, 4);
+          const on = key(o) === cur;
+          return (
+            <button key={i} type="button" className="twk-chip" role="radio"
+                    aria-checked={on} data-on={on ? '1' : '0'}
+                    aria-label={colors.join(', ')} title={colors.join(' · ')}
+                    style={{ background: hero }}
+                    onClick={() => onChange(o)}>
+              {sup.length > 0 && (
+                <span>
+                  {sup.map((c, j) => <i key={j} style={{ background: c }} />)}
+                </span>
+              )}
+              {on && <__TwkCheck light={__twkIsLight(hero)} />}
+            </button>
+          );
+        })}
+      </div>
+    </TweakRow>
+  );
+}
+
+function TweakButton({ label, onClick, secondary = false }) {
+  return (
+    <button type="button" className={secondary ? 'twk-btn secondary' : 'twk-btn'}
+            onClick={onClick}>{label}</button>
+  );
+}
+
+Object.assign(window, {
+  useTweaks, TweaksPanel, TweakSection, TweakRow,
+  TweakSlider, TweakToggle, TweakRadio, TweakSelect,
+  TweakText, TweakNumber, TweakColor, TweakButton,
+});

requirements.txt

@@ -0,0 +1,3 @@
+# Forge app deps. External (not pip): Bright Data CLI, llama.cpp (llama-server).
+fastapi
+uvicorn[standard]