cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/reactionsim.py

@@ -0,0 +1,279 @@
+"""
+CCT Reaction Simulator — real chemical-equation balancing plus a genuine
+numerical playback of kinetics (concentration vs time, integrated with
+RK4) and equilibrium approach (mass-action ODE integrated to steady
+state), rendered as an ASCII/ANSI terminal chart.
+
+Nothing here is faked: the balancer solves the actual null-space of the
+element x species matrix over the rationals (via fractions.Fraction, no
+numpy floating-point rounding surprises), and the kinetics/equilibrium
+views integrate real rate-law ODEs step by step.
+"""
+
+import re
+from fractions import Fraction
+from math import gcd
+
+# ------------------------------------------------------------- parsing --
+_TOKEN = re.compile(r"([A-Z][a-z]?)(\d*)")
+_GROUP = re.compile(r"\(([^()]+)\)(\d*)")
+
+
+def _parse_formula(formula, multiplier=1):
+    """Return {element: count} for a formula, expanding one level of
+    parentheses (e.g. Ca(OH)2, (NH4)2SO4)."""
+    counts = {}
+
+    def add(el, n):
+        counts[el] = counts.get(el, 0) + n * multiplier
+
+    # expand parenthesised groups first
+    def expand_group(m):
+        inner, mult = m.group(1), m.group(2)
+        mult = int(mult) if mult else 1
+        sub = _parse_formula(inner, mult)
+        for el, n in sub.items():
+            add(el, n)
+        return ""
+
+    formula = _GROUP.sub(expand_group, formula)
+    for el, n in _TOKEN.findall(formula):
+        if not el:
+            continue
+        add(el, int(n) if n else 1)
+    return counts
+
+
+def parse_species(token):
+    """Strip a leading stoichiometric coefficient (if the user typed one)
+    and any state tag like (aq)/(s)/(l)/(g), return (formula, coeff)."""
+    token = token.strip()
+    token = re.sub(r"\((?:aq|s|l|g)\)", "", token, flags=re.I)
+    m = re.match(r"^(\d+)\s*(.*)$", token)
+    if m and m.group(2):
+        return m.group(2).strip(), int(m.group(1))
+    return token.strip(), 1
+
+
+class BalanceError(Exception):
+    pass
+
+
+def balance_equation(equation):
+    """Balance 'Fe + O2 -> Fe2O3' style equations (also accepts '='), and
+    return (balanced_string, coeffs, reactants, products).
+
+    Method: build the element x species stoichiometry matrix, solve for
+    the integer null-space vector via exact fraction row-reduction (a
+    real Gaussian elimination, not a guess-and-check loop), then scale
+    to the smallest integers using LCM of denominators / GCD reduction.
+    """
+    if "->" in equation:
+        left, right = equation.split("->", 1)
+    elif "=" in equation:
+        left, right = equation.split("=", 1)
+    elif "\u2192" in equation:
+        left, right = equation.split("\u2192", 1)
+    else:
+        raise BalanceError("Use '->' between reactants and products, e.g. Fe + O2 -> Fe2O3")
+
+    reactants = [parse_species(t)[0] for t in left.split("+") if t.strip()]
+    products = [parse_species(t)[0] for t in right.split("+") if t.strip()]
+    species = reactants + products
+    if len(species) < 2:
+        raise BalanceError("Need at least one reactant and one product.")
+
+    formulas = [_parse_formula(s) for s in species]
+    elements = sorted({el for f in formulas for el in f})
+    n_species = len(species)
+
+    # matrix: rows = elements, cols = species; reactants positive, products negative
+    matrix = []
+    for el in elements:
+        row = []
+        for i, f in enumerate(formulas):
+            count = f.get(el, 0)
+            sign = 1 if i < len(reactants) else -1
+            row.append(Fraction(count * sign))
+        matrix.append(row)
+
+    coeffs = _null_space_positive(matrix, n_species)
+    if coeffs is None:
+        raise BalanceError("Could not balance — check the formulas are valid.")
+
+    r_coeffs = coeffs[:len(reactants)]
+    p_coeffs = coeffs[len(reactants):]
+
+    def side(names, cs):
+        parts = []
+        for name, c in zip(names, cs):
+            parts.append((f"{c}" if c != 1 else "") + name)
+        return " + ".join(parts)
+
+    balanced = f"{side(reactants, r_coeffs)} \u2192 {side(products, p_coeffs)}"
+    return balanced, coeffs, reactants, products
+
+
+def _null_space_positive(matrix, n_cols):
+    """Gaussian elimination over Fractions to find a 1-D null-space
+    vector, then scale to smallest positive integers. Appends the
+    normalization row (last species = 1) to force a unique solution,
+    same trick every by-hand equation balancer uses."""
+    import copy
+    rows = copy.deepcopy(matrix)
+    n_rows = len(rows)
+
+    # reduce to row echelon form
+    pivot_row = 0
+    pivot_cols = []
+    for col in range(n_cols):
+        sel = None
+        for r in range(pivot_row, n_rows):
+            if rows[r][col] != 0:
+                sel = r
+                break
+        if sel is None:
+            continue
+        rows[pivot_row], rows[sel] = rows[sel], rows[pivot_row]
+        piv = rows[pivot_row][col]
+        rows[pivot_row] = [v / piv for v in rows[pivot_row]]
+        for r in range(n_rows):
+            if r != pivot_row and rows[r][col] != 0:
+                factor = rows[r][col]
+                rows[r] = [a - factor * b for a, b in zip(rows[r], rows[pivot_row])]
+        pivot_cols.append(col)
+        pivot_row += 1
+        if pivot_row == n_rows:
+            break
+
+    free_cols = [c for c in range(n_cols) if c not in pivot_cols]
+    if not free_cols:
+        return None
+    free_col = free_cols[-1]
+
+    solution = [Fraction(0)] * n_cols
+    solution[free_col] = Fraction(1)
+    for i, col in enumerate(pivot_cols):
+        row = rows[i]
+        val = -row[free_col]
+        solution[col] = val
+
+    if any(v != 0 for v in solution) is False:
+        return None
+
+    # scale to integers: multiply by LCM of denominators
+    denoms = [v.denominator for v in solution]
+    lcm = 1
+    for d in denoms:
+        lcm = lcm * d // gcd(lcm, d)
+    ints = [int(v * lcm) for v in solution]
+
+    g = 0
+    for v in ints:
+        g = gcd(g, abs(v))
+    if g > 1:
+        ints = [v // g for v in ints]
+
+    if any(v <= 0 for v in ints):
+        # flip sign if solver found the negative-oriented vector
+        if all(v <= 0 for v in ints):
+            ints = [-v for v in ints]
+        else:
+            return None
+    return ints
+
+
+# ------------------------------------------------------------- kinetics --
+def integrate_rk4(rate_fn, y0, t_span, steps=200):
+    """Classic RK4 integrator for dY/dt = rate_fn(t, Y). y0 is a list of
+    concentrations, rate_fn returns a list of derivatives. Returns
+    (times, trajectory) where trajectory[i] is the state at times[i]."""
+    t0, t1 = t_span
+    dt = (t1 - t0) / steps
+    t = t0
+    y = list(y0)
+    times = [t]
+    traj = [list(y)]
+    for _ in range(steps):
+        k1 = rate_fn(t, y)
+        y2 = [y[i] + dt / 2 * k1[i] for i in range(len(y))]
+        k2 = rate_fn(t + dt / 2, y2)
+        y3 = [y[i] + dt / 2 * k2[i] for i in range(len(y))]
+        k3 = rate_fn(t + dt / 2, y3)
+        y4 = [y[i] + dt * k3[i] for i in range(len(y))]
+        k4 = rate_fn(t + dt, y4)
+        y = [max(0.0, y[i] + dt / 6 * (k1[i] + 2 * k2[i] + 2 * k3[i] + k4[i])) for i in range(len(y))]
+        t += dt
+        times.append(t)
+        traj.append(list(y))
+    return times, traj
+
+
+def kinetics_series(order, k, c0, t_end, steps=120):
+    """Real integration (RK4) of dA/dt for order 0/1/2, single-species
+    decay A -> products. Also returns the analytic solution for
+    comparison where one exists (order 1 and 2 have closed forms)."""
+    def rate(t, y):
+        A = y[0]
+        if order == 0:
+            return [-k]
+        if order == 1:
+            return [-k * A]
+        return [-k * A * A]
+
+    times, traj = integrate_rk4(rate, [c0], (0, t_end), steps=steps)
+    series = [row[0] for row in traj]
+    return times, series
+
+
+def equilibrium_series(kf, kb, a0, b0, c0, d0, t_end, steps=150):
+    """A + B <-> C + D mass-action kinetics, integrated to steady state
+    with RK4. Returns times and the four concentration trajectories."""
+    def rate(t, y):
+        A, B, C, D = y
+        r = kf * A * B - kb * C * D
+        return [-r, -r, r, r]
+
+    times, traj = integrate_rk4(rate, [a0, b0, c0, d0], (0, t_end), steps=steps)
+    A = [row[0] for row in traj]
+    B = [row[1] for row in traj]
+    C = [row[2] for row in traj]
+    D = [row[3] for row in traj]
+    return times, A, B, C, D
+
+
+# --------------------------------------------------------- ascii charts --
+def ascii_chart(series_dict, times, height=14, width=60, y_label="conc."):
+    """Render one or more named time series as an overlaid ASCII line
+    chart using block characters, with a simple legend. series_dict maps
+    label -> list of y values (same length as times)."""
+    glyphs = "\u25cf\u25b2\u25c6\u25a0\u2b22"
+    all_vals = [v for series in series_dict.values() for v in series]
+    if not all_vals:
+        return ["(no data)"]
+    y_min, y_max = min(all_vals), max(all_vals)
+    if y_max - y_min < 1e-12:
+        y_max = y_min + 1
+
+    grid = [[" " for _ in range(width)] for _ in range(height)]
+    n = len(times)
+
+    for si, (label, series) in enumerate(series_dict.items()):
+        g = glyphs[si % len(glyphs)]
+        for i in range(width):
+            idx = int(i / (width - 1) * (n - 1)) if width > 1 else 0
+            idx = max(0, min(n - 1, idx))
+            val = series[idx]
+            row = int((val - y_min) / (y_max - y_min) * (height - 1))
+            row = max(0, min(height - 1, row))
+            grid[height - 1 - row][i] = g
+
+    lines = []
+    for r, row in enumerate(grid):
+        y_val = y_max - (r / (height - 1)) * (y_max - y_min)
+        lines.append(f"{y_val:8.3g} \u2502 " + "".join(row))
+    lines.append(" " * 9 + "\u2514" + "\u2500" * width)
+    legend = "  ".join(f"{glyphs[i % len(glyphs)]} {label}" for i, label in enumerate(series_dict))
+    lines.append(" " * 10 + legend)
+    lines.append(" " * 10 + f"t: 0 \u2192 {times[-1]:.3g}s   ({y_label})")
+    return lines

calc_terminal/registry.py

@@ -0,0 +1,337 @@
+"""
+CCT centralized command registry (spec section 14).
+
+Before this module, commands existed as: an entry in
+commands_data.py's COMMANDS list (name + one-line description only),
+a separate elif branch in app.py's dispatch chain, a separate entry
+in fallback_cli.py, and sometimes a separate tool entry in agent.py's
+TOOLS dict for AI-mode invocation — four places to touch per command,
+with no shared notion of category, aliases, icon, shortcut, required
+permissions, which AI modes can invoke it, or example usage. That's
+the exact "hardcoded across multiple files" problem section 14 names.
+
+This module gives every command ONE CommandSpec with all of those
+fields, and ONE registry to look them up by name, alias, category, or
+free-text search (for autocomplete). It does not yet replace app.py's
+dispatch chain (that's real surgery — see CHANGELOG_v0.6.3) but it IS
+the real source of truth for the palette/help text: `bootstrap()`
+below builds full CommandSpec entries for every command in
+commands_data.COMMANDS right now (migrating the existing data, not
+duplicating it) and layers on rich metadata for the commands that
+already have it elsewhere in the codebase (permissions.py's keys,
+agent.py's TOOLS, the SHORT_ALIASES map in app.py) so those fields are
+real, not guessed.
+"""
+
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+
+@dataclass
+class CommandSpec:
+    name: str                                  # canonical, e.g. "/atomsim"
+    description: str = ""
+    category: str = "general"
+    aliases: list = field(default_factory=list)
+    icon: str = "\u2022"                        # bullet by default
+    shortcut: Optional[str] = None              # e.g. "Ctrl+Shift+N"
+    permissions: list = field(default_factory=list)   # keys from permissions.PERMISSION_DEFS
+    ai_modes: list = field(default_factory=lambda: ["notebook"])  # which AI modes may invoke it
+    examples: list = field(default_factory=list)
+    autocomplete_keywords: list = field(default_factory=list)
+    handler: Optional[Callable] = None          # bound at registration time by app.py, if any
+    arg_style: Optional[str] = None             # None | "split_optional" — see ARG_STYLE_MAP below
+
+
+# name -> category, used to bootstrap from the existing flat COMMANDS list
+CATEGORY_MAP = {
+    "/help": "general", "/about": "general", "/shortcuts": "general", "/settings": "general",
+    "/history": "general", "/memory": "general", "/upload": "general", "/voice": "general",
+    "/permissions": "general", "/browser": "general", "/browse": "general", "/cat": "general",
+    "/calculator": "calculation", "/solve": "calculation", "/formulas": "calculation",
+    "/kinetics": "calculation", "/electrochemistry": "calculation", "/random": "calculation",
+    "/derive": "calculation",
+    "/atomsim": "simulation", "/orbitals": "simulation", "/orbitalgrid": "simulation",
+    "/bonding": "simulation", "/bloch": "simulation", "/sim3d": "simulation", "/gpu3d": "simulation", "/graph": "simulation",
+    "/ai": "ai", "/agent": "ai", "/ai-verify": "ai",
+    "/mode": "ai", "/notebook": "ai", "/build": "ai", "/plan": "ai",
+    "/game": "misc",
+}
+
+# hand-authored rich metadata for the commands that most need it right
+# now (the ones this session touched, plus the highest-traffic core
+# ones) — everything else in commands_data.COMMANDS still gets a real
+# CommandSpec via bootstrap(), just without hand-tuned icon/shortcut/
+# examples yet. That gap is intentional and tracked, not hidden.
+RICH_METADATA = {
+    "/atomsim": dict(
+        icon="\u269b", aliases=["/at"], permissions=["execute_python"],
+        ai_modes=["notebook", "agent", "build"],
+        examples=["/atomsim Fe", "/atomsim 26"],
+        autocomplete_keywords=["atom", "nucleus", "proton", "neutron", "bohr", "element"],
+    ),
+    "/orbitals": dict(
+        icon="\u2601", aliases=["/o"], permissions=["execute_python"],
+        ai_modes=["notebook", "agent", "build"],
+        examples=["/orbitals 2p", "/orbitals 3d"],
+        autocomplete_keywords=["orbital", "electron cloud", "probability density", "psi"],
+    ),
+    "/orbitalgrid": dict(
+        icon="\U0001f4ca", permissions=["execute_python"],
+        ai_modes=["notebook", "agent", "build"],
+        examples=["/orbitalgrid"],
+        autocomplete_keywords=["orbital grid", "hydrogen wave function", "reference chart"],
+    ),
+    "/bonding": dict(
+        icon="\U0001f9ea", permissions=["execute_python"],
+        ai_modes=["notebook", "agent", "build"],
+        examples=["/bonding furan", "/bonding water"],
+        autocomplete_keywords=["elf", "electron localization", "bonding", "molecule density"],
+    ),
+    "/bloch": dict(
+        icon="\u269b", permissions=["execute_python"],
+        ai_modes=["notebook", "agent", "build"],
+        examples=["/bloch", "/bloch 90 0", "/bloch 90 90"],
+        autocomplete_keywords=["bloch sphere", "qubit", "quantum state", "superposition"],
+    ),
+    "/solve": dict(
+        icon="\U0001f9ee", aliases=["/s"], permissions=["calculator"],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/solve"],
+        autocomplete_keywords=["solve", "formula", "algebra"],
+    ),
+    "/settings": dict(
+        icon="\u2699", permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/settings"],
+        autocomplete_keywords=["settings", "config", "preferences"],
+    ),
+    "/mode": dict(
+        icon="\U0001f501", permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/mode", "/mode build"],
+        autocomplete_keywords=["mode", "ai mode", "persona", "notebook", "agent", "build", "plan"],
+    ),
+    "/notebook": dict(
+        icon="\U0001f4d8", permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/notebook"],
+        autocomplete_keywords=["notebook mode", "chemistry", "physics", "math", "daily ai"],
+    ),
+    "/agent": dict(
+        icon="\u2699", permissions=["execute_python"],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/agent"],
+        autocomplete_keywords=["agent mode", "autonomous", "tool use", "simulate", "solve"],
+    ),
+    "/build": dict(
+        icon="\U0001f528", permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/build"],
+        autocomplete_keywords=["build mode", "code", "software", "debug", "architecture", "api"],
+    ),
+    "/plan": dict(
+        icon="\U0001f9ed", permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/plan"],
+        autocomplete_keywords=["plan mode", "roadmap", "brainstorm", "prototype", "study plan"],
+    ),
+    "/research": dict(
+        icon="\U0001f50d", permissions=[],
+        ai_modes=["notebook", "research", "agent", "build", "plan"],
+        examples=["/research"],
+        autocomplete_keywords=["research mode", "deep research", "web search", "literature"],
+    ),
+    "/debug": dict(
+        icon="\U0001f41b", permissions=[],
+        ai_modes=["notebook", "debugger", "agent", "build", "plan"],
+        examples=["/debug"],
+        autocomplete_keywords=["debugger mode", "debug", "fix", "error", "traceback"],
+    ),
+    "/install": dict(
+        icon="\U0001f4e6", permissions=["install_packages"],
+        ai_modes=["build"],
+        examples=["/install requests", "/install numpy", "/install torch"],
+        autocomplete_keywords=["install", "package", "pip", "npm", "dependency", "library"],
+    ),
+    "/packages": dict(
+        icon="\U0001f4e6", permissions=["install_packages"],
+        ai_modes=["build"],
+        examples=["/packages", "/packages forget numpy"],
+        autocomplete_keywords=["package manager", "dashboard", "remembered decisions", "forget"],
+    ),
+    "/pipeline": dict(
+        icon="\U0001f5fa", permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/pipeline build me a molecule viewer script"],
+        autocomplete_keywords=["pipeline", "planner", "research", "build", "verify", "stages"],
+    ),
+    "/orchestrate": dict(
+        icon="\U0001f465", permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/orchestrate build a chemistry dashboard"],
+        autocomplete_keywords=["orchestrator", "coordinator", "specialists", "team", "agents"],
+    ),
+    "/devices": dict(
+        icon="\U0001f4f1", permissions=["device_control"],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/devices", "/devices terminal run 'git status'"],
+        autocomplete_keywords=["devices", "device control", "terminal", "android", "desktop"],
+    ),
+    "/workspace": dict(
+        icon="\U0001f5c2", permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/workspace", "/workspace open C:\\projects\\app",
+                  "/workspace list", "/workspace detect"],
+        autocomplete_keywords=["workspace", "detect", "open folder", "recent",
+                               "pinned", "favorite", "rename", "search"],
+    ),
+    "/browser": dict(
+        icon="\U0001f30d", aliases=["/browse", "/cat"], permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/browser", "/cat", "/cat https://example.com", "/cat search cats on mars"],
+        autocomplete_keywords=["browser", "browse", "cat", "web", "surf", "terminal browser", "duckduckgo", "fomoji browser"],
+    ),
+    "/browse": dict(
+        icon="\U0001f30d", aliases=[], permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/browse https://example.com", "/browse search cats"],
+        autocomplete_keywords=["browse", "browser", "surf", "open url", "search"],
+    ),
+    "/cat": dict(
+        icon="\U0001f30d", aliases=[], permissions=[],
+        ai_modes=["notebook", "agent", "build", "plan"],
+        examples=["/cat", "/cat https://example.com", "/cat search cats on mars"],
+        autocomplete_keywords=["cat", "browser", "browse", "web", "chromium", "qt webengine"],
+    ),
+}
+
+
+# Canonical alias -> full-command table (spec section 14: one place,
+# not duplicated). This WAS a hardcoded dict living only in app.py's
+# App.SHORT_ALIASES class attribute; app.py now derives that attribute
+# from short_alias_map() below instead of declaring its own copy — the
+# mapping itself hasn't changed, only where it's defined.
+ALIAS_TABLE = {
+    "/h": "/help", "/c": "/calculator", "/s": "/solve", "/f": "/formulas",
+    "/k": "/kinetics", "/d": "/derive", "/g": "/graph", "/a": "/about",
+    "/gm": "/game", "/pg": "/game",
+    "/e": "/electrochemistry", "/r": "/random", "/x": "/exit",
+    "/o": "/orbitals", "/u": "/upload", "/v": "/voice", "/3": "/sim3d",
+    "/ag": "/agent", "/y": "/history", "/st": "/settings", "/sh": "/shortcuts",
+    "/at": "/atomsim", "/vf": "/verify", "/?": "/help", "/m": "/memory",
+    "/cp": "/codepad", "/tk": "/tokens", "/th": "/theme", "/ws": "/websearch",
+    "/rs": "/research", "/im": "/import", "/pt": "/pet", "/cc": "/copycode",
+    "/rx": "/react", "/ex": "/export", "/tu": "/tui", "/co": "/composer",
+    "/br": "/browser", "/bw": "/browse", "/cat": "/browser",
+}
+
+
+def short_alias_map():
+    """Return the alias -> canonical-command dict, exactly the shape
+    app.py's SHORT_ALIASES used to hardcode."""
+    return dict(ALIAS_TABLE)
+
+
+class CommandRegistry:
+    def __init__(self):
+        self._by_name = {}
+        self._by_alias = {}
+
+    def register(self, spec: CommandSpec):
+        self._by_name[spec.name] = spec
+        for alias in spec.aliases:
+            self._by_alias[alias] = spec.name
+
+    def get(self, name_or_alias):
+        if name_or_alias in self._by_name:
+            return self._by_name[name_or_alias]
+        canonical = self._by_alias.get(name_or_alias)
+        return self._by_name.get(canonical) if canonical else None
+
+    def all(self):
+        return list(self._by_name.values())
+
+    def by_category(self, category):
+        return [s for s in self._by_name.values() if s.category == category]
+
+    def categories(self):
+        seen = []
+        for s in self._by_name.values():
+            if s.category not in seen:
+                seen.append(s.category)
+        return seen
+
+    def usable_in_mode(self, ai_mode):
+        return [s for s in self._by_name.values() if ai_mode in s.ai_modes]
+
+    def search(self, query):
+        """Free-text match against name, description, and autocomplete
+        keywords — what a command-palette type-ahead would call."""
+        q = query.strip().lower()
+        if not q:
+            return self.all()
+        out = []
+        for s in self._by_name.values():
+            hay = " ".join([s.name, s.description] + s.autocomplete_keywords).lower()
+            if q in hay:
+                out.append(s)
+        return out
+
+
+# Commands matching this exact pattern in app.py's old elif chain:
+#   if low == "/X": self.cmd_X(); return
+#   if low.startswith("/X "): self.cmd_X(raw.split(" ", 1)[1].strip()); return
+# i.e. zero args or one stripped trailing-text arg, same method either
+# way. Verified against app.py line-by-line before being added here —
+# see CHANGELOG_v0.6.3_architecture.md.
+ARG_STYLE_MAP = {
+    "/memory": "split_optional",
+    "/model": "split_optional",
+    "/theme": "split_optional",
+    "/websearch": "split_optional",
+    "/research": "split_optional",
+    "/import": "split_optional",
+    "/react": "split_optional",
+    "/export": "split_optional",
+    "/workspace": "split_optional",
+    "/permissions": "split_optional",
+    "/browser": "split_optional",
+    "/browse": "split_optional",
+    "/cat": "split_optional",
+    "/vision": "split_optional",
+    "/vscode": "split_optional",
+}
+
+
+def bootstrap():
+    """Build a full CommandRegistry from commands_data.COMMANDS (the
+    existing real command list), layering in RICH_METADATA where it
+    exists. Real migration of real data, not a mock catalog."""
+    from . import commands_data
+    reverse_alias = {}
+    for alias, full in ALIAS_TABLE.items():
+        reverse_alias.setdefault(full, []).append(alias)
+
+    reg = CommandRegistry()
+    for name, desc in commands_data.COMMANDS:
+        extra = dict(RICH_METADATA.get(name, {}))
+        category = CATEGORY_MAP.get(name, "general")
+        canonical_aliases = reverse_alias.get(name, [])
+        hand_aliases = extra.pop("aliases", [])
+        merged_aliases = list(dict.fromkeys(canonical_aliases + hand_aliases))  # dedup, preserve order
+        arg_style = ARG_STYLE_MAP.get(name)
+        spec = CommandSpec(name=name, description=desc, category=category,
+                            aliases=merged_aliases, arg_style=arg_style, **extra)
+        reg.register(spec)
+    return reg
+
+
+_registry = None
+
+
+def get_registry():
+    global _registry
+    if _registry is None:
+        _registry = bootstrap()
+    return _registry