Deploy AIOS web (React glide grid + FastAPI slice)

RELEASES.json

@@ -1,5 +1,5 @@
 {
- "current": "7b711f1",
+ "current": "91ad73a",
  "releases": [
   {
    "version": "v25",

VERSION

@@ -1 +1 @@
-7b711f1
+91ad73a

api/ai_enrich.py

@@ -0,0 +1,520 @@
+"""ai_enrich.py -- the AI ENRICHMENT column (wave 34, owner ruling R13).
+
+R13: *"A field kind called AI enrichment: a prompt per row that populates text. Detailed
+configuration in the field's own config, including a token-usage limit."*
+
+WHERE THE HALVES LIVE, and why the line is drawn here rather than anywhere else:
+
+    core/user_tables.py   the CONTRACT and the STORAGE -- `UT_FIELD_TYPES`, `_clean_ai_enrich`,
+                          the per-cell provenance stratum, and the law about what an automatic
+                          run may overwrite. It owns the store document, so it owns the marks.
+    api/ai_enrich.py      THIS file: the PROMPT vocabulary, the run PLAN, and the token ceiling's
+                          own report. `core` may not import upward, so anything that needs to
+                          reach a vendor or an HTTP session lives here.
+
+Everything in this module is a PURE FUNCTION of data it is handed. That is deliberate: it is the
+half a gate can exercise without a network, a store, or a running server, which is what makes
+`api_ai_enrich` a real gate rather than a mount check.
+
+TOKEN ACCOUNTING, and the hole it is filling. `api/ai_review.py::decide` -- the product's only
+other LLM entry -- has no token accounting of ANY kind: `max_tokens: 300` per call, one 20 s
+timeout, no retry, and nothing anywhere counts what a run spent. R13 asks for a usage limit, so
+there was nothing to build on and the ledger starts here. The two measured community complaints
+about this feature elsewhere are both REPORTING gaps rather than capability gaps (a preview said
+15 credits and the run spent 360; a finished run gave no completion signal), which is why
+`ceiling_report` exists beside the ceiling itself.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+import requests
+
+#: A prompt names other columns the way a formula does, so a user who has written one already
+#: knows this syntax. ⚠ ONE parser, exported, because `user_tables.ai_enrich_input_hash` fingerprints
+#: the referenced cells and a second copy of this pattern would disagree with it the first time the
+#: token syntax gained a form ([[one-question-two-normalizers]]).
+_REF = re.compile(r'\{([a-zA-Z0-9_]{1,60})\}')
+
+#: What a cell can say about where its value came from. Mirrors
+#: `user_tables.AI_ENRICH_STATES` plus the two states that are DERIVED rather than stored:
+#: `stale` (the inputs moved since the value was written) and `empty` (nothing has run).
+#: ⛔ Re-exported rather than re-declared: the stored vocabulary has exactly one owner.
+CELL_STATES = ('empty', 'agent', 'human', 'stale', 'error')
+
+#: ⛔ THERE IS DELIBERATELY NO PROVIDER LIST IN THIS FILE. The product already has TWO opinions
+#: about provider order (`harness/analyst.PROVIDERS` says groq-first, `routes_query.
+#: QUERY_PROVIDER_ORDER` says cerebras-first) and `W34-T37` exists to reconcile them. Declaring a
+#: third here would make that ticket harder and this feature wrong in a new way, so the catalogue
+#: is BORROWED from `ai_review` (`PROVIDERS` + `ladder()` + the key names + the cheap-first order
+#: owner ruling R14 set). ⚠ The CALL is ours because the requirements differ: `ai_review` hardcodes
+#: `max_tokens: 300` and reads no `usage`, and R13 needs a per-column ceiling and a real ledger.
+#: One provider catalogue, two call shapes, and the reason is written down rather than inferred.
+
+#: The run's per-cell wall clock. Separate from `ai_review.TIMEOUT_SECONDS` because a review is
+#: one classification a person is waiting on and this is a loop over rows.
+TIMEOUT_SECONDS = float(os.environ.get('AIOS_AI_ENRICH_TIMEOUT') or 30)
+#: How many failing rows carry their error into the report before it is summarised. A report that
+#: lists 900 identical `429`s is a report nobody reads.
+MAX_REPORTED_ERRORS = 10
+#: Bound on what one row hands the model, mirroring `ai_review`'s own two caps: a table can hold a
+#: 32 KB JSON cell per row and no prompt needs it.
+MAX_CELL_CHARS = 400
+
+
+def prompt_refs(prompt):
+    """The column keys a prompt names, in first-appearance order, de-duplicated.
+
+    `"Summarise {name} for {segment}"` -> `['name', 'segment']`.
+    """
+    seen, out = set(), []
+    for key in _REF.findall(str(prompt or '')):
+        if key not in seen:
+            seen.add(key)
+            out.append(key)
+    return out
+
+
+def render_prompt(prompt, row, field_keys=()):
+    """`(text, unresolved)` -- the prompt with `{token}` replaced by this row's cells.
+
+    ⛔ AN UNKNOWN TOKEN IS REPORTED, NOT SILENTLY BLANKED. A prompt naming a column that does not
+    exist is a prompt that will quietly ask a different question on every row, and the resulting
+    text looks exactly like a correct answer. `unresolved` is what the caller shows the user;
+    R6's standing rule is the same sentence one layer up (a limit that cannot be removed must be
+    reported with its cause).
+
+    ⚠ A token naming a real column whose CELL is empty is NOT unresolved: an empty cell is data.
+    """
+    known = set(field_keys or ())
+    unresolved = []
+
+    def _sub(match):
+        key = match.group(1)
+        if known and key not in known:
+            unresolved.append(key)
+            return match.group(0)
+        return str((row or {}).get(key, ''))
+
+    return _REF.sub(_sub, str(prompt or '')), sorted(set(unresolved))
+
+
+def ceiling_report(spent, ceiling, rows_done, rows_total):
+    """R6's second sentence as DATA, or None while the run is still inside its budget.
+
+    `{subject, limit, spent, effect, cause, recommendation}` -- the same shape
+    `user_tables.limit_report` returns, so the client renders one vocabulary for every limit the
+    product enforces rather than a second one for this feature.
+
+    ⛔ `effect` is `stopped`, never `truncated`. A run that quietly stopped filling cells leaves a
+    column that looks complete and is not, which is the failure the whole reporting rule is
+    arranged against. The caller STOPS and says so.
+    """
+    if ceiling is None or spent < ceiling:
+        return None
+    left = max(0, int(rows_total or 0) - int(rows_done or 0))
+    rest = f'{left:,} rows' if left != 1 else '1 row'
+    return {
+        'subject': 'tokens',
+        'limit': int(ceiling),
+        'spent': int(spent),
+        'effect': 'stopped',
+        'cause': f'this run reached its token ceiling of {int(ceiling):,} after filling '
+                 f'{int(rows_done or 0):,} of {int(rows_total or 0):,} rows',
+        'recommendation': f'raise the column\'s token limit, shorten its prompt, or run the '
+                          f'remaining {rest} again. Nothing was truncated and no cell holds a '
+                          f'partial answer',
+    }
+
+
+def plan_rows(rows, col_id, config, marks, cost_of=None):
+    """Which rows an automatic run should fill, and why the others were left alone.
+
+    Returns `{'run': [row_id, ...], 'skipped': {reason: count}, 'estimate': int}`.
+
+    ⛔ THE SELECTION IS SEPARATE FROM THE RUN ON PURPOSE. It is pure, so a gate can prove the
+    never-overwrite-a-human-edit law without a vendor, and so the client can PREVIEW a run
+    honestly before it spends anything -- which is exactly the complaint R13 cites (a preview
+    that said 15 credits against a run that spent 360).
+
+    `cost_of(row)` estimates one row's tokens; absent, the column's own ceiling is used per row,
+    which is the pessimistic direction and the right one for a preview.
+    """
+    import core.user_tables as ut
+
+    cfg = config if isinstance(config, dict) else {}
+    prompt = str(cfg.get('prompt') or '')
+    policy = str(cfg.get('overwrite') or 'blank')
+    refs = prompt_refs(prompt)
+    per_row = int(cfg.get('maxTokens') or 0)
+    run, skipped, estimate = [], {}, 0
+    for row_id, row in (rows or {}).items():
+        row = row if isinstance(row, dict) else {}
+        mark = (marks or {}).get(str(row_id)) or {}
+        fresh = ut.ai_enrich_input_hash(prompt, row, refs)
+        has_value = bool(str(row.get(str(col_id)) or '').strip())
+        if ut.ai_enrich_may_write(mark, policy, fresh, has_value=has_value):
+            run.append(str(row_id))
+            estimate += int(cost_of(row)) if callable(cost_of) else per_row
+        else:
+            # The same predicate again, so the count a preview shows and the cells a run leaves
+            # alone can never be two different sets.
+            reason = ('human_edited' if ut.ai_enrich_human_authored(mark, has_value)
+                      else 'unchanged' if has_value else 'skipped')
+            skipped[reason] = skipped.get(reason, 0) + 1
+    return {'run': run, 'skipped': skipped, 'estimate': estimate}
+
+
+def cell_state(mark, config, row, col_id):
+    """What ONE cell should say about itself: one of `CELL_STATES`.
+
+    ⚠ `stale` and `empty` are computed here and never stored -- see the stratum's own note in
+    `core/user_tables.py`. A stored staleness flag needs a sweep to stay true, and a sweep nobody
+    runs is a flag shipped without its writer.
+    """
+    import core.user_tables as ut
+
+    mark = mark if isinstance(mark, dict) else {}
+    has_value = bool(str((row or {}).get(str(col_id)) or '').strip())
+    if str(mark.get('state') or '') == 'error':
+        return 'error'
+    # ⛔ THE SAME PREDICATE THE RUNNER OBEYS, called rather than restated. A cell this reports as
+    # the human's while `ai_enrich_may_write` would overwrite it is the worst of both answers.
+    if ut.ai_enrich_human_authored(mark, has_value):
+        return 'human'
+    if str(mark.get('state') or '') != 'agent':
+        return 'empty'
+    cfg = config if isinstance(config, dict) else {}
+    prompt = str(cfg.get('prompt') or '')
+    fresh = ut.ai_enrich_input_hash(prompt, row or {}, prompt_refs(prompt))
+    return 'stale' if ut.ai_enrich_is_stale(mark, fresh) else 'agent'
+
+
+# ══════════════════════════════════════════════════════════════════════ THE RUN
+# ���⛔ THE LEDGER IS THE POINT OF THIS HALF. `ai_review.decide` (the product's only other LLM entry)
+# counts nothing: it sends `max_tokens: 300` and never reads `usage` off the response, so no run in
+# this product has ever been able to say what it cost. R13 asks for a token-usage limit, so the
+# accounting starts here, and every leg below reads `usage` even where it is not needed, because a
+# ledger with one blind provider is not a ledger.
+
+
+def _usage_tokens(body):
+    """Total tokens for one call, from whichever shape the provider answered in.
+
+    ⚠ RETURNS None WHEN THE PROVIDER DID NOT SAY, and the caller treats that as a real unknown
+    rather than as zero. A ledger that silently books an unmeasured call at 0 reports a cheaper
+    run than happened, which is exactly the cost-surprise complaint R13 cites.
+    """
+    usage = (body or {}).get('usage')
+    if not isinstance(usage, dict):
+        return None
+    for key in ('total_tokens', 'totalTokens'):
+        got = usage.get(key)
+        if isinstance(got, int) and not isinstance(got, bool):
+            return got
+    ins = usage.get('prompt_tokens', usage.get('input_tokens'))
+    outs = usage.get('completion_tokens', usage.get('output_tokens'))
+    if isinstance(ins, int) and isinstance(outs, int):
+        return ins + outs
+    return None
+
+
+#: R6's subject: the em dash (U+2014) and the en dash (U+2013), as a regex character class.
+#: ⛔ BUILT FROM CODE POINTS, NOT TYPED, AND THIS IS NOT COSMETIC. `web_prose` reads a Python
+#: string's VALUE off the AST, so a class written `'[<em><en>]'` is reported as two findings in
+#: the one function whose entire job is to REMOVE those characters. That is a false positive, and
+#: the wrong fix would be to silence the gate or to weaken the pattern. `chr()` keeps the value
+#: byte-identical while putting no dash in a literal, so the gate sees what it should see and the
+#: normalizer keeps working. ⚠ Lane D hit the same wall in `routes_query` (note D-13).
+_DASH = '[' + chr(0x2014) + chr(0x2013) + ']'
+
+
+def no_dashes(text):
+    """R6 applied to MODEL-AUTHORED text, before it is stored.
+
+    ⛔⛔ A PROMPT INSTRUCTION DOES NOT ENFORCE THIS, AND THE MEASUREMENT IS LANE D'S, NOT A GUESS
+    (mailbox note D-4, 2026-08-16): a system prompt ending *"Never use an em dash or an en dash"*
+    was answered on the very next live turn with *"Which view type would you like-grid, chart,
+    list, or another?"* carrying U+2014 (cerebras). `web_prose` scans SOURCE, so it is
+    structurally blind to a dash that arrives at runtime.
+    ⚠ AND THIS COLUMN IS THE WORST CASE IN THE WAVE, which is why D routed the note here: chat
+    prose is read once, but an enrichment value is WRITTEN INTO A CELL, then re-read and
+    re-rendered forever. Normalising after the write would never reach the rows already stored.
+
+    ⚠ A DIGIT RANGE IS A DIFFERENT SENTENCE and gets the first rule: "10-20" means "10 to 20", and
+    rewriting it as "10, 20" states two numbers where the model stated a span. That is a wrong
+    value, not a punctuation fix.
+
+    ⛔⛔ THIS IS THE SECOND IMPLEMENTATION IN THE PRODUCT and that is a known cost, taken
+    deliberately rather than by drift. The first is `routes_query._no_dashes` (lane D's, shipped
+    first). Importing it would point a LIBRARY module at a ROUTE module, which is backwards, and
+    lane D's file is not in this lane's fence to move it. So the two are held in step by a PARITY
+    CHECK instead of by hope: `verify_ai_enrich` section 10 imports D's function and asserts both
+    agree over a corpus including every shape either docstring names. One shared home is owed and
+    is booked as a PENDING line, not left implicit ([[one-question-two-normalizers]]).
+    """
+    text = str(text or '')
+    text = re.sub(rf'(?<=\d)\s*{_DASH}\s*(?=\d)', ' to ', text)
+    text = re.sub(rf'\s*{_DASH}\s*(?=[,.;:!?])', '', text)     # abutting punctuation: it just goes
+    text = re.sub(rf'(?<=[,;:])\s*{_DASH}\s*', ' ', text)      # already punctuated: one space
+    return re.sub(rf'\s*{_DASH}\s*', ', ', text)
+
+
+#: What the model is told about its job. It fills ONE cell, so anything conversational it adds is
+#: a defect in the column rather than a nicety. `UNKNOWN` is the honest out: a row the data cannot
+#: answer is recorded as an error against that row, never as an invented value.
+#: ⚠ The dash sentence is here for the same reason lane D kept theirs: it costs nothing and it
+#: reduces how often `no_dashes` has to act. It is NOT the enforcement; `no_dashes` is.
+_SYSTEM = ('You fill in ONE cell of a spreadsheet. Answer with the value only: no preamble, no '
+           'quotes, no markdown, no explanation. Never use an em dash or an en dash; use a comma, '
+           'a colon or a full stop. If the information given does not let you answer, reply with '
+           'exactly: UNKNOWN')
+
+
+def _ask(provider, model, prompt, max_tokens, timeout):
+    """One cell's answer. `(text, tokens_or_None, problem)`; a truthy `problem` means no text.
+
+    ⚠ Both request shapes are `ai_review`'s, changed in exactly two ways: they carry the COLUMN's
+    ceiling instead of a hardcoded 300, and they read `usage` back.
+    """
+    key = (os.environ.get(provider['env']) or '').strip()
+    if not key:
+        return '', None, f"{provider['name']} has no key on this deployment"
+    try:
+        if provider['shape'] == 'anthropic':
+            r = requests.post(
+                provider['url'], timeout=timeout,
+                headers={'x-api-key': key, 'anthropic-version': '2023-06-01',
+                         'content-type': 'application/json'},
+                json={'model': model, 'max_tokens': max_tokens, 'system': _SYSTEM,
+                      'messages': [{'role': 'user', 'content': prompt}]})
+            if r.status_code >= 400:
+                return '', None, f"{provider['name']} answered {r.status_code}"
+            body = r.json()
+            # ⛔ stop_reason FIRST. A safety refusal is a 200 with an EMPTY content list, so
+            # reading content[0] before this turns a refusal into an IndexError inside the loop.
+            if body.get('stop_reason') == 'refusal':
+                return '', _usage_tokens(body), f"{provider['name']} declined this row"
+            parts = [b.get('text') or '' for b in (body.get('content') or [])
+                     if isinstance(b, dict) and b.get('type') == 'text']
+            return ''.join(parts).strip(), _usage_tokens(body), ''
+        r = requests.post(
+            provider['url'], timeout=timeout,
+            headers={'Authorization': f"Bearer {key}", 'Content-Type': 'application/json'},
+            json={'model': model, 'max_tokens': max_tokens, 'temperature': 0,
+                  'messages': [{'role': 'system', 'content': _SYSTEM},
+                               {'role': 'user', 'content': prompt}]})
+        if r.status_code >= 400:
+            return '', None, f"{provider['name']} answered {r.status_code}"
+        body = r.json()
+        choices = body.get('choices') or []
+        if not choices:
+            return '', _usage_tokens(body), f"{provider['name']} returned no choices"
+        text = ((choices[0] or {}).get('message') or {}).get('content') or ''
+        return str(text).strip(), _usage_tokens(body), ''
+    except Exception as exc:                                          # noqa: BLE001
+        return '', None, f"{provider['name']} failed: {type(exc).__name__}"
+
+
+def on_change_fields(defn, changed_keys):
+    """Which `ai_enrich` columns in this table want a run because one of their inputs moved.
+
+    A column qualifies when its trigger is `on_change` AND its prompt names at least one of the
+    columns that just changed. ⛔ A column that names NOTHING (a prompt with no `{token}`) never
+    fires on change, whatever its trigger says: it would re-ask the same question of the same row
+    forever, once per unrelated edit, and bill for every one.
+
+    ⚠ PURE, AND HANDED THE DEFINITION IT SHOULD USE. `automation_engine.grid_hook` calls
+    `all_definitions(st)` once PER EVENT, which turns a 20,000-row import into 20,000 whole
+    document reads (`D-134`); this function reads no store at all, so the caller can do one read
+    for a whole batch. Rebuilding that shape here was the one thing T54's ticket said not to do.
+    """
+    import core.user_tables as ut
+
+    touched = {str(k) for k in (changed_keys or ())}
+    if not touched:
+        return []
+    out = []
+    for field in ut.ai_enrich_fields(defn):
+        cfg = field.get('aiEnrich') or {}
+        if (cfg.get('trigger') or {}).get('mode') != 'on_change':
+            continue
+        refs = set(prompt_refs(cfg.get('prompt')))
+        # ⚠ A column never fires on a change to ITSELF. Its own value moving is either the run
+        # that just wrote it or a person typing over it, and both would loop.
+        refs.discard(str(field.get('key') or ''))
+        if refs & touched:
+            out.append(field)
+    return out
+
+
+def scheduled_fields(defn):
+    """`[(field, cron)]` for every enrichment column that runs on a cadence.
+
+    ⛔ IT DOES NOT PARSE THE CRON AND MUST NOT. `core.user_tables` stores that string opaque
+    precisely so the cadence vocabulary has ONE owner, and the owner is the scheduler
+    (`automation_engine`), not the field layer. A second parser here would be a door that starts
+    refusing a cadence the other one accepts, which is exactly the divergence the whole field
+    contract keeps paying for ([[one-question-two-normalizers]]).
+
+    ⚠ SO THIS IS HALF A FEATURE ON PURPOSE, and the other half is a cross-fence ask: something has
+    to TICK. Nothing in lane F's fence runs on a timer.
+    """
+    import core.user_tables as ut
+
+    out = []
+    for field in ut.ai_enrich_fields(defn):
+        trigger = ((field.get('aiEnrich') or {}).get('trigger') or {})
+        if trigger.get('mode') == 'schedule' and str(trigger.get('cron') or '').strip():
+            out.append((field, str(trigger['cron'])))
+    return out
+
+
+def run_field(table_key, col_id, *, st, rows=None, manual=False, policy=None, budget=None,
+              timeout=None, ask=None):
+    """Fill one `ai_enrich` column over the rows an automatic run is allowed to touch.
+
+    Returns a REPORT and never raises for a vendor problem:
+        `{planned, filled, failed, skipped{reason: count}, tokens, provider, model,
+          limit: <ceiling_report or None>, errors[], problem}`
+
+    ⛔ THE RUN BUDGET IS DERIVED FROM THE COLUMN'S OWN CEILING, and the arithmetic is the point:
+    `budget = maxTokens * planned`. `maxTokens` bounds the OUTPUT of one call while spend counts
+    INPUT tokens too, so a real run crosses this before it finishes every row. That is intended:
+    R13 asked for a token-usage limit and a ceiling that can never bite is not one. A caller may
+    pass a TIGHTER `budget`; nothing may pass a looser one.
+
+    ⛔ TWO STORE WRITES FOR THE WHOLE RUN, not two per row: one `patch_many_cells` for the values
+    and one `stamp_ai_enrich` for the marks. Each is a read-modify-write of the whole tenant
+    document, which is why `patch_cells` in a loop was never an option (D-134's shape).
+
+    ⚠ `ask` is injectable so a gate can exercise the ledger, the ceiling and every failure path
+    with no network and no vendor bill. It defaults to the real `_ask`.
+    """
+    import ai_review
+    import core.user_tables as ut
+
+    defn = ut.get(table_key, st=st) or {}
+    field = next((f for f in ut.ai_enrich_fields(defn) if f.get('key') == str(col_id)), None)
+    if field is None:
+        return {'problem': f'{col_id!r} is not an AI enrichment column on this database',
+                'planned': 0, 'filled': 0, 'failed': 0, 'skipped': {}, 'tokens': 0,
+                'errors': [], 'limit': None, 'provider': '', 'model': ''}
+    cfg = field.get('aiEnrich') or {}
+    # ⭐ THE BULK MENU'S TWO CHOICES ARE THIS ONE OVERRIDE (`W34-T54`): "Rows never filled" is
+    # `blank` and "All rows" is `always`. ⛔ It overrides the column's SAVED POLICY for one run and
+    # NOTHING ELSE: `ai_enrich_may_write` still refuses a human-edited cell under every value, so
+    # "All rows" means every row the AGENT wrote, which is exactly what the menu label says.
+    # ⚠ An unrecognised value falls back to the column's own setting rather than to a default: a
+    # typo'd override must not quietly widen what a run touches.
+    if policy in ut.AI_ENRICH_OVERWRITE:
+        cfg = {**cfg, 'overwrite': policy}
+    all_rows = defn.get('rows') or {}
+    marks = ut.ai_enrich_marks(table_key, col_id, st=st)
+    # ⛔⛔ `rows` NARROWS; `manual` DECIDES WHETHER THE POLICY APPLIES. They are two questions and
+    # an early draft of this function conflated them, which would have let an ON-CHANGE fire (an
+    # automatic act, scoped to one row) overwrite a cell a person had typed into. That is the one
+    # law this whole feature is arranged around, broken by a parameter name.
+    #   rows=None                -> the automatic plan over every row
+    #   rows=[...], manual=False -> the automatic plan, INTERSECTED with those rows (on_change)
+    #   rows=[...], manual=True  -> exactly those rows, policy skipped
+    # `manual` is skippable because a person clicking "run this cell" has asked, in front of the
+    # value being replaced; refusing them would be the product overruling an explicit act with a
+    # rule written for an implicit one. `ai_enrich_may_write`'s own docstring says exactly this.
+    # ⚠ A named row is always INTERSECTED with the table's own row set, so a stale caller cannot
+    # name a record that has since been deleted.
+    named = None if rows is None else [str(r) for r in rows if str(r) in all_rows]
+    if named is not None and manual:
+        plan = {'run': named, 'skipped': {},
+                'estimate': int(cfg.get('maxTokens') or 0) * len(named)}
+    else:
+        plan = plan_rows(all_rows, col_id, cfg, marks)
+        if named is not None:
+            keep = set(named)
+            dropped = [r for r in plan['run'] if r not in keep]
+            plan = {**plan, 'run': [r for r in plan['run'] if r in keep]}
+            if dropped:
+                plan['skipped'] = {**plan['skipped'], 'not_in_this_run': len(dropped)}
+    rows = all_rows
+    keys = [f.get('key') for f in (defn.get('fields') or []) if f.get('key')]
+    report = {'planned': len(plan['run']), 'filled': 0, 'failed': 0,
+              'skipped': dict(plan['skipped']), 'tokens': 0, 'errors': [], 'limit': None,
+              'provider': '', 'model': '', 'problem': ''}
+    if not plan['run']:
+        return report
+
+    caller = ask or _ask
+    ceiling = int(cfg.get('maxTokens') or 0) * len(plan['run'])
+    if isinstance(budget, int) and not isinstance(budget, bool):
+        ceiling = min(ceiling, max(0, budget))
+    live = ai_review.ladder()
+    if not live and ask is None:
+        # ⛔ FAIL CLOSED AND SAY SO. A run that quietly filled nothing looks identical to a run
+        # with nothing to do; `planned` above is the number that distinguishes them.
+        report['problem'] = 'no AI provider is configured on this deployment'
+        return report
+    provider = (live or [{'name': 'injected', 'model': 'injected', 'env': '',
+                          'shape': 'openai', 'url': ''}])[0]
+    model = str(cfg.get('model') or provider['model'])
+    report['provider'], report['model'] = provider['name'], model
+    tmo = float(timeout or TIMEOUT_SECONDS)
+
+    values, stamps = {}, {}
+    for row_id in plan['run']:
+        if ceiling and report['tokens'] >= ceiling:
+            # ⛔ STOP AND REPORT (R6's second sentence). Cells already written STAY written and
+            # carry honest marks; nothing is truncated and no cell holds half an answer.
+            report['limit'] = ceiling_report(report['tokens'], ceiling,
+                                             report['filled'], report['planned'])
+            left = report['planned'] - report['filled'] - report['failed']
+            if left > 0:
+                report['skipped']['over_budget'] = left
+            break
+        row = rows.get(row_id) or {}
+        text, unresolved = render_prompt(cfg.get('prompt'), row, keys)
+        if unresolved:
+            # Reported per row rather than refused up front: the prompt is valid for the column,
+            # and naming the missing token is what lets somebody fix it.
+            why = ('the prompt names ' + ', '.join(unresolved)
+                   + ', which is not a column on this database')
+            report['failed'] += 1
+            stamps[row_id] = {'state': 'error', 'error': why}
+            if len(report['errors']) < MAX_REPORTED_ERRORS:
+                report['errors'].append({'row': row_id, 'error': why})
+            continue
+        answer, tokens, problem = caller(provider, model, text[:MAX_CELL_CHARS * 8],
+                                         int(cfg.get('maxTokens') or 300), tmo)
+        if isinstance(tokens, int) and not isinstance(tokens, bool):
+            report['tokens'] += tokens
+        if problem or not answer or answer.strip().upper() == 'UNKNOWN':
+            # ⛔ THE CELL IS LEFT ALONE. An errored row keeps whatever it held; only the MARK
+            # changes, so a failed run never destroys a value it could not replace.
+            why = problem or ('the model had nothing to answer from' if not answer
+                              else 'the model answered UNKNOWN for this row')
+            report['failed'] += 1
+            stamps[row_id] = {'state': 'error', 'error': why, 'model': model}
+            if len(report['errors']) < MAX_REPORTED_ERRORS:
+                report['errors'].append({'row': row_id, 'error': why})
+            continue
+        # ⛔ NORMALISED BEFORE THE WRITE, NOT AFTER (note D-6). This is the ONE line where model
+        # prose becomes stored product data; a cell fixed after the fact leaves every row already
+        # written carrying the dash, and `web_prose` can never see it because it scans source.
+        values[row_id] = no_dashes(answer)[:MAX_CELL_CHARS]
+        stamps[row_id] = {'state': 'agent', 'model': model,
+                          'hash': ut.ai_enrich_input_hash(cfg.get('prompt'), row,
+                                                          prompt_refs(cfg.get('prompt'))),
+                          'tokens': tokens if isinstance(tokens, int) else 0}
+        report['filled'] += 1
+
+    if values:
+        ut.patch_many_cells(table_key, {r: {str(col_id): v} for r, v in values.items()}, st=st)
+    if stamps:
+        ut.stamp_ai_enrich(table_key, col_id, stamps, st=st)
+    # ⚠ The ceiling is re-asked AFTER the loop too: a run whose LAST row crossed the budget spent
+    # over it without re-entering the guard, and staying silent there would under-report the one
+    # run most likely to surprise somebody.
+    if report['limit'] is None and ceiling and report['tokens'] >= ceiling:
+        report['limit'] = ceiling_report(report['tokens'], ceiling,
+                                         report['filled'], report['planned'])
+    return report

api/routes_nav.py

@@ -248,6 +248,191 @@ def _read_recents(runtime, uname, allowed):
     return out[:_MAX_RECENTS]
 
 
+# ── W34-T10 (ruling R1, contract C1): the "mark important" counts, per database ──────────────
+
+#: A wall-clock ceiling on the WHOLE counting block, checked between databases.
+#:
+#: ⛔ IT IS A COLD-START BOUND, NOT A PERFORMANCE BUDGET, and the measurement is the reason it
+#: exists at all. Every database's views live in its OWN store bucket (`<key>_table_workspace`),
+#: never in the `user_tables` document this route already holds — so this block is `N` reads on a
+#: route D-175 spent a wave reducing to one. What makes it affordable is that those buckets are
+#: TINY. Measured on tenant #0, 2026-08-16: twelve of them cost **6.2 ms WARM in total**, and the
+#: largest (`customer_data`) is 45,035 bytes against the 28.6 MB `user_tables` document; ten of the
+#: twelve are under 1 KB. COLD is the other half of the truth: the same twelve cost 7,331 ms of
+#: first fetch. So this budget bounds the FIRST request after a container starts, and a database it
+#: does not reach is reported through `degraded` rather than quietly carrying no number.
+#:
+#: ⚠ THE NUMBER IS CHOSEN AGAINST THE CLIENT'S DEADLINE, NOT AGAINST A FEELING. `nav.ts`'s
+#: `NAV_TIMEOUT_MS` is 20 s and a cold `/nav` already spends most of that on the `user_tables`
+#: download; letting this block run unbounded (measured: 7,331 ms for twelve cold buckets) would
+#: convert a slow success into a manufactured failure, which is the exact mistake that deadline's
+#: own comment warns about. 2.5 s is a bound the route can afford to lose.
+_IMPORTANT_BUDGET_S = 2.5
+
+#: Suffix `core.view_templates.workspace_key` appends. Stripping it is how a page key becomes the
+#: TOPIC key the cohort bucket is named from — `customer_data` -> `customer_table_workspace` ->
+#: `customer` -> `customer_cohorts`. Derived rather than re-listed on purpose: `_WS_KEYS` is
+#: already the one place `customer_data`/`product_data` are mapped to their topic, and a second
+#: copy here would be free to drift from it ([[one-question-two-normalizers]]).
+_WS_SUFFIX = "_table_workspace"
+
+
+def _visible_views(doc, uname, is_admin, granted_ids):
+    """Every view on ONE database that THIS caller can see, from an already-read workspace doc.
+
+    ⛔ PER-CALLER, NOT TENANT-WIDE, and this is the half a server-side count is most likely to get
+    wrong. `<key>_table_workspace` is `{username: {views, fields, overlays}, '__shared__': {...}}`
+    — one home per view, never both — so "how many views are marked important here" has a
+    DIFFERENT answer for every account. Measured on tenant #0: `leadership` has one marked view and
+    `admin` has none, on the same database. A tenant-wide count would put a number in the owner's
+    rail that no view sidebar they can open would ever add up to.
+
+    ⚠ `table_store._may_see` is imported rather than re-expressed. It is private, and reaching for
+    it is still the right call: the alternative is `TableOps.shared_views`, which re-reads the whole
+    bucket per database (the N whole reads this block exists to avoid), and the only other option is
+    a second copy of a permission predicate. A wrong copy of `_may_see` widens what a user is told
+    exists; a private import cannot.
+    """
+    import core.table_store as table_store
+    out = {}
+    for vid, view in ((doc.get(uname) or {}).get("views") or {}).items():
+        if isinstance(view, dict):
+            out[str(vid)] = view
+    for vid, view in ((doc.get(table_store.SHARED_KEY) or {}).get("views") or {}).items():
+        if isinstance(view, dict) and table_store._may_see(view, uname, is_admin):
+            out.setdefault(str(vid), view)
+    # The wave-21 named-user grants. The ids come from ONE tenant-wide bucket read once for the
+    # whole request; the RECORD is already in hand, in whichever stratum its owner keeps it.
+    if granted_ids:
+        for stratum, blob in doc.items():
+            if stratum == uname or not isinstance(blob, dict):
+                continue
+            for vid, view in (blob.get("views") or {}).items():
+                if str(vid) in granted_ids and isinstance(view, dict):
+                    out.setdefault(str(vid), view)
+    return out
+
+
+def _view_record_count(cfg, cohorts):
+    """How many RECORDS this view resolves to, or None when that cannot be answered for free.
+
+    ⛔ `None` IS AN ANSWER AND IT IS THE IMPORTANT ONE. Two of the three shapes below are exact
+    because the view CARRIES its row set; the third — an ordinary filtered view — can only be
+    counted by running its filters over the records, and the records are the one thing this route
+    must never read (`D-175`/`D-185`: `/nav` is a rows-free projection, and reaching for `rows`
+    here raises by that projection's own contract). So a filtered view is reported as UNCOUNTED and
+    the database's `partial` flag says so, which is the whole of R6's second sentence applied to a
+    badge: a limit that cannot be removed is REPORTED with its cause, never papered over with a
+    number that is short by an unknown amount.
+
+    ⚠ THIS IS ALSO WHY THE SERVER DOES NOT SIMPLY MIRROR THE CLIENT. `CustomerGrid::alertCounts`
+    counts a filtered view fine and gives up on a SERVER-WINDOWED one (`D-205`'s `Important 0+`);
+    this end is the exact inverse — it has no rows at all and no window either. The two are honest
+    about different halves, which is why `partial` had to be on the wire rather than derived.
+    """
+    if not isinstance(cfg, dict):
+        return None
+    # A cohort-locked view IS its cohort: the lock and the id are the same fact (`grid_events`
+    # re-stamps it on every write), and a cohort's membership is a stored pid LIST, not a query.
+    lock = str(cfg.get("cohortLock") or "").strip()
+    if lock:
+        n = cohorts.get(lock)
+        return int(n) if isinstance(n, int) else None
+    # A curated row set carries its own count.
+    pids = cfg.get("memberPids")
+    if isinstance(pids, list) and pids:
+        return len(pids)
+    return None
+
+
+def _important_counts(session, keys):
+    """`({key: {marked, counted, partial}}, unread)` for the databases in `keys`.
+
+    `marked` = views this caller can see on that database whose `config.important is True`.
+    `counted` = the SUM of those views' record counts — a record matching two marked views
+                contributes twice, because that is what the badge the owner is moving has always
+                meant (`CustomerGrid::importantTotal`: *"a sum of per-view counts, which is what
+                was asked"*), and a distinct-record total would disagree with the per-view numbers
+                a user can read off the sidebar and add up themselves.
+    `partial` = at least one marked view could not be counted.
+
+    `unread` is the set of keys whose bucket did not answer — a store blip or the budget above.
+    They are reported through `degraded`, never as a confident zero.
+    """
+    import core.shares as shares
+    import core.view_templates as view_templates
+    import modules.cohort as cohort_mod
+
+    uname, is_admin = session.uname, session.admin
+    out, unread = {}, set()
+    try:
+        # ⚠ THE ROLE FILTER IS NOT BELT-AND-BRACES. `shared_with` answers "is there an entry naming
+        # me", and `grid_events._granted_views` — the reader whose answer this badge has to agree
+        # with — then requires `role_for(...) in ('view','edit')`. Dropping that second test would
+        # count a view the sidebar does not list, i.e. a badge one higher than anything a person can
+        # add up. One tenant-wide bucket, read once and cached, so it costs a dict lookup per id.
+        granted = {str(v) for v in
+                   ((shares.shared_with(uname, kind="view", st=session.runtime) or {})
+                    .get("view") or [])
+                   if shares.role_for("view", str(v), uname,
+                                      st=session.runtime) in ("view", "edit")}
+    except Exception:
+        granted = set()          # no grants is the fail-closed answer: a narrower count, never wider
+    cohort_cache = {}
+    started = time.perf_counter()
+    for key in keys:
+        if key in out or key in unread:
+            continue             # the caller's order may repeat a key; a repeat must not respend
+        ws_key = view_templates.workspace_key(key)
+        if not ws_key:
+            continue             # not a table at all (a module surface, a folder head)
+        if time.perf_counter() - started > _IMPORTANT_BUDGET_S:
+            unread.add(key)
+            continue
+        try:
+            # ⛔ PROJECTED, and the two dropped keys are the whole reason this is affordable.
+            # `overlays` is per-record field values and `fields` is the schema stratum; neither
+            # says anything about a view. On `customer_data` they are most of the bucket.
+            doc = session.runtime.get_projection(ws_key, drop=("overlays", "fields")) or {}
+        except Exception:
+            unread.add(key)
+            continue
+        marked = [v for v in _visible_views(doc, uname, is_admin, granted).values()
+                  if ((v.get("config") or {}).get("important") is True)]
+        if not marked:
+            out[key] = {"marked": 0, "counted": 0, "partial": False}
+            continue
+        scope = ws_key[:-len(_WS_SUFFIX)] if ws_key.endswith(_WS_SUFFIX) else key
+        if scope not in cohort_cache:
+            try:
+                # ⚠ Read through `session.runtime`, NOT `modules.cohort`'s own module-level
+                # helpers: those call `core.store` directly, so they carry no tenant namespace.
+                # The MODULE is asked for the bucket NAME (it owns that rule) and this route does
+                # the reading, which is the only tenant-correct combination.
+                bucket = session.runtime.get(cohort_mod.key_for(scope)) or {}
+                # ⛔ THIS CALLER'S OWN COHORTS ONLY, and the consequence is deliberate: a SHARED
+                # view locked to a cohort somebody else owns finds no id here, so it is reported
+                # UNCOUNTED (`partial`) rather than counted from a stratum this session cannot
+                # see. Widening the read to every user's cohorts would make the badge disclose the
+                # SIZE of another person's private list, which is a leak wearing a bug fix.
+                mine = bucket.get(uname) or {}
+                cohort_cache[scope] = {
+                    str(cid): len(c.get("members") or [])
+                    for cid, c in mine.items() if isinstance(c, dict)
+                }
+            except Exception:
+                cohort_cache[scope] = {}
+        counted, partial = 0, False
+        for view in marked:
+            n = _view_record_count(view.get("config"), cohort_cache[scope])
+            if n is None:
+                partial = True
+            else:
+                counted += n
+        out[key] = {"marked": len(marked), "counted": counted, "partial": partial}
+    return out, unread
+
+
 @router.get("/nav")
 def nav(session: Session = Depends(require_session)):
     """`{pages: [{key,label,source?,chrome}], landing}`.
@@ -336,7 +521,7 @@ def nav(session: Session = Depends(require_session)):
             # empty rather than leaving 200-[] ambiguous.
             return {"pages": [], "landing": None, "empty": "no_databases"}
         raise err(403, "no_surfaces",
-                  "your account has no dashboards assigned — ask an administrator")
+                  "your account has no dashboards assigned. Ask an administrator.")
     # WAVE 19 (R8 / C1): the tenant's name + icon overrides, merged LAST — after the registry
     # rows, after the tenant module filter, after the user tables. Merged HERE rather than
     # applied by the client for one reason: `label` is what every reader of this payload shows,
@@ -350,6 +535,38 @@ def nav(session: Session = Depends(require_session)):
     # leak with no symptom until two tenants rename the same registry key. Copy the rows before
     # merging on the day that invariant changes.
     meta = _read_nav_meta(session.runtime)
+    # ⭐⭐ W34-T10 (ruling R1, contract C1) — THE MARK-IMPORTANT NUMBERS, COMPUTED ONCE.
+    #
+    # ⛔ COMPUTED HERE RATHER THAN INSIDE THE LOOP BELOW, AND THAT PLACEMENT IS THE SAFETY
+    # ARGUMENT, not tidiness. The `for p in pages:` loop sits OUTSIDE the try/except that wraps
+    # the `all_defs()` read, so anything raising inside it takes the whole nav down for every
+    # user — a 500 where the store-blip path is careful to answer 200 with `degraded`. One call,
+    # one guard, and the loop stays a dict lookup.
+    #
+    # ⛔⛔ AND THE ORDER IS LOAD-BEARING, WHICH IS THE ONE THING THE FIRST DRAFT GOT WRONG.
+    # A budget spent in whatever order the pages happen to arrive is a lottery: measured cold on
+    # tenant #0, the block spent all 1.5 s of its first draft on ten EMPTY Odoo buckets and was cut
+    # off two rows before `customer_data`, which holds the only marked view in the tenant. The
+    # feature would have shipped, been correct, and shown nothing on a cold container. Counting in
+    # the user's own RECENTS order first fixes that with a fact this route already holds: a mark
+    # lives on a database somebody works in, and `nav_recents` is exactly the list of those,
+    # newest first.
+    _page_keys = {str(p.get("key", "")) for p in pages}
+    recents = _read_recents(session.runtime, session.uname, _page_keys)
+    _recent_first = [r["key"] for r in recents]
+    _seen_first = set(_recent_first)
+    _recent_first += [k for k in (str(p.get("key", "")) for p in pages)
+                      if k not in _seen_first]
+    _important, _imp_unread = {}, set()
+    try:
+        _important, _imp_unread = _important_counts(session, _recent_first)
+    except Exception:
+        _imp_unread = set(_page_keys)
+    if _imp_unread:
+        # The SAME honest-absence channel W31-T11 built for the `ut_*` merge. A database whose
+        # count could not be read must not be indistinguishable from one with nothing marked:
+        # both would render as no badge, and only one of them is true.
+        _degraded.append("important")
     # Wave 21 (C3): the definitions, once — `manage`/`canDelete` below answer from `createdBy`.
     # WAVE 27 (C9): `locked` answers from `recordMode`, off the same one read.
     # ⭐ W31-T10: that read is now the SAME one the merge above did — it used to be a second,
@@ -398,6 +615,13 @@ def nav(session: Session = Depends(require_session)):
                 p["locked"] = True
         elif session.admin:
             p["manage"] = True
+        # ⭐ W34-T10 / C1 — always emitted for a database this route could READ, including when
+        # nothing is marked (`{marked: 0, counted: 0, partial: false}`). That is the same rule
+        # `omitted`/`degraded` follow at the bottom of this function and for the same reason: a key
+        # a consumer has to test for is a key a consumer forgets to test for. ABSENT here means
+        # "not a database, or we could not read it" — the second case is named in `degraded`.
+        if key in _important:
+            p["important"] = _important[key]
         entry = meta.get(p.get("key")) if meta else None
         if not entry:
             continue
@@ -422,8 +646,11 @@ def nav(session: Session = Depends(require_session)):
     # both doors finally agree on what a placeable key is. This block keeps using the assembled
     # list because it already holds it: re-enumerating here would be a second store read for an
     # answer sitting in a local variable.
-    recents = _read_recents(session.runtime, session.uname,
-                            {str(p.get("key", "")) for p in pages})
+    #
+    # ⚠ W34-T10 MOVED THE READ, NOT THE RULE. `recents` is now computed ABOVE the enrichment loop,
+    # because the important-count block spends its budget in RECENTS ORDER (see there). It is still
+    # ONE read of `nav_recents`, still pruned against the assembled page list, and it is used here
+    # unchanged — a second `_read_recents` call would be the extra store read this comment forbids.
     # ⭐ W31-T11 — TWO KINDS OF ABSENCE, NAMED SEPARATELY, and both keys are ALWAYS PRESENT.
     #   `omitted`  — this workspace's catalogue does not include these modules. Deliberate.
     #   `degraded` — a part of this payload could not be read. NOT deliberate, and the shell says
@@ -460,7 +687,7 @@ def nav_opened(body: dict = Body(default=None),
         raise err(400, "bad_request", "no page was named")
     if not session.runtime.available():
         raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — nothing was recorded")
+                  "the tenant store is unavailable. Nothing was recorded.")
     stamp, uname = _now(), session.uname
 
     def _up(data):
@@ -484,7 +711,7 @@ def nav_opened(body: dict = Body(default=None),
         session.runtime.update(_NAV_RECENTS_KEY, _up, flush='async')
     except Exception:
         raise err(503, "store_unavailable",
-                  "the tenant store refused the write — nothing was recorded")
+                  "the tenant store refused the write. Nothing was recorded.")
     return {"key": key, "at": stamp}
 
 
@@ -549,7 +776,7 @@ def save_nav_meta(body: dict = Body(default=None),
     if "name" in body:
         if not key.startswith("ut_"):
             raise err(400, "name_not_allowed",
-                      "only a database you created can be renamed — this one's name comes "
+                      "only a database you created can be renamed. This one's name comes "
                       "from the module registry")
         name = " ".join(str(body.get("name") or "").split())[:_MAX_NAV_NAME]
         if not name:
@@ -560,7 +787,7 @@ def save_nav_meta(body: dict = Body(default=None),
 
     if not session.runtime.available():
         raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — nothing was saved")
+                  "the tenant store is unavailable. Nothing was saved.")
 
     def _up(data):
         data = data if isinstance(data, dict) else {}
@@ -583,7 +810,7 @@ def save_nav_meta(body: dict = Body(default=None),
         session.runtime.update(_NAV_META_KEY, _up)
     except Exception:
         raise err(503, "store_unavailable",
-                  "the change was not saved — the store refused the write")
+                  "the change was not saved: the store refused the write.")
     return {"key": key, "meta": _read_nav_meta(session.runtime).get(key, {})}
 
 
@@ -608,7 +835,7 @@ def save_nav_prefs(body: dict = Body(default=None),
     clean = _clean_nav_prefs(body or {}, keys, keep_unknown_ut=not enumerated)
     if not session.runtime.available():
         raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — nothing was saved")
+                  "the tenant store is unavailable. Nothing was saved.")
 
     def _up(data):
         data = data if isinstance(data, dict) else {}
@@ -622,7 +849,7 @@ def save_nav_prefs(body: dict = Body(default=None),
         session.runtime.update(_NAV_PREFS_KEY, _up)
     except Exception:
         raise err(503, "store_unavailable",
-                  "the folder change was not saved — the store refused the write")
+                  "the folder change was not saved: the store refused the write.")
     return {"prefs": clean}
 
 

api/routes_tables.py

@@ -165,7 +165,7 @@ def _records_or_refuse(session, table_key, st=None):
     defn = _defn_or_refuse(session, table_key, st=st)
     if not _ut().records_mutable(table_key, st=st):
         raise err(403, "records_read_only",
-                  "records in this automation-owned database are read-only — add Instagram "
+                  "records in this automation-owned database are read-only. Add Instagram "
                   "handles in a Profile database and let enrichment populate this database")
     return defn
 
@@ -376,7 +376,7 @@ def delete_shared_field(table_key: str, field_key: str,
     owner = str(defn.get("createdBy") or "")
     if not session.admin and owner != session.uname:
         raise err(403, "forbidden",
-                  f"a tenant-wide column can be removed by its creator or an admin — this one "
+                  f"a tenant-wide column can be removed by its creator or an admin. This one "
                   f"was added by {owner or 'somebody else'}, and dropping it would delete the "
                   f"value for every account")
     dropped = shared_overlay.drop_field(table_key, str(field_key), st=session.runtime)
@@ -735,17 +735,17 @@ def create_table(body: dict = Body(default=None),
         raise err(400, "bad_label", "give the database a name")
     if not session.runtime.available():
         raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — nothing was created")
+                  "the tenant store is unavailable. Nothing was created")
     source = body.get("source")
     try:
         key = ut.create(label, session.uname, fields=body.get("fields"),
                         source=source, st=session.runtime)
     except Exception:
         raise err(503, "store_unavailable",
-                  "the tenant store refused the write — nothing was created")
+                  "the tenant store refused the write. Nothing was created")
     if not key:
         raise err(400, "refused",
-                  f"could not create it — the name may be empty or this tenant already has "
+                  f"could not create it. The name may be empty or this tenant already has "
                   f"{ut.MAX_TABLES} databases")
     return {"key": key}
 
@@ -845,7 +845,7 @@ def delete_table(table_key: str, session: Session = Depends(require_session)):
     try:
         _ut().delete(table_key, st=session.runtime)
     except Exception:
-        raise err(503, "store_unavailable", "the delete did not land — try again")
+        raise err(503, "store_unavailable", "the delete did not land. Try again")
     return {"ok": True}
 
 
@@ -993,6 +993,9 @@ def table_rows(table_key: str, session: Session = Depends(require_session)):
     # so a tenant using `json` for a short config sees no change at all.
     rows = aios_grid.rows_from_pool(
         g["rows_src"], g["fields"], _thin_json(g["fields"], merged, table_key), derived=g["derived"])
+    # ⭐⭐ WAVE-34 (R13) — the per-cell enrichment STATE rides the row, beside `_created`/`lat`/
+    # `lon`. See `_stamp_ai_states` for why it is a row key rather than a map beside `rows`.
+    _stamp_ai_states(table_key, g["fields"], rows, st=_lent)
     # ⭐ R6's SECOND SENTENCE, ON THE WIRE (W30-T29). *"if there is lag or it can't be done, you
     # need to explicitly tell me why and recommend a fix."* A ceiling that still applies to this
     # database says so here, with its cause and the recommendation, rather than waiting to be
@@ -1016,6 +1019,48 @@ def table_rows(table_key: str, session: Session = Depends(require_session)):
             "recordsMutable": _ut().records_mutable(table_key, st=_lent)}
 
 
+#: The per-cell provenance a row carries on the wire, one key per enrichment column.
+#: ⛔ A ROW KEY RATHER THAN A SIBLING MAP, and the choice is load-bearing rather than cosmetic.
+#: A `{colId: {pid: state}}` map beside `rows` would need a new PROP on `RecordDetail` and a new
+#: argument at `CustomerGrid`'s call site, both in another lane's fence, to reach the two surfaces
+#: that must paint it. The row already carries `_created`, `lat` and `lon` for exactly this
+#: reason, so every reader already tolerates keys that are not columns, and both surfaces hold the
+#: row already. ⚠ COLLISION-PROOF BY CONSTRUCTION: `_clean_field` strips leading underscores off
+#: every field key, so no column can ever be called `_ai_*`.
+AI_STATE_PREFIX = "_ai_"
+
+
+def _stamp_ai_states(table_key, fields, rows, st=None):
+    """Add `_ai_<colId>` to each row for every `ai_enrich` column. Mutates and returns `rows`.
+
+    ⛔ A PROJECTION, NOT THE MARK SET. The stratum holds a hash, a model, a timestamp, a token
+    count and an error per cell; a browser needs ONE WORD to paint a state, and shipping the rest
+    would grow this payload by a dict per enriched cell for data no reader reads. The vocabulary
+    is `agent`/`human`/`stale`/`error` (`api/ai_enrich.py::cell_state`), which is also what the
+    RUNNER obeys, so the badge and the behaviour cannot disagree about whose cell it is.
+
+    ⚠ AN ABSENT KEY MEANS `empty`, and only non-empty states are stamped: a table with no
+    enrichment column is untouched, and a freshly created column adds nothing until something
+    runs. ⛔ `stale` is DERIVED here rather than stored, so it is computed against TODAY'S row
+    instead of against whatever was true when the value was written.
+    """
+    cols = [f for f in (fields or []) if str(f.get("type") or "") == "ai_enrich"]
+    if not cols:
+        return rows
+    import ai_enrich as _ae
+    for field in cols:
+        col = str(field.get("key") or "")
+        marks = _ut().ai_enrich_marks(table_key, col, st=st)
+        cfg = field.get("aiEnrich") if isinstance(field.get("aiEnrich"), dict) else {}
+        for row in (rows or []):
+            if not isinstance(row, dict):
+                continue
+            state = _ae.cell_state(marks.get(str(row.get("pid"))), cfg, row, col)
+            if state != "empty":
+                row[AI_STATE_PREFIX + col] = state
+    return rows
+
+
 @router.get("/tables/{table_key}/rows/{pid}/fields/{fkey}")
 def table_cell(table_key: str, pid: str, fkey: str,
                session: Session = Depends(require_session)):
@@ -1062,7 +1107,7 @@ def add_row(table_key: str, body: dict = Body(default=None),
         rid = ut.add_row(table_key, values, session.uname, st=session.runtime,
                          rid=(body or {}).get("rid"))
     except Exception:
-        raise err(503, "store_unavailable", "the row was not saved — the store refused")
+        raise err(503, "store_unavailable", "the row was not saved. The store refused")
     if rid is None:
         # C3 (wave 25): `add_row` also refuses a profile cell that is not a handle, so the cap
         # sentence alone would misdirect — the reader would go and count rows. Ask the same
@@ -1072,11 +1117,11 @@ def add_row(table_key: str, body: dict = Body(default=None),
             _h, ok = ut.normalize_profile(values[pf["key"]], pf["profile"].get("source"))
             if not ok:
                 raise err(400, "refused",
-                          f"{str(values[pf['key']])[:80]!r} is not an Instagram profile — "
+                          f"{str(values[pf['key']])[:80]!r} is not an Instagram profile. "
                           f"{pf.get('label') or pf['key']!r} takes a handle (@name) or a "
                           f"profile link (instagram.com/name)")
         raise err(400, "refused",
-                  f"row refused — the table may be at its {ut.MAX_ROWS}-row cap")
+                  f"row refused. The table may be at its {ut.MAX_ROWS}-row cap")
     _refresh_relations(session)
     return {"rid": rid, "pid": int(rid)}
 
@@ -1130,14 +1175,14 @@ def import_rows(table_key: str, body: dict = Body(default=None),
         for key, value in row.items():
             why = ut.cell_type_refusal(by_key[key], value)
             if why:
-                raise err(400, "bad_value", f"row {index + 1}: {why} — nothing was imported")
+                raise err(400, "bad_value", f"row {index + 1}: {why}. Nothing was imported")
     try:
         made = ut.add_rows(table_key, rows_in, session.uname, st=session.runtime)
     except Exception:
-        raise err(503, "store_unavailable", "nothing was imported — the store refused")
+        raise err(503, "store_unavailable", "nothing was imported. The store refused")
     if made is None:
         raise err(400, "refused",
-                  f"nothing was imported — {len(rows_in)} rows would take this database past "
+                  f"nothing was imported. {len(rows_in)} rows would take this database past "
                   f"its {ut.MAX_ROWS}-row cap, or a profile column rejected a value")
     _refresh_relations(session)
     return {"imported": len(made), "pids": [int(r) for r in made]}
@@ -1168,7 +1213,7 @@ def _field_or_refuse(session, table_key, fkey=""):
     ut = _ut()
     if not ut.is_user_table(table_key, st=session.runtime):
         raise err(400, "not_a_user_table",
-                  "only a user-created database has an editable schema — a connected source "
+                  "only a user-created database has an editable schema. A connected source "
                   "owns its own columns")
     if fkey and not ut.may_edit_field(table_key, fkey, session.uname, session.admin,
                                       st=session.runtime):
@@ -1221,12 +1266,41 @@ def add_field(table_key: str, body: dict = Body(default=None),
     # field relational", which is the question that was always meant.
     if field.get("type") in ("link", "rollup"):
         _refresh_relations(session)
-    return {"field": field}
+    return _with_dropped(ut, {"field": field}, body)
+
+
+def _with_dropped(ut, out, body):
+    """Attach the NAMED list of config keys the validator did not keep (wave 34, R13 / W34-T51).
+
+    ⛔⛔ THIS EXISTS BECAUSE THE VALIDATOR HAS NO ERROR CHANNEL AND CANNOT GROW ONE. Every bag
+    cleaner in `core/user_tables.py` returns `dict | None` and drops unknown keys in silence, and
+    `verify_fields_contract` asserts that they do -- so the drop is correct and the SILENCE is the
+    defect. T51's contract is that an unknown config key is dropped **and named**, so the naming
+    rides the response beside the accepted field rather than inside the validator.
+
+    ⚠ OMITTED WHEN EMPTY, deliberately: an always-present `dropped: []` teaches every reader to
+    ignore the key, which is how a report stops being read before it stops being true.
+    """
+    dropped = ut.ai_enrich_dropped_keys((body or {}).get("aiEnrich"))
+    if dropped:
+        out = dict(out)
+        out["dropped"] = dropped
+    return out
 
 
 def _refusal_sentence(ut, session, body, table_key="", fkey=""):
     """Why was this column refused? The specific reason when we can name one, the general list
     otherwise — never a specific-sounding guess."""
+    # ⭐ WAVE-34 (R13): the enrichment column's own sentence, named BEFORE the automation bag
+    # below. `_clean_field` DERIVES `field.automation` for this kind, so a refused enrichment
+    # column would otherwise be explained by the flow law -- "pick a flow, or make this an
+    # ordinary column" -- which is the D-46 misdirection exactly, pointing at a control the user
+    # never touched.
+    if str((body or {}).get("type") or "").strip().lower() == "ai_enrich":
+        bag = (body or {}).get("aiEnrich")
+        if not isinstance(bag, dict) or not str(bag.get("prompt") or "").strip():
+            return ("an AI enrichment column needs a prompt. It is the only thing that can "
+                    "produce a value here, so a column without one would stay empty forever")
     # ⭐ C3 (wave 25, R7): the one-profile-per-table refusal NAMES THE EXISTING COLUMN, which is
     # what the contract asks for and what makes it actionable — "at most one" sends the reader
     # hunting through a 40-column schema for a flag they cannot see from the header.
@@ -1238,11 +1312,11 @@ def _refusal_sentence(ut, session, body, table_key="", fkey=""):
         # real mistake was the column type sends them to fix the wrong thing, which is the
         # misdirection D-46 closed one door over.
         if str((body or {}).get("type") or "text").strip().lower() != "text":
-            return ("a profile column is a flag on an ordinary TEXT column — it validates what "
+            return ("a profile column is a flag on an ordinary TEXT column. It validates what "
                     "is typed into it, which it can only do for text")
         existing = ut.profile_field(table_key, st=session.runtime) if table_key else None
         if existing and existing.get("key") != str(fkey):
-            return (f"this database already has a profile column — "
+            return (f"this database already has a profile column: "
                     f"{existing.get('label') or existing.get('key')!r}. A database has at most "
                     f"one, so the automation knows which handle to enrich; edit that column, or "
                     f"take the flag off it first")
@@ -1250,16 +1324,16 @@ def _refusal_sentence(ut, session, body, table_key="", fkey=""):
     if isinstance(bag, dict):
         flow = str(bag.get("flowId") or "").strip()
         if not flow:
-            return ("an automation column has to name the automation that fills it — pick a "
+            return ("an automation column has to name the automation that fills it. Pick a "
                     "flow, or make this an ordinary column")
         if not ut.flow_bound(bag, st=session.runtime):
             return (f"this column names automation {flow!r}, which does not exist in this "
-                    f"workspace — it may have been deleted; pick a flow that is still there")
+                    f"workspace. It may have been deleted; pick a flow that is still there")
     kind = str((body or {}).get("type") or "").strip()
     if kind and kind not in ut.UT_FIELD_TYPES:
         return (f"{kind!r} is not a column type here (types: "
                 f"{', '.join(sorted(ut.UT_FIELD_TYPES))})")
-    return (f"the column was refused — check the name and type, or the table may be at its "
+    return (f"the column was refused. Check the name and type, or the table may be at its "
             f"{ut.MAX_FIELDS}-column cap (types: {', '.join(sorted(ut.UT_FIELD_TYPES))})")
 
 
@@ -1282,7 +1356,7 @@ def patch_field(table_key: str, fkey: str, body: dict = Body(default=None),
         try:
             migrated = ut.rename_choice_values(table_key, fkey, renames, st=session.runtime)
         except Exception:
-            raise err(503, "store_unavailable", "the rename did not land — try again")
+            raise err(503, "store_unavailable", "the rename did not land. Try again")
         # The per-user workspace strata and any view filter naming the old value are the OTHER
         # half of C-RENAME and belong to `core.table_store`. Called only if it is there: an
         # enumerator's mirror waits for its counterpart rather than guessing at its shape, and a
@@ -1309,7 +1383,79 @@ def patch_field(table_key: str, fkey: str, body: dict = Body(default=None),
     out = {"field": field}
     if migrated is not None:
         out["migrated"] = migrated
-    return out
+    return _with_dropped(ut, out, body)
+
+
+def _fire_on_change(table_key, pid, changed, session):
+    """Run any `on_change` enrichment column whose prompt names a cell that just moved.
+
+    ⛔ ONE DEFINITION READ FOR THE WHOLE WRITE, and that is the point rather than an optimisation.
+    `automation_engine.grid_hook` calls `all_definitions(st)` once PER EVENT, which turns a
+    20,000-row import into 20,000 whole-document reads on the single process this product runs
+    (`D-134`, and `W34-T54`'s own `how:` says not to rebuild it). `on_change_fields` is pure and
+    takes the definition, so this reads once and asks about every column.
+
+    ⛔ AND IT NEVER FAILS THE WRITE. The cell edit has already succeeded and been acknowledged;
+    an enrichment that could not run is a missing value, not a lost edit, and the run's own report
+    carries the reason. ⚠ It is also deliberately SYNCHRONOUS and bounded to this one row: a
+    fan-out here would put a vendor call on the critical path of every keystroke-commit.
+    """
+    import ai_enrich as _ae
+
+    try:
+        defn = _ut().get(table_key, st=session.runtime) or {}
+        wanted = _ae.on_change_fields(defn, changed.keys())
+        for field in wanted:
+            _ae.run_field(table_key, field["key"], st=session.runtime, rows=[str(pid)])
+    except Exception:                                              # noqa: BLE001
+        pass
+
+
+@router.post("/tables/{table_key}/fields/{fkey}/enrich")
+def enrich_field(table_key: str, fkey: str, body: dict = Body(default=None),
+                 session: Session = Depends(require_session)):
+    """Run an AI enrichment column (wave 34, owner ruling R13). Returns the run's own REPORT.
+
+    ⛔ THIS DOOR SPENDS MONEY, so it rides the same wall every other schema write rides
+    (`_field_or_refuse`) rather than a looser one of its own. A read-only viewer cannot bill the
+    tenant by opening a grid.
+
+    `{"rows": ["3"]}` is a MANUAL run of exactly those records: a person asked, in front of the
+    value being replaced, so it skips the `overwrite` policy. An ABSENT `rows` is the automatic
+    plan, where the policy and the never-overwrite-a-human law both apply. The two are one
+    function with one flag, not two runners.
+
+    ⚠ THE REPORT IS THE PRODUCT, not a status code. It carries `filled`, `failed`, `skipped` by
+    reason, `tokens` spent, the provider, per-row errors, and `limit` (R6's second sentence: a
+    ceiling that stopped the run names its cause and a remedy). A 200 with `filled: 0` and a
+    populated `skipped` is a correct, informative answer, and the client must render it rather
+    than treat it as success.
+    """
+    _field_or_refuse(session, table_key, fkey)
+    import ai_enrich as _ae
+
+    rows = (body or {}).get("rows")
+    if rows is not None and not isinstance(rows, list):
+        raise err(400, "bad_rows", "`rows` must be a list of record ids, or absent to run the "
+                                   "rows this column's own settings choose")
+    # The caller's permitted pool, the same one the row doors use. A named row outside it is
+    # dropped rather than refused: a stale client naming a record that has been deleted or moved
+    # out of scope should not fail a run over the rows it can legitimately fill.
+    if rows is not None:
+        allowed = {str(p) for p in scoped_pids(session, table_key)[0]}
+        rows = [str(r) for r in rows if str(r) in allowed]
+    # ⭐ `W34-T54`'s bulk menu is this one field: "Rows never filled" sends `blank`, "All rows"
+    # sends `always`. Anything else falls back to the column's own saved policy rather than to a
+    # default, so a typo cannot quietly widen what a run touches.
+    report = _ae.run_field(table_key, fkey, st=session.runtime, rows=rows,
+                           policy=str((body or {}).get("scope") or "") or None,
+                           # A named row set through THIS door is a person asking.
+                           manual=rows is not None)
+    if report.get("problem"):
+        # A run that could not start at all is not a 200: nothing was attempted, nothing was
+        # spent, and the reason is actionable (no provider configured, or the wrong column).
+        raise err(400, "enrich_refused", str(report["problem"]))
+    return report
 
 
 @router.delete("/tables/{table_key}/fields/{fkey}")
@@ -1317,7 +1463,7 @@ def delete_field(table_key: str, fkey: str, session: Session = Depends(require_s
     _field_or_refuse(session, table_key, fkey)
     if not _ut().delete_field(table_key, fkey, st=session.runtime):
         raise err(400, "refused",
-                  "that column could not be removed — a database must keep at least one")
+                  "that column could not be removed. A database must keep at least one")
     _refresh_relations(session)
     return {"deleted": fkey}
 
@@ -1342,7 +1488,7 @@ def delete_row(table_key: str, rid: str, session: Session = Depends(require_sess
     try:
         ok = _ut().delete_row(table_key, rid, st=lent)
     except Exception:
-        raise err(503, "store_unavailable", "the delete did not land — try again")
+        raise err(503, "store_unavailable", "the delete did not land. Try again")
     if not ok:
         raise err(400, "refused", "rows can only be deleted from user-created databases")
     _refresh_relations(session)
@@ -1375,7 +1521,7 @@ def patch_row(table_key: str, pid: int, body: dict = Body(default=None),
              "pid": pid, "updates": updates}, ctx)
     except grid_events.StoreUnavailable:
         raise err(503, "store_unavailable",
-                  "the tenant store is unavailable — your change was not saved")
+                  "the tenant store is unavailable. Your change was not saved")
     # ⚠ THE READ-BACK IS THE DEFINITION ROW, AND ON A `ut_` SCOPE THAT IS THE WHOLE OF IT.
     #
     # ⛔ CORRECTED, wave-29 T22 (owner item 2a): this note used to say "THE READ-BACK SPANS BOTH
@@ -1414,6 +1560,22 @@ def patch_row(table_key: str, pid: int, body: dict = Body(default=None),
         return False
 
     refused = sorted(k for k in updates if not _took(k))
+    # ⭐⭐ WAVE-34 (R13) — THE HUMAN-EDIT STAMP, AND IT HAS TO HAPPEN HERE. "Did a person write
+    # this cell?" is not recoverable from the value afterwards, so the only place to record it is
+    # the door a person writes through. `ai_enrich_may_write` then refuses to let any automatic
+    # run overwrite it, whatever the column's `overwrite` policy says.
+    # ⚠ STAMPED FROM THE CELLS THAT ACTUALLY TOOK, never from what was asked: marking a refused
+    # write `human` would freeze a cell against the agent on the strength of an edit that never
+    # landed. `note_human_edit` filters to the enrichment columns itself and is a no-op otherwise.
+    took = {k: v for k, v in accepted.items() if k not in refused}
+    if took:
+        try:
+            _ut().note_human_edit(table_key, took, pid, st=session.runtime)
+        except Exception:                                          # noqa: BLE001
+            # Provenance is metadata about a write that has already succeeded. Failing the
+            # request here would tell the user their edit was lost when it was not.
+            pass
+        _fire_on_change(table_key, pid, took, session)
     out = {"pid": pid, "updates": accepted}
     if refused:
         out["refused"] = refused

api/web_agent.py

@@ -1,9 +1,10 @@
 """web_agent.py — THE SEAM between an automation step and a browser that runs somewhere else.
 
-CONTRACT C5 (wave 31, ruling R10 / D-51). E ships this; **C mounts it** in
-`automation_engine.py`'s action dispatch for `web_read` and adds the `verify_wiring` row —
-⛔ E cannot verify its own mounting, and an unmounted runner is a whole, correct, UNREACHABLE
-feature, which is exactly how five wave-29 features shipped behind green gates.
+CONTRACT C5 (wave 31, ruling R10 / D-51). E shipped this and C mounted it in
+`automation_engine.py`'s action dispatch; both halves landed and the `verify_wiring` row exists.
+⚠ That sentence was written in the FUTURE TENSE as a wave-31 hand-off and stayed that way for
+three waves, which is the smaller cousin of the correction below: a fence note describes one
+wave's division of labour and reads, afterwards, as a description of the code.
 
     result, error = web_agent.run_step(step, ctx)      # -> (dict|None, str)
 
@@ -30,22 +31,39 @@ foreground step of an automation RUN and far too slow for a route a person is wa
 cost is per JOB, not per step — `run_plan` sends a whole flow's steps in ONE job for that reason.
 
 ────────────────────────────────────────────────────────────────────────────────────────────────
-⛔ THREE THINGS ARE TRUE OF PRODUCTION TODAY AND ARE NOT DEFECTS IN THIS FILE. `capability()`
-reports each as a sentence, and `verify_web_agent.py` holds each to a check, so none of them can
-be discovered by a customer instead of by us:
-
-  1. THE SPACE'S TOKEN CANNOT PAY FOR A JOB. `deploy_web.py` pushes `HF_TOKEN`, which is scoped to
-     the org `royal-imports`; HF answers **402 `Pre-paid credit balance is insufficient`** there
-     and 0 jobs have ever run under it. `AIOS_HF_TOKEN` (user `fsanyoto`, 100 jobs) works and is
-     NOT pushed. Measured 2026-08-12.
-  2. THE SPACE DOES NOT SHIP THE JOB SCRIPT. `deploy_web.py` uploads `api/*.py` and
-     `platform/{core,modules,harness}`; `jobs/` is in no manifest. And `check_upload()` walks
-     IMPORTS, so it structurally cannot see a file opened by PATH — its own comments say so, about
-     `aios_grid_fields.json`, which crashed a Space for exactly this reason.
-  3. `routes_web_agent.py` IS NOT MOUNTED. `main.py` is another lane's file this wave.
-
-Each needs one line somebody else owns. Until then this module answers with a sentence rather
-than a silence, which is the whole of R6's second half.
+⛔⛔ WAVE 34 · W34-T44 — THIS BLOCK LISTED "THREE THINGS TRUE OF PRODUCTION TODAY". ALL THREE WERE
+FALSE BY THE TIME ANYBODY READ THEM, AND THIS DOCSTRING IS WHERE THE ERROR CAME FROM.
+
+It said the Space token 402s, that `deploy_web.py` never uploads `jobs/`, and that
+`routes_web_agent.py` is not mounted — so the whole web-action family was inert in production.
+**Four later documents repeated it** (the wave-34 PRD's scouted index, the plan-time scout's
+report, `W34-T44`'s own `how:`, and `run_gates.ps1`'s annotation telling a deploy to expect
+`web_agent` at 48/50), and every one of them traced back here. Re-checked line by line, against
+the files themselves, on 2026-08-16:
+
+  1. THE TOKEN IS PUSHED. `deploy_web.py:1128` adds `AIOS_HF_TOKEN` to the Space's secrets when it
+     is set, and `ENV_TOKEN` below prefers it over `HF_TOKEN`, so the org token that 402s is never
+     the one reached. The 402 itself is still true OF THAT TOKEN and is why the order matters.
+  2. THE JOB SCRIPT SHIPS. `deploy_web.py::_jobs_files` (:413) collects `jobs/` and :867 uploads
+     it. The `check_upload()` caveat stands as a caveat: it walks IMPORTS and cannot see a file
+     opened by PATH, so this upload is covered by the manifest, never by that check.
+  3. IT IS MOUNTED. `main.py:264`, `app.include_router(routes_web_agent.router)` — and
+     `verify_web_agent.py` asserts the route is in the SERVED set (`app.openapi()["paths"]`),
+     which is green.
+
+⭐ MEASURED END TO END the same day, from a dev box: `capability()` = ready True / "configured" /
+`AIOS_HF_TOKEN` / playwright 1.62.0, and a real `web_read` of `https://example.com h1` submitted in
+3.8 s, was alive at 21.4 s and returned `value "Example Domain"`, status 200, 106 ms in-browser,
+24.5 s wall clock cold.
+⚠ STILL UNPROVEN, so nobody over-corrects in the other direction: that run was NOT on the deployed
+Space, which carries the secret only if the last deploy read this `.env`. Proving it needs a click
+on staging, and until then "it works" means "it works from a box with the token".
+
+⛔ THE STANDING LESSON, kept here because this file is where it started: **a docstring stating
+facts about PRODUCTION has no expiry and nothing re-reads it when the world changes.** Three
+sentences about somebody else's file outlived all three of those files' fixes, and were quoted as
+current by four documents and a ticket. `capability()` answers the same question in under a second
+and returns TODAY's answer; prefer calling it to reading this.
 """
 import base64
 import hashlib
@@ -223,7 +241,7 @@ def _sentence_for(exc, namespace):
                 f"point this deployment at one that has it ({ENV_NAMESPACE} / {ENV_TOKEN[0]}). "
                 f"Nothing was read.")
     if status in (401, 403):
-        return (f"Hugging Face refused the browser job as unauthorised for {where} — this "
+        return (f"Hugging Face refused the browser job as unauthorised for {where}. This "
                 f"deployment's token does not carry `job.write` on that account. Point it at an "
                 f"account the token owns ({ENV_NAMESPACE}), or configure a token that owns this "
                 f"one ({ENV_TOKEN[0]}). Nothing was read.")
@@ -524,7 +542,7 @@ def _await(api, job_id, namespace, started, log):
             break
         if state in ("COMPLETED", "ERROR", "CANCELED"):
             return None, (f"The browser job {job_id} ended {state} without returning a result"
-                          f"{' — it never started printing' if not booted else ''}. "
+                          f"{'. It never started printing' if not booted else ''}. "
                           f"Nothing was read.")
         if not booted and waited > START_TIMEOUT:
             # The submitted-but-never-started case, named as itself.
@@ -534,7 +552,7 @@ def _await(api, job_id, namespace, started, log):
                 pass
             return None, (f"The browser job {job_id} was accepted but had not started after "
                           f"{int(START_TIMEOUT)}s (it stayed {state or 'queued'}), so it was "
-                          f"cancelled. Nothing was read — try again, or the platform is busy.")
+                          f"cancelled. Nothing was read. Try again, or the platform is busy.")
         if waited > RUN_TIMEOUT:
             try:
                 api.cancel_job(job_id=job_id, namespace=namespace)

platform/aios_grid.py

@@ -120,9 +120,20 @@ def _round(v):
 #: surfaces that CREATE them are the user-table databases, where a relation between two tables is
 #: a thing that exists. On the Odoo-backed Customer/Product grids there is no second user table to
 #: point at, so the column menu there simply never offers one.
+#: ⭐⭐ WAVE-34 (owner ruling R13) — `ai_enrich` JOINS, and it had to join HERE in the same change
+#: that put it in `UT_FIELD_TYPES`, not a ticket later. The wave planned a SERVER-FIRST landing on
+#: the reasoning that a kind the client does not offer is invisible while a kind the server refuses
+#: deletes a column. That reasoning is sound and the conclusion was still wrong, because THREE
+#: parity gates chain over these sets and none of them permits a partial landing:
+#:   `verify_api` W18-UT   `UT_FIELD_TYPES - CUSTOM_FIELD_TYPES == set()`   (this line)
+#:   `aw_fields_contract` §5   `CREATABLE_TYPES == CUSTOM_FIELD_TYPES`, EXACT set equality
+#:   `types.ts`   `CREATABLE_TYPES: readonly FieldType[]`, so the union must carry it too
+#: Measured live by lane B at 17:09: `api_api` went 969/969 to 968/969 the moment the kind entered
+#: `core/user_tables.py` alone, printing `got {'ai_enrich'} want set()`. The comments on
+#: `json`, `link`/`rollup` and `code` below all say the same thing in their own words.
 CUSTOM_FIELD_TYPES = {"text", "select", "multiselect", "user", "int", "currency", "pct", "date",
                       "checkbox", "phone", "email", "url", "rating", "created_time", "formula",
-                      "automation", "image", "json", "link", "rollup", "code"}
+                      "automation", "image", "json", "link", "rollup", "code", "ai_enrich"}
 
 #: ⭐ WAVE-27 item 13 (owner ruling R13) — the `code` field's LANGUAGES.
 #:

platform/core/registry.py

@@ -57,7 +57,7 @@ REGISTRY = [
     # briefing still read it, and pages_sales.py survives UNREGISTERED as the Y1 envelope's
     # template + verify_api's fixture.
     {'key': 'sales',     'label': 'Sales',              'brand': True,  'hq': False, 'validate': True, 'source': 'Odoo', 'archived': True,
-     'note': 'Revenue, YoY, seasonality, reps, customers, SKUs — by BU. Retired wave 16: '
+     'note': 'Revenue, YoY, seasonality, reps, customers, SKUs. By BU. Retired wave 16: '
              'rebuild as grid chart/dashboard views (compare series, KPI deltas, tables).'},
     # ARCHIVED AS A PAGE (owner item 14, wave 8): "archive the current form of the Customer
     # dashboard completely, i want to redesign it, exactly with the backend we have". So the
@@ -104,7 +104,7 @@ REGISTRY = [
     # _LEGACY_KEYS maps cohort→customer_data so grants + ?page= deep links land on the grid
     # that now hosts the cohorts.
     {'key': 'cohort',    'label': 'Cohort',             'brand': True,  'hq': False, 'validate': False, 'source': 'Odoo', 'parent': 'customers', 'archived': True,
-     'note': 'Hand-curated, unchanging customer lists — folded into the Customer rail as '
+     'note': 'Hand-curated, unchanging customer lists. Folded into the Customer rail as '
              'locked views (wave 16). The set is fixed: it changes only when someone adds '
              'or removes a member. Open them from Customer > Views > Cohorts.'},
     # ARCHIVED wave 16 (owner item 7, R11, 2026-08-02) beside Sales. The agent DRAWER and the
@@ -131,9 +131,9 @@ REGISTRY = [
      'note': 'The SKU catalogue as a grid: per-product revenue, units and (consolidated) '
              'stock columns, with saved views and custom fields. Identity = the SKU code.'},
     {'key': 'products',  'label': 'SKU',                'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'SKU movers, zombies, velocity, coverage, drawers — by BU (sales-derived).'},
+     'note': 'SKU movers, zombies, velocity, coverage, drawers. By BU (sales-derived).'},
     {'key': 'assortment', 'label': 'Assortment',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Facet-level performance (category/color/occasion/collection/season) + season readiness — by BU.'},
+     'note': 'Facet-level performance (category/color/occasion/collection/season) + season readiness. By BU.'},
     {'key': 'financial', 'label': 'Financial',          'brand': True,  'hq': False, 'validate': True, 'archived': True,
      'note': 'Gross margin by BU/category/SKU. Cash-conversion cycle is HQ-consolidated.'},
     {'key': 'pricing',   'label': 'Pricing',            'brand': True,  'hq': False, 'validate': True, 'archived': True,
@@ -148,7 +148,7 @@ REGISTRY = [
      'note': 'PAGE RETIRED 2026-08-03 (owner wave-17 item 13: "We should be able to replace '
              'Procurement completely, and add it as part of the Product database"). The buy '
              'list is now a saved VIEW on the Product grid, filtered on a FORMULA field over '
-             'the supplier/lead-time columns and the demand measure — the owner\'s ruling R3: '
+             'the supplier/lead-time columns and the demand measure. The owner\'s ruling R3: '
              '"Buy list is just a View, with a Filter from a Formula field that taps into '
              'Metrics Fields... the 8-month demand baseline etc. is just math in a Formula '
              'field." The ROW STAYS validate_only: `modules/procurement.py` still owns the '
@@ -162,7 +162,7 @@ REGISTRY = [
      'source': 'Odoo', 'api_surface': False, 'admin_only': True,
      'note': 'PAGE RETIRED 2026-08-03 (owner wave-17 item 15: "Collections should also be '
              'entirely replicable as just a View under Customer"). The worklist is the shared '
-             '"Collections" view on the Customer grid — same numbers, from this module\'s own '
+             '"Collections" view on the Customer grid. Same numbers, from this module\'s own '
              'reconciled blocks (ar_open/ar_overdue/ar_exposure/days_to_pay + the four aging '
              'buckets). The ROW STAYS validate_only so validate.py keeps running ar.validate(), '
              'which is the proof those columns rest on; archiving it would have skipped the '
@@ -171,7 +171,7 @@ REGISTRY = [
              'sender (app._collections_statements -> modules/collections_send), the ONE '
              'sanctioned Odoo writer, which the same ruling says stays untouched. So the row '
              'keeps a Streamlit page for ADMINS ONLY (`admin_only`) and leaves the API payload '
-             'entirely (`api_surface: False`) — no "Collections" in the React nav, no second '
+             'entirely (`api_surface: False`). No "Collections" in the React nav, no second '
              'worklist, and the biweekly send keeps its door.'},
     {'key': 'returns',   'label': 'Returns',            'brand': False, 'hq': True,  'validate': True, 'archived': True,
      'note': 'Credit-note lens: refund concentration by SKU (quality) and customer (behavior). Company-level.'},
@@ -180,7 +180,7 @@ REGISTRY = [
     {'key': 'backorders', 'label': 'Backorders',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
      'note': 'Confirmed-undelivered order lines aged vs promise date, valued, with a supply-aware next action per row (ship / expedite / call). Wholesale scope.'},
     {'key': 'pricecomp', 'label': 'Price Compliance',   'brand': True,  'hq': False, 'validate': True, 'archived': True,
-     'note': 'Selling below the customer pricelist tier (LTM, per customer x SKU): the pocket-price floor worklist with annualized leak $. Sub-30% ratios usually mean a stale or pack-basis RULE — fix the rule, not the rep.'},
+     'note': 'Selling below the customer pricelist tier (LTM, per customer x SKU): the pocket-price floor worklist with annualized leak $. Sub-30% ratios usually mean a stale or pack-basis RULE. Fix the rule, not the rep.'},
     {'key': 'o2c',       'label': 'Cash Timing',        'brand': True,  'hq': False, 'validate': True, 'archived': True,
      'note': 'Order-to-cash stage decomposition (order-to-ship / ship-to-invoice / invoice-to-paid, each with its owner) + the terms-gap rollup: contractual vs actual days per payment term with the free-credit $ it strands.'},
     {'key': 'bookings',  'label': 'Order Book',         'brand': True,  'hq': False, 'validate': True, 'archived': True,
@@ -193,29 +193,37 @@ REGISTRY = [
      'note': 'Operating expense from the GL (all expense-type accounts; COGS excluded): trend, operating leverage (opex % of revenue), the YoY cost bridge, XmR control-limit spike watch list, fixed/variable split and a drill-to-ledger category directory. Company-level.'},
     {'key': 'health',    'label': 'Data Health',        'brand': False, 'hq': True,  'validate': True, 'archived': True,
      'note': 'Close/reconciliation scan; period-filtered, mostly company-level. ARCHITECTURE '
-             '(owner 2026-07-23): every discrepancy / potential-error marker lives here — '
+             '(owner 2026-07-23): every discrepancy / potential-error marker lives here. '
              'procurement mapping gaps, count-trust (unverified on-hand counts), untracked-on-'
-             'order — so operational workflows stay clean for doing the work.'},
+             'order. So operational workflows stay clean for doing the work.'},
     {'key': 'dictionary', 'label': 'Metric Dictionary', 'brand': False, 'hq': True,  'validate': True,
      'nav': False, 'validate_only': True,
-     'note': 'PAGE RETIRED 2026-07-23 (owner: broken/not customer-facing) — row kept ONLY so '
+     'note': 'PAGE RETIRED 2026-07-23 (owner: broken/not customer-facing). Row kept ONLY so '
              'validate.py keeps running the semantic-layer contracts (the Analyst grounding '
-             'proof). No nav, no page. Wave 17 R8 ("I don\'t even know what it does — delete '
+             'proof). No nav, no page. Wave 17 R8 ("I don\'t even know what it does. Delete '
              'them") made that literal: `validate_only` takes it out of the account menu too, '
              'which is the last place it was still visible. The proof survives; the door does not.'},
-    {'key': 'automation', 'label': 'Automation',        'brand': False, 'hq': True,  'validate': False,
+    {'key': 'automation', 'label': 'Agents',            'brand': False, 'hq': True,  'validate': False,
      'nav': True,
-     'note': 'Wave 18 (C-AUTONAV): the Automation surface — scheduled jobs that create and '
-             'refresh user databases (website scrape-to-DB, the Instagram field). React-only '
-             'surface (no PAGE_FUNCS entry, the no-new-Streamlit rule); admins hold it via '
-             '"all", other users need the explicit grant — fail-closed default.'},
+     'note': 'Wave 18 (C-AUTONAV): scheduled jobs that create and refresh user databases '
+             '(website scrape-to-DB, the Instagram field). React-only surface (no PAGE_FUNCS '
+             'entry, the no-new-Streamlit rule); admins hold it via "all", other users need the '
+             'explicit grant, fail-closed default. '
+             '⭐ WAVE 34 · R12. THE LABEL IS "Agents" AND THE KEY IS STILL `automation`. The '
+             'owner ruled the module becomes Agent: this is our agent deployment surface going '
+             'forward. Only the LABEL moved, because the key is a permission scope, a nav '
+             'placement key, a grant name and the `#/automation` route; renaming it would revoke '
+             'every stored grant and 404 every bookmark to buy a caption. ⚠ The plural is not a '
+             'slip: R15 and the wave PRD both spell the rail row "Agents", and the degraded '
+             'fallback row in Shell.tsx hard-codes that spelling, so a singular here would paint '
+             'two different words in one list depending on whether /nav answered.'},
     {'key': 'settings',  'label': 'Settings',           'brand': False, 'hq': True,  'validate': False,
      'nav': False,   # sidebar sentinel (account group) — owner IA 2026-07-12
      'note': 'User scope settings: the Business Unit toggle (strict isolation) and the Data basis '
              'toggle (Orders vs Invoiced) moved here from the sidebar.'},
     {'key': 'analyst',   'label': 'AIOS Analyst',       'brand': False, 'hq': True,  'validate': False,
      'nav': False,   # sidebar sentinel button; eval gate = harness/evals.py (run pre-ship, NOT in validate.py — live LLM cost)
-     'note': 'Ask the business a question in plain language: a small AI model calls governed tools over the semantic layer — answers carry their query trace and drill links. AI-generated output (Art. 50 labeled).'},
+     'note': 'Ask the business a question in plain language: a small AI model calls governed tools over the semantic layer. Answers carry their query trace and drill links. AI-generated output (Art. 50 labeled).'},
 ]
 
 BY_KEY = {m['key']: m for m in REGISTRY}

platform/core/user_tables.py

@@ -336,7 +336,7 @@ def limit_report(table_key, st=None):
         'cause': f'this database is EDITABLE, so its rows live in the shared `{STORE_KEY}` '
                  f'document that every request copies; at the widest shipped row (0.318 KB) '
                  f'{cap:,} rows is 19.1 MB against a 32 MB per-table budget',
-        'recommendation': 'connect it to a source instead — connected data is served '
+        'recommendation': 'connect it to a source instead. Connected data is served '
                           'read-through from the mirror and is not bounded (R6); for typed data '
                           'the increment is D-87, a per-table row key, not a bigger number',
     }
@@ -439,9 +439,15 @@ def records_mutable(table_key, st=None):
 #: waves because `verify_fields_contract` diffed the client's offer against the ODOO grid's
 #: acceptance and never against this set. Wave-27 item 13 adds that derived leg, which is what
 #: found it (measured, not reviewed: `_clean_field({'type':'image'})` returned None).
+#: ⭐ WAVE-34 (owner ruling R13) — `ai_enrich` JOINS, and it lands HERE FIRST rather than last.
+#: The block above records that `image` reached four of the five surfaces and missed this one, so
+#: the client offered a column the server deleted on the next read. `ai_enrich` is added to this
+#: set in `W34-T51` (server) while the CLIENT half waits for `W34-T53`, which is the safe order:
+#: a kind the server accepts and the client does not offer is invisible, whereas a kind the client
+#: offers and the server refuses is a column created, named, configured and gone.
 UT_FIELD_TYPES = {'text', 'select', 'multiselect', 'user', 'int', 'currency', 'pct', 'date',
                   'checkbox', 'phone', 'email', 'url', 'rating', 'automation', 'json',
-                  'link', 'rollup', 'code', 'image', 'formula'}
+                  'link', 'rollup', 'code', 'image', 'formula', 'ai_enrich'}
 #: A cell is still a scalar on the wire (`Row` values are strings/numbers) — what this bounds is
 #: the DOCUMENT inside it.  Source data is one already-paid provider response; keep it whole so a
 #: provider field is never silently discarded merely because the response is rich. 32 MiB matches
@@ -902,6 +908,19 @@ def clean_fields(raw):
                 entry = None
             elif fx is not None:
                 entry['formula'] = fx
+        # ⭐⭐ WAVE-34 (R13) — the AI ENRICHMENT bag rides THIS door too, and it is the SIXTH time
+        # this seam has been fixed after the fact (`pinned`, `code`, `link`/`rollup`, `formula`,
+        # `agg`). It is written in the same change as `_clean_field`'s arm rather than a wave
+        # later, which is the only difference between this entry and the five above it.
+        if entry is not None:
+            ae = (_clean_ai_enrich(f.get('aiEnrich'))
+                  if f.get('aiEnrich') is not None else None)
+            if (ftype == 'ai_enrich') != (ae is not None):
+                entry = None
+            elif ae is not None:
+                entry['aiEnrich'] = ae
+                # C3: derived, never typed beside the config. Same call as the other door.
+                entry['automation'] = _field_agent_binding(entry)
         if entry is None:
             seen.discard(key)
             continue
@@ -1664,6 +1683,308 @@ def _clean_rollup(raw):
     return out
 
 
+# ---------------------------------------------------------------------------------------------
+# THE AI ENRICHMENT COLUMN (wave 34, owner ruling R13)
+# ---------------------------------------------------------------------------------------------
+# R13: *"a field kind called AI enrichment: a prompt per row that populates text. Detailed
+# configuration in the field's own config, including a token-usage limit."*
+#
+# ⛔ POSTURE: `link`/`rollup`/`formula`'s, NOT `code`'s. The bag DEFINES the column — a prompt is
+# the only thing that can ever produce a value here — so the type/bag pairing is enforced BOTH
+# WAYS and either half alone refuses the field. An `ai_enrich` column with no prompt is a column
+# that renders, sorts, filters and can never hold anything, which is the silent kind of broken
+# every other bag on this door is paired to prevent.
+#
+# ⚠ AND THE VALUE IS STORED, NOT COMPUTED. `formula` is client-recomputed on every paint and
+# `rollup` is read-through; neither persists. An enrichment that vanished on reload would not be
+# the feature (PRD assumption A6), so an `ai_enrich` cell is an ordinary stored string, a human
+# may type over it, and it is deliberately NOT in `is_computed_cell`.
+
+#: The bag's own key set, read by BOTH the cleaner and the reporter below so they cannot disagree
+#: about what "unknown" means. ⛔ ONE constant, because T51's contract is that an unknown key is
+#: DROPPED **and NAMED** — two hand-maintained lists would eventually drop a key the report did
+#: not mention, which reads to a user as the config silently not saving.
+AI_ENRICH_KEYS = ('prompt', 'model', 'maxTokens', 'trigger', 'overwrite')
+#: When the column runs. `manual` = only when a person asks; `on_change` = when a referenced cell
+#: moves; `schedule` = on a cadence. The community ask R13 cites ("enrichment on a schedule") is
+#: the third of these, so it is in the vocabulary from the start rather than added later.
+AI_ENRICH_TRIGGER_MODES = ('manual', 'on_change', 'schedule')
+#: What an AUTOMATIC run may replace. ⛔ A HUMAN-EDITED CELL IS NEVER OVERWRITTEN AND THAT IS NOT
+#: IN THIS VOCABULARY — it is a law (`ai_enrich_may_write`), not a policy, so no configuration can
+#: turn it off. These three decide only what happens to cells the AGENT itself wrote.
+AI_ENRICH_OVERWRITE = ('blank', 'stale', 'always')
+#: Bounded because the ceiling is the feature (R13). The floor is one useful sentence; the roof is
+#: what one cell can cost before the run has to say so out loud.
+AI_ENRICH_MIN_TOKENS, AI_ENRICH_MAX_TOKENS = 16, 4000
+AI_ENRICH_DEFAULT_TOKENS = 300
+#: A prompt is a template, not an essay. Long enough for real instructions plus a few `{field}`
+#: tokens, short enough that the per-cell input cost is predictable.
+AI_ENRICH_PROMPT_MAX = 2000
+#: `cron` is stored as an opaque bounded string. ⚠ It is NOT parsed here on purpose: this module
+#: owns the field contract, and the scheduler that reads it owns the cadence vocabulary. Parsing
+#: it in two places is how one door starts refusing a cadence the other accepts.
+AI_ENRICH_CRON_MAX = 120
+
+
+def _clean_ai_enrich(raw):
+    """The `ai_enrich` config bag → the stored shape, or None if the column cannot run.
+
+    ⚠ Every key is normalised to a canonical form, so a definition saved and re-read is
+    byte-identical (`_clean_ai_enrich(_clean_ai_enrich(x)) == _clean_ai_enrich(x)`). That
+    idempotence is what makes the round-trip clause testable rather than a claim.
+    """
+    if not isinstance(raw, dict):
+        return None
+    prompt = str(raw.get('prompt') or '').strip()[:AI_ENRICH_PROMPT_MAX]
+    if not prompt:
+        return None                      # the prompt IS the column; see the posture note above
+    out = {'prompt': prompt}
+    # The model is OPTIONAL and an unknown name is DROPPED rather than refused: it selects a
+    # PROVIDER for a column that already knows what to ask, so a stale name should fall back to
+    # the ladder's own order, never destroy the column. (`code`'s language argument, same shape.)
+    model = str(raw.get('model') or '').strip().lower()[:60]
+    if model:
+        out['model'] = model
+    tokens = raw.get('maxTokens')
+    # `bool` is an `int` subclass — `True` would otherwise validate as a 1-token ceiling.
+    if isinstance(tokens, bool) or not isinstance(tokens, (int, float)):
+        tokens = AI_ENRICH_DEFAULT_TOKENS
+    out['maxTokens'] = max(AI_ENRICH_MIN_TOKENS, min(int(tokens), AI_ENRICH_MAX_TOKENS))
+    trig = raw.get('trigger') if isinstance(raw.get('trigger'), dict) else {}
+    mode = str(trig.get('mode') or '').strip().lower()
+    trigger = {'mode': mode if mode in AI_ENRICH_TRIGGER_MODES else 'manual'}
+    # ⛔ `cron` is kept ONLY on a scheduled column. A cadence stored under `manual` is a setting
+    # the user can see and nothing will ever read — the shape D-246 wears on the Odoo sync, where
+    # a `manual` preset does nothing because no branch reads it.
+    cron = str(trig.get('cron') or '').strip()[:AI_ENRICH_CRON_MAX]
+    if trigger['mode'] == 'schedule' and cron:
+        trigger['cron'] = cron
+    out['trigger'] = trigger
+    overwrite = str(raw.get('overwrite') or '').strip().lower()
+    out['overwrite'] = overwrite if overwrite in AI_ENRICH_OVERWRITE else 'blank'
+    return out
+
+
+def ai_enrich_dropped_keys(raw):
+    """The config keys `_clean_ai_enrich` will NOT keep, sorted — the NAMING half of T51's
+    "an unknown config key is DROPPED and NAMED, never silently eaten".
+
+    ⛔ IT EXISTS BECAUSE EVERY OTHER BAG CLEANER IN THIS FILE HAS NO ERROR CHANNEL. `_clean_link`,
+    `_clean_rollup`, `_clean_profile` and `_clean_format` all return `dict | None` and drop
+    unknown keys in silence — `verify_fields_contract` even asserts that they do. Copying one of
+    them as a template gets the DROP right and the NAMING wrong by construction, so the report is
+    a separate function reading the SAME `AI_ENRICH_KEYS` constant rather than a second list.
+
+    ⚠ It reports UNKNOWN keys only. A known key whose VALUE was normalised (an out-of-range
+    ceiling clamped, an unknown model dropped) is not a surprise worth a sentence — the stored
+    definition comes straight back to the editor, so the user sees the accepted value itself.
+    """
+    if not isinstance(raw, dict):
+        return []
+    return sorted(str(k) for k in raw if k not in AI_ENRICH_KEYS)
+
+
+def ai_enrich_fields(defn):
+    """Every `ai_enrich` column in this table definition, in declaration order.
+
+    One reader for "which columns are field agents", so the Agents module (contract C3), the
+    runner and the scheduler cannot disagree about the set ([[one-evaluator-per-question]]).
+    """
+    return [f for f in ((defn or {}).get('fields') or [])
+            if isinstance(f, dict) and f.get('type') == 'ai_enrich'
+            and isinstance(f.get('aiEnrich'), dict)]
+
+
+def _field_agent_binding(field):
+    """Contract C3's `field.automation` bag, DERIVED from the column rather than typed beside it.
+
+    ⛔⛔ THIS IS DERIVED ON PURPOSE AND IT IS THE ONE DESIGN CALL IN T51 WORTH ARGUING WITH.
+    C3 as drafted has F *store* `{kind, table, field, trigger}` — but `field` is already
+    `field['key']` and `trigger` is already `aiEnrich['trigger']`, so two of its four keys would
+    be a second copy of a fact this same dict already carries. Two copies of one fact is
+    [[one-question-two-normalizers]] with a guaranteed drift date: the first PATCH that changes
+    the trigger through the enrichment editor and not through the automation editor.
+    Computing it inside the SINGLE validator both write doors run means they cannot diverge.
+
+    ⚠ `table` IS ABSENT, and that is the deviation E must know about: this function is handed one
+    field dict and no table context, while `_clean_field(f) == f` is asserted by two gates over
+    engine-seeded field lists — stamping the table key from a caller that happens to know it would
+    make a stored field unequal to its own validator's output. E iterates tables to build the
+    synthetic rows, so E already holds the key that would go here.
+    """
+    bag = (field or {}).get('aiEnrich')
+    if not isinstance(bag, dict):
+        return None
+    return {'kind': 'field_agent', 'field': str((field or {}).get('key') or ''),
+            'trigger': dict(bag.get('trigger') or {'mode': 'manual'})}
+
+
+# ---------------------------------------------------------------------------------------------
+# PER-CELL PROVENANCE (wave 34, W34-T51 — "stamp it FROM DAY ONE")
+# ---------------------------------------------------------------------------------------------
+# ⛔⛔ IT CANNOT LIVE IN THE ROW, AND THAT IS MEASURED RATHER THAN ASSUMED. `add_row` builds its
+# row as `{k: str(v) for k, v in values.items() if k in valid}` where `valid` is the declared
+# field keys — a row dict is field-keys-only by construction, so a reserved `__ai__` key inside
+# one would be stripped on the way in. Widening that filter to admit a private key would weaken
+# the wall that stops a client inventing columns. So provenance is a SIBLING STRATUM of `rows`,
+# exactly as `fields` and `rows` are siblings today.
+#
+# ⛔ AND `stale` IS DERIVED, NEVER STORED. A stored `stale` flag needs a sweep to stay true, and a
+# sweep nobody runs is [[flag-shipped-without-its-writer]]. What IS stored is the INPUT HASH the
+# value was produced from; `ai_enrich_is_stale` compares it to today's inputs, so staleness is a
+# question asked at read time and can never be out of date.
+
+#: The stratum's key inside a table document, beside `fields` and `rows`.
+AI_ENRICH_MARK_KEY = 'aiEnrich'
+#: What a mark can say. ⚠ `stale` is absent ON PURPOSE (see above) and so is `generating`: an
+#: in-flight run is a fact about a REQUEST, not about stored data, and persisting it would leave
+#: a cell stuck on "generating" forever the first time a process dies mid-run.
+AI_ENRICH_STATES = ('agent', 'human', 'error')
+#: A bound on the stratum, in the shape `row_limit` uses: this document is copied whole on every
+#: read, so a mark set that can outgrow the rows it describes is a store problem wearing a
+#: feature's name. One mark per (row, column) is the natural size; the cap is the guard against a
+#: column deleted without its marks.
+AI_ENRICH_MAX_MARKS = MAX_ROWS
+#
+# ⚠ THERE IS DELIBERATELY NO `drop_marks(column)`, AND THE ABSENCE IS THE DECISION. `delete_field`
+# leaves a deleted column's CELLS in the rows on purpose — an accidental delete stays recoverable,
+# and re-adding the column under the same key brings the values back. Marks must follow the same
+# rule or a restored column's agent-written values would come back looking human-authored, which
+# is the one distinction this whole stratum exists to make. A table that is deleted takes its
+# document (and therefore its marks) with it, so neither lifecycle leaks.
+
+
+def ai_enrich_input_hash(prompt, row, refs):
+    """The fingerprint a stored value was produced FROM: the prompt plus the referenced cells.
+
+    ⚠ `refs` is passed in rather than re-parsed here, so the token vocabulary is owned by one
+    module (`api/ai_enrich.py::prompt_refs`) instead of two. A hash built from a second parse
+    would disagree with the runner's the first time the token syntax gains a form.
+    """
+    payload = [str(prompt or '')]
+    for key in sorted(str(r) for r in (refs or ())):
+        payload.append(f'{key}={(row or {}).get(key, "")}')
+    return hashlib.sha256('\x1f'.join(payload).encode('utf-8')).hexdigest()[:32]
+
+
+def ai_enrich_marks(table_key, col_id, st=None):
+    """`{row_id: mark}` for ONE column. Absent = a cell nobody has written yet."""
+    stratum = (get(table_key, st) or {}).get(AI_ENRICH_MARK_KEY) or {}
+    got = stratum.get(str(col_id))
+    return dict(got) if isinstance(got, dict) else {}
+
+
+def ai_enrich_is_stale(mark, fresh_hash):
+    """Was this value produced from inputs that have since changed?
+
+    A human edit is never stale — a person's own words do not go out of date because a
+    neighbouring cell moved. Only an agent-written value can be.
+    """
+    if not isinstance(mark, dict) or mark.get('state') != 'agent':
+        return False
+    return bool(fresh_hash) and str(mark.get('hash') or '') != str(fresh_hash)
+
+
+def ai_enrich_human_authored(mark, has_value=False):
+    """Did somebody other than the agent put this value here?
+
+    ⛔ TWO CASES, AND THE SECOND IS THE ONE THAT GETS MISSED. An explicit `human` mark is obvious.
+    The other is a cell that holds a value with NO mark at all: a value typed, pasted or imported
+    before the column became an enrichment column. The agent did not write it, so the agent does
+    not own it. Without this arm, `overwrite: 'always'` would eat exactly the pre-existing work
+    R8's *"we are helping the team put their work into the system"* is about.
+
+    ⚠ ONE PREDICATE, because `ai_enrich_may_write` and `api/ai_enrich.py::cell_state` both answer
+    "is this the human's?" and a cell the UI labels human-written while the runner overwrites it
+    is the worst of both ([[one-question-two-normalizers]]).
+    """
+    if isinstance(mark, dict) and mark.get('state') == 'human':
+        return True
+    return bool(has_value) and not (isinstance(mark, dict) and mark.get('state') == 'agent')
+
+
+def ai_enrich_may_write(mark, policy, fresh_hash, has_value=False):
+    """May an AUTOMATIC run write this cell? The law, in one place.
+
+    ⛔ THE FIRST CLAUSE IS NOT CONFIGURABLE. A cell a person typed into is never overwritten by an
+    agent, whatever `overwrite` says — that is why `human` is not one of the `AI_ENRICH_OVERWRITE`
+    values, and why `always` means "always refresh what the AGENT owns" rather than "overwrite
+    everything". A policy that could turn it off would make the column unsafe to hand to a team.
+    ⚠ A MANUAL, per-cell run is a different act with a different door; this predicate governs the
+    automatic paths (`on_change`, `schedule`, and a bulk "all rows" sweep).
+    """
+    if ai_enrich_human_authored(mark, has_value):
+        return False
+    if not has_value:
+        return True                       # a blank cell is fillable under every policy
+    if policy == 'always':
+        return True
+    if policy == 'stale':
+        return ai_enrich_is_stale(mark, fresh_hash)
+    return False                          # 'blank': an agent never replaces a value it wrote
+
+
+def stamp_ai_enrich(table_key, col_id, marks, st=None):
+    """Write MANY marks for one column in ONE store update. Returns the number stored.
+
+    ⛔ BULK BY CONSTRUCTION, and the signature is what enforces it. Every write here is a
+    read-modify-write of the whole tenant document, so a per-row stamp inside a run loop is the
+    same shape as the 2,000-full-document-copies problem `add_rows` exists to avoid. There is
+    deliberately no `stamp_one`.
+    """
+    col_id = str(col_id)
+    clean = {}
+    for row_id, mark in (marks or {}).items():
+        if not isinstance(mark, dict):
+            continue
+        state = str(mark.get('state') or '')
+        if state not in AI_ENRICH_STATES:
+            continue
+        entry = {'state': state, 'at': _dt.datetime.now(_dt.timezone.utc)
+                 .replace(microsecond=0).isoformat()}
+        for key, cap in (('hash', 64), ('model', 60), ('error', 300)):
+            got = str(mark.get(key) or '').strip()[:cap]
+            if got:
+                entry[key] = got
+        tokens = mark.get('tokens')
+        if isinstance(tokens, int) and not isinstance(tokens, bool) and tokens >= 0:
+            entry['tokens'] = tokens
+        clean[str(row_id)] = entry
+    if not clean:
+        return 0
+
+    def _set(cur):
+        t = cur.get(str(table_key))
+        if t is not None:
+            col = t.setdefault(AI_ENRICH_MARK_KEY, {}).setdefault(col_id, {})
+            col.update(clean)
+            # The cap is enforced by DROPPING THE OLDEST, never by refusing the write: a run that
+            # produced values and could not record where they came from would leave the cells
+            # looking human-authored, which is the one state this stratum exists to distinguish.
+            if len(col) > AI_ENRICH_MAX_MARKS:
+                for rid in sorted(col, key=lambda r: str(col[r].get('at') or ''))[
+                        :len(col) - AI_ENRICH_MAX_MARKS]:
+                    col.pop(rid, None)
+        return cur
+
+    _st(st).update(STORE_KEY, _set, flush='async')
+    return len(clean)
+
+
+def note_human_edit(table_key, values, row_id, st=None):
+    """A person typed into these cells: mark any `ai_enrich` column among them `human`.
+
+    ⛔ THE STAMP HAS TO HAPPEN AT THE WRITE DOOR, not at read time, because "did a human write
+    this" is not recoverable from the value afterwards. Called by `routes_tables.patch_row`;
+    a no-op (and cheap) for the overwhelming case where the edited columns are ordinary.
+    """
+    defn = get(table_key, st) or {}
+    touched = {f['key'] for f in ai_enrich_fields(defn)} & {str(k) for k in (values or {})}
+    for col_id in touched:
+        stamp_ai_enrich(table_key, col_id, {str(row_id): {'state': 'human'}}, st=st)
+    return sorted(touched)
+
+
 def _clean_field(raw, previous=None):
     """One field dict → the stored shape, or None. The single validator for create AND patch, so
     a column cannot be typed one way on the way in and another on the way back."""
@@ -1899,6 +2220,28 @@ def _clean_field(raw, previous=None):
         out['formula'] = fx
     elif ftype == 'formula':
         return None
+    # ⭐⭐ WAVE-34 (owner ruling R13) — THE AI ENRICHMENT BAG. Posture and inheritance copied from
+    # `formula` two lines up, deliberately and for the same reason: the bag defines the column, so
+    # the pairing is enforced both ways, and an inherited bag is only inherited while the type
+    # still wants it (retyping an enrichment column to text must not resurrect its prompt through
+    # `prev` and then refuse the whole write, which is the bug the `prev_type == ftype` guard on
+    # `link`/`rollup`/`formula` exists to record).
+    enrich_raw = (raw.get('aiEnrich') if 'aiEnrich' in raw
+                  else (prev.get('aiEnrich') if prev_type == ftype else None))
+    if enrich_raw is not None:
+        ae = _clean_ai_enrich(enrich_raw)
+        if ae is None or ftype != 'ai_enrich':
+            return None
+        out['aiEnrich'] = ae
+    elif ftype == 'ai_enrich':
+        return None
+    # C3 (wave 34): the Agents module reads field agents off this bag. DERIVED here, inside the
+    # one validator both write doors run, so the binding can never drift from the config it
+    # describes — see `_field_agent_binding` for why it is computed rather than stored beside it.
+    # ⛔ It is written AFTER the generic `automation` passthrough above, so a caller cannot hand us
+    # a `field_agent` bag that disagrees with the column. Every OTHER automation bag is untouched.
+    if ftype == 'ai_enrich':
+        out['automation'] = _field_agent_binding(out)
     return out
 
 
@@ -2094,6 +2437,16 @@ def flow_bound(bag, st=None):
     lives in `aios_grid._clean_automation` — this guards the WRITE doors only.)"""
     if not isinstance(bag, dict):
         return True                        # no bag, no law — an ordinary column
+    # ⭐⭐ WAVE-34 (R13 / contract C3) — A FIELD AGENT IS BOUND BY ITS OWN COLUMN, NOT BY A FLOW,
+    # and without this arm the whole feature is unsavable. `_clean_field` stamps
+    # `{kind:'field_agent', ...}` on every `ai_enrich` column; `add_field` then asks this
+    # predicate, which read `flowId` and only `flowId` — so every AI enrichment column would have
+    # been refused at the create door by the guard for a different feature that happens to share
+    # the `automation` key. ⚠ The binding is REAL, not waived: the bag names the column it belongs
+    # to, and `_clean_field` derives that name from the field itself, so it cannot name a column
+    # that does not exist the way a stale `flowId` can name a deleted flow.
+    if bag.get('kind') == 'field_agent':
+        return bool(str(bag.get('field') or '').strip())
     flow = str(bag.get('flowId') or '').strip()
     if not flow:
         return False
@@ -2399,6 +2752,41 @@ def patch_cells(table_key, row_id, values, st=None):
     return True
 
 
+def patch_many_cells(table_key, updates, st=None):
+    """Write cells across MANY rows in ONE store update. Returns the number of rows touched.
+
+    ⛔ WHY THIS EXISTS RATHER THAN A LOOP OVER `patch_cells`, which is the same argument
+    `add_rows` makes one screen up: every write here is a read-modify-write of the WHOLE tenant
+    document, so filling a 1,000-row enrichment column row by row is 1,000 full-document copies
+    under one lock on the single uvicorn process this product runs. One `update()` writes them
+    all.
+
+    ⚠ `updates` is `{row_id: {field_key: value}}`, and a row id that does not exist is SKIPPED
+    rather than created: this is a cell writer, not an insert door, and inventing a row here would
+    let a stale plan resurrect a record somebody deleted mid-run.
+    """
+    if not is_user_table(table_key, st):
+        return 0
+    have = set((get(table_key, st) or {}).get('rows') or {})
+    clean = {str(r): {str(k): str(v) for k, v in (cells or {}).items()}
+             for r, cells in (updates or {}).items()
+             if str(r) in have and isinstance(cells, dict) and cells}
+    if not clean:
+        return 0
+
+    def _set(cur):
+        t = cur.get(str(table_key))
+        if t is not None:
+            rows = t.setdefault('rows', {})
+            for rid, cells in clean.items():
+                if rid in rows:
+                    rows[rid].update(cells)
+        return cur
+
+    _st(st).update(STORE_KEY, _set, flush='sync')
+    return len(clean)
+
+
 def patch_link_cell(table_key, row_id, fkey, value, st=None):
     """Persist one user-picked Link cell in the shared row and return its canonical id string.
 

web/src/assistant/AssistantPage.tsx

@@ -1,20 +1,81 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 import { QUERY_OPEN_EVENT, signal } from "../apiContract";
 import { FolderMark } from "../customer-grid/icons";
 import { queryCitationLabel } from "../customer-grid/queryPreview";
 import { retryEmit } from "../inbox/inboxModel";
+import { queryGroups, QueryRail } from "../query/queryParts";
 import { DbIcon } from "../shell/dbFrame";
-import { databaseEntries, QUERY_ROUTE } from "../shell/nav";
+import { ASSISTANT_ROUTE, databaseEntries, QUERY_ROUTE, routeKeyOf } from "../shell/nav";
 import type { NavEntry } from "../shell/nav";
 import {
-  deleteThread, fetchQueries, submitChat, type QueryCitation, type QueryIndex,
-  type QueryMessage, type SavedQuery,
+  deleteQuery, deleteThread, fetchQueries, rateMessage, submitChat, type QueryCitation,
+  type QueryIndex, type QueryMessage, type SavedQuery,
 } from "../query/queryApi";
 import "./assistant.css";
 
+/**
+ * ⭐ LAZY ON PURPOSE. `QueryPage` imports `CustomerGrid`, the largest module in the client; a
+ * static import here would put the whole grid in the chat bundle, so opening the Assistant to ask
+ * one question would download the surface it is merged WITH but not showing. The list itself
+ * comes from `queryParts`, which imports no grid, so the left panel renders in Query mode before
+ * this chunk arrives.
+ */
+const QueryWorkspace = lazy(() => import("../query/QueryPage"));
+
 export interface AssistantPageProps { granted: NavEntry[]; }
 
+/**
+ * ⭐⭐ R14 / CONTRACT C2 — ONE MODULE, ONE ROUTE, TWO LISTS. Owner, 2026-08-16: *"Combine the AI
+ * assistant module AND the Query module. In the secondary navigation at the top, just above
+ * '+ New chat', an easily accessible toggle between Chat / Query; the list below then shows either
+ * Chats or Queries."*
+ *
+ * The toggle changes WHICH LIST the left panel shows, never which route you are on: `#/assistant`
+ * serves both, and `#/query` redirects here carrying `?mode=query`.
+ */
+export type AssistantMode = "chat" | "query";
+const MODE_KEY = "aios-assistant-mode";
+const isMode = (value: unknown): value is AssistantMode => value === "chat" || value === "query";
+
+/**
+ * The hash wins on arrival, the stored choice answers a reload.
+ *
+ * `?mode=query` is the REDIRECT'S INSTRUCTION — somebody followed a `#/query` link or bookmark —
+ * and a preference stored days ago must not override the link just clicked. Everything else reads
+ * `localStorage`, which is what makes the choice survive a reload.
+ *
+ * ⚠ THE TOGGLE STILL DOES NOT WRITE THE HASH, AND THE REASON HAS CHANGED — corrected here rather
+ * than left, because a stale comment that later readers quote is this wave's own worst defect.
+ * It USED to be a hard constraint: `Shell.tsx::read` took the whole remainder of the hash as the
+ * route key, so writing `#/assistant?mode=query` resolved to no route and landed on Home. B's
+ * `routeKeyOf` splits on `?` now (NOTE B-8), so writing it would be safe. It is still not written,
+ * for a smaller reason: which LIST a panel shows is a preference, not a location, and the hash is
+ * B's to own. The arrival parameter is consumed once, below, and stored.
+ * Pure and exported so the decision can be checked without a browser.
+ */
+export function initialMode(hash: string, stored: string | null): AssistantMode {
+  const mark = hash.indexOf("?");
+  if (mark >= 0) {
+    const asked = new URLSearchParams(hash.slice(mark + 1)).get("mode");
+    if (isMode(asked)) return asked;
+  }
+  return isMode(stored) ? stored : "chat";
+}
+
+/** A private window refuses storage; that is a lost preference, never an error the reader sees. */
+function readMode(): AssistantMode {
+  if (typeof window === "undefined") return "chat";
+  let stored: string | null = null;
+  try { stored = window.localStorage.getItem(MODE_KEY); } catch { stored = null; }
+  return initialMode(window.location.hash, stored);
+}
+
+function storeMode(mode: AssistantMode): void {
+  if (typeof window === "undefined") return;
+  try { window.localStorage.setItem(MODE_KEY, mode); } catch { /* see readMode */ }
+}
+
 const KIND_LABEL: Record<string, string> = {
   grid: "table", list: "list", chart: "chart", kanban: "board", calendar: "calendar",
   timeseries: "time series", map: "map",
@@ -30,17 +91,42 @@ const KIND_LABEL: Record<string, string> = {
  * whatever the server sent — an unknown key falls through to itself rather than being hidden, so a
  * provider added server-side appears here the day it is added instead of the day someone
  * remembers to edit this file [[a-flag-can-ship-without-its-writer]].
+ *
+ * ⛔ `anthropic: "Claude"` AND `openai: "OpenAI"` ARE GONE, and the reason is worth keeping because
+ * the ticket that removed them described the defect backwards. They were never OFFERED: the picker
+ * renders `index.models`, which is `model_choices()` = `[auto, *QUERY_PROVIDER_ORDER]`, so no
+ * reader ever saw "Claude" in this control. They were labels for providers that do not exist in
+ * the platform ladder, i.e. dead weight, and the fall-through above already covers a provider
+ * added server-side. The REAL defect the ticket named lives one layer down and is fixed by
+ * `modelStatus`: a model that IS offered and whose key this deployment does not hold.
  */
 const MODEL_LABEL: Record<string, string> = {
   auto: "Auto", cerebras: "Cerebras", groq: "Groq", openrouter: "OpenRouter",
-  anthropic: "Claude", openai: "OpenAI",
 };
 const modelLabel = (key: string) => MODEL_LABEL[key] ?? key;
 
-/** Route to the exact Query-owned artefact. C owns the destination wiring, not this page. */
-export function openBuiltView(qid: string): () => void {
+/**
+ * Route to the exact Query-owned artefact. C owns the destination wiring, not this page.
+ *
+ * ⭐ `hosted` is R14's one change and it is a NAVIGATION suppressor, not a second path: when this
+ * surface is itself showing Query, there is nowhere to route TO — the workspace is already mounted
+ * in the main column — and setting the hash would send the reader to the standalone route we just
+ * merged away from. The qid contract is unchanged either way, which is the point: the same public
+ * hand-off answers an external link and an in-page click, so Query keeps ONE selection door.
+ * ⚠ The retry ladder still earns its keep here: the hosted workspace is lazy, so the event can
+ * fire before its chunk has finished loading and its listener exists.
+ */
+export function openBuiltView(qid: string, hosted = false): () => void {
   if (typeof window === "undefined") return () => {};
-  if (window.location.hash.replace(/^#\/?/, "") !== QUERY_ROUTE) window.location.hash = `#/${QUERY_ROUTE}`;
+  // ⛔ `routeKeyOf`, NOT `hash.replace(...)` (B's NOTE B-14). Since T15 the hash is
+  // `#/assistant?mode=query`, so the whole-remainder idiom yields the key `assistant?mode=query`,
+  // which is never `query` — the guard was permanently true and its intent ("do not navigate, we
+  // are already there") had become unsatisfiable by any hash. Latent rather than live, because the
+  // one caller passes `hosted`, and fixed rather than left because a guard that cannot be
+  // satisfied is the kind a later reader trusts.
+  if (!hosted && routeKeyOf(window.location.hash) !== QUERY_ROUTE) {
+    window.location.hash = `#/${QUERY_ROUTE}`;
+  }
   return retryEmit(() => signal(QUERY_OPEN_EVENT, { qid }));
 }
 
@@ -54,10 +140,25 @@ export function CitationLine({ citation }: { citation: QueryCitation }) {
   return <a className="as-citation" href={citation.href}>{queryCitationLabel(citation)}</a>;
 }
 
-export function AssistantMessage({ message, view, citations, onPreview }: {
+/** One glyph, drawn once and turned over for the other. R20 asked for thumbs; these are thumbs. */
+function ThumbIcon({ down = false }: { down?: boolean }) {
+  return (
+    <svg viewBox="0 0 16 16" aria-hidden="true" width="13" height="13"
+      {...(down ? { transform: "rotate(180)" } : {})}>
+      <path d="M5.6 14.2V6.9h1.5l2.2-4.3a1 1 0 0 1 1.8.9l-.7 2.6h2.4a1 1 0 0 1 1 1.3l-1.1 4.6a1.5 1.5 0 0 1-1.5 1.1H5.6z" />
+      <path d="M5.6 6.9H2.6v7.3h3" />
+    </svg>
+  );
+}
+
+export function AssistantMessage({ message, view, citations, onPreview, onRate }: {
   message: QueryMessage; view?: SavedQuery; citations: QueryCitation[]; onPreview: (id: string) => void;
+  /** Optional so the message can be rendered outside a live conversation without a rating door. */
+  onRate?: (id: string, rating: "up" | "down" | null, reason?: string) => void;
 }) {
   const [openSources, setOpenSources] = useState(false);
+  const [askWhy, setAskWhy] = useState(false);
+  const [why, setWhy] = useState("");
   const matching = citations.filter((citation) => (message.citationIds || []).includes(citation.id));
   if (message.role === "user") {
     return (
@@ -85,6 +186,38 @@ export function AssistantMessage({ message, view, citations, onPreview }: {
           <span className="as-preview-meta">{`Open the ${KIND_LABEL[view.kind] ?? view.kind} in Query`}</span>
         </button>
       ) : null}
+      {/* ⚠ The thumbs are NOT a survey: the server reads a thumbs-down back into the next turn of
+          this thread. That is why a down asks for one short reason and why both are clearable. */}
+      {onRate ? (
+        <div className="as-rate">
+          <button type="button" aria-label="Helpful" aria-pressed={message.rating === "up"}
+            className={"as-rate-btn" + (message.rating === "up" ? " is-on" : "")}
+            onClick={() => { setAskWhy(false); onRate(message.id, message.rating === "up" ? null : "up"); }}>
+            <ThumbIcon />
+          </button>
+          <button type="button" aria-label="Not helpful" aria-pressed={message.rating === "down"}
+            className={"as-rate-btn" + (message.rating === "down" ? " is-on" : "")}
+            onClick={() => {
+              if (message.rating === "down") { setAskWhy(false); onRate(message.id, null); return; }
+              setAskWhy(true); onRate(message.id, "down");
+            }}>
+            <ThumbIcon down />
+          </button>
+          {message.rating === "down" && !askWhy && message.ratingReason ? (
+            <span className="as-rate-why-said">{message.ratingReason}</span>
+          ) : null}
+        </div>
+      ) : null}
+      {onRate && askWhy && message.rating === "down" ? (
+        <form className="as-rate-why" onSubmit={(event) => {
+          event.preventDefault(); setAskWhy(false); onRate(message.id, "down", why.trim());
+        }}>
+          <input className="as-rate-input" value={why} aria-label="What was wrong"
+            placeholder="What was wrong? Optional."
+            onChange={(event) => setWhy(event.currentTarget.value)} />
+          <button type="submit" className="as-rate-send">Send</button>
+        </form>
+      ) : null}
       {matching.length ? (
         <div className="as-sources">
           <button type="button" className="as-sources-btn" aria-expanded={openSources}
@@ -103,7 +236,8 @@ export function AssistantMessage({ message, view, citations, onPreview }: {
 }
 
 function initialIndex(): QueryIndex {
-  return { threads: [], messages: [], views: [], citations: [], models: ["auto"], sources: [] };
+  return { threads: [], messages: [], views: [], citations: [], models: ["auto"],
+           modelStatus: [], sources: [] };
 }
 
 /**
@@ -147,8 +281,14 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
   const [problem, setProblem] = useState("");
   const [loaded, setLoaded] = useState(false);
   const [confirmThread, setConfirmThread] = useState("");
+  const [mode, setMode] = useState<AssistantMode>(readMode);
+  const [activeQuery, setActiveQuery] = useState("");
+  /** Bumped on delete so the hosted workspace's own copy of the list cannot go stale behind us. */
+  const [queryRefresh, setQueryRefresh] = useState(0);
   const openCancel = useRef<(() => void) | null>(null);
   const foot = useRef<HTMLDivElement | null>(null);
+  /** A counter, not a random id: the optimistic message only has to be unique within this page. */
+  const pending = useRef(0);
 
   const databases = useMemo(() => databaseEntries(granted).filter((entry) => entry.kind !== "group"), [granted]);
   const labels = useMemo(() => new Map(databases.map((entry) => [entry.key, entry.label])), [databases]);
@@ -171,12 +311,24 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
   const messages = index.messages.filter((row) => row.threadId === activeThread);
   const viewById = useMemo(() => new Map(index.views.map((view) => [view.id, view])), [index.views]);
 
+  /** Offered is not callable: a model whose key this deployment does not hold says so, and why. */
+  const modelBlocked = useCallback((key: string) => {
+    const row = index.modelStatus.find((item) => item.model === key);
+    return row && row.available === false
+      ? row.reason || "this model is not available on this deployment" : "";
+  }, [index.modelStatus]);
+
   const reload = useCallback(async () => {
     const result = await fetchQueries();
     setLoaded(true);
     if (result.ok) {
       setIndex(result.value);
-      setModel((current) => result.value.models.includes(current) ? current : "auto");
+      // ⚠ Falls back to Auto when the SELECTED model is offered but not callable, not only when it
+      // has left the list: a stored thread can restore a model whose key was removed since, and a
+      // disabled option the picker cannot clear is a control that refuses its own value.
+      const callable = (key: string) => result.value.models.includes(key)
+        && result.value.modelStatus.every((row) => row.model !== key || row.available);
+      setModel((current) => callable(current) ? current : "auto");
     }
   }, []);
 
@@ -190,6 +342,62 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
   // The conversation reads bottom-up, like every chat the owner named.
   useEffect(() => { foot.current?.scrollIntoView({ block: "end" }); }, [messages.length, busy]);
 
+  /**
+   * The `?mode=` the redirect carried has been read into state; drop it so a toggle made later is
+   * not overridden by a stale parameter on the next reload. `replaceState` does NOT fire
+   * `hashchange`, so the shell never re-resolves the route and nothing flickers.
+   *
+   * ⛔ AND IT IS STORED IN THE SAME BREATH, WHICH IS THE HALF THAT WAS MISSING. `useState(readMode)`
+   * reads the hash and writes NOTHING; only `pickMode` persists. So a reader who arrived in Query
+   * by following a `#/query` link, never touching the toggle, would have the parameter stripped
+   * here and then land back in Chat on the next reload, restored from a choice made days earlier.
+   * Following the link IS choosing.
+   */
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.location.hash.includes("?")) return;
+    storeMode(mode);
+    window.history.replaceState(null, "", `#/${ASSISTANT_ROUTE}`);
+    // `mode` is read once, at mount, on purpose: this effect exists to consume the arrival
+    // parameter, not to mirror every later toggle (`pickMode` already does that).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const pickMode = useCallback((next: AssistantMode) => {
+    setMode(next); storeMode(next); setProblem("");
+  }, []);
+
+  /** The saved Query views, grouped exactly as the standalone page groups them (ONE function). */
+  const queryList = useMemo(() => queryGroups(index.views, databases), [index.views, databases]);
+
+  const selectQuery = useCallback((qid: string) => {
+    setActiveQuery(qid);
+    openCancel.current?.();
+    openCancel.current = openBuiltView(qid, true);
+  }, []);
+
+  /** A renamed or duplicated artefact, merged in place, and the hosted workspace told to re-read. */
+  const upsertQuery = useCallback((view: SavedQuery) => {
+    setIndex((current) => ({
+      ...current, views: [view, ...current.views.filter((row) => row.id !== view.id)],
+    }));
+    setQueryRefresh((count) => count + 1);
+  }, []);
+
+  const removeQuery = useCallback(async (qid: string) => {
+    const result = await deleteQuery(qid);
+    if (!result.ok) { setProblem(result.message); return; }
+    setIndex((current) => ({ ...current, views: current.views.filter((row) => row.id !== qid) }));
+    setActiveQuery((current) => (current === qid ? "" : current));
+    setQueryRefresh((count) => count + 1);
+  }, []);
+
+  /** Arriving in Query with nothing chosen selects the newest view of the first database. */
+  useEffect(() => {
+    if (mode !== "query" || activeQuery) return;
+    const first = queryList[0]?.views[0];
+    if (first) selectQuery(first.id);
+  }, [mode, activeQuery, queryList, selectQuery]);
+
   const newChat = useCallback(() => {
     setActiveThread(""); setQuestion(""); setProblem("");
   }, []);
@@ -202,8 +410,8 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
     const permitted = databases.map((entry) => entry.key);
     const sources = (row.sources || []).filter((key) => permitted.includes(key));
     if (sources.length) { setSelected(sources); setTarget(sources[0]); }
-    if (row.model && index.models.includes(row.model)) setModel(row.model);
-  }, [databases, index.models, index.threads]);
+    if (row.model && index.models.includes(row.model) && !modelBlocked(row.model)) setModel(row.model);
+  }, [databases, index.models, index.threads, modelBlocked]);
 
   const toggleSource = useCallback((key: string) => {
     if (blockedReason(key)) return;
@@ -214,20 +422,48 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
     });
   }, [blockedReason]);
 
+  /**
+   * ⭐⭐ R16 — ENTER GOES TO THE CHAT, NOT TO A WAIT. Owner: *"Pressing enter goes immediately to
+   * the chat view showing that it is loading; there is a thinking animation."*
+   *
+   * This used to POST and only then touch `index`, so for the whole model call the reader sat on
+   * the opening screen looking at their own unsent sentence with nothing moving. The message is
+   * appended FIRST, which is what flips `empty` and hands the surface to the stream; `busy` then
+   * draws the app's one loading mark under it.
+   *
+   * ⛔ THE INVERSE IS CAPTURED BEFORE THE WRITE. An optimistic append that is not reconciled on
+   * failure leaves a message on screen the server never received, and the next turn replays it to
+   * the model as if it had [[undo-capture-before-the-write]]. The typed text goes back in the
+   * composer too: losing somebody's sentence to a failed request is the second injury.
+   */
   const ask = useCallback(async () => {
     const text = question.trim();
     if (!text || !target || !selected.includes(target) || busy) return;
-    setBusy(true); setProblem("");
+    const pendingId = `pending_${(pending.current += 1)}`;
+    const optimistic: QueryMessage = {
+      id: pendingId, threadId: activeThread, role: "user", content: text,
+      createdAt: new Date().toISOString(), targetDatabase: target,
+      sources: selected, requestedModel: model,
+    };
+    const withoutPending = (rows: QueryMessage[]) => rows.filter((row) => row.id !== pendingId);
+    setBusy(true); setProblem(""); setQuestion("");
+    setIndex((current) => ({ ...current, messages: [...current.messages, optimistic] }));
     const result = await submitChat({ question: text, database: target, sources: selected,
       ...(activeThread ? { threadId: activeThread } : {}), model });
     setBusy(false);
-    if (!result.ok) { setProblem(result.message); return; }
-    setQuestion("");
+    if (!result.ok) {
+      setIndex((current) => ({ ...current, messages: withoutPending(current.messages) }));
+      setQuestion(text);
+      setProblem(result.message);
+      return;
+    }
     setActiveThread(result.value.thread.id);
     setIndex((current) => ({
       ...current,
       threads: [result.value.thread, ...current.threads.filter((row) => row.id !== result.value.thread.id)],
-      messages: [...current.messages, result.value.userMessage, result.value.message],
+      // The server's own copy of the question replaces the optimistic one, so a thread never holds
+      // two of the same turn and the id the rest of the page keys on is the durable one.
+      messages: [...withoutPending(current.messages), result.value.userMessage, result.value.message],
       views: result.value.view ? [result.value.view, ...current.views.filter((row) => row.id !== result.value.view?.id)] : current.views,
       citations: [...current.citations, ...result.value.citations],
     }));
@@ -246,11 +482,26 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
     setConfirmThread("");
   }, []);
 
-  const preview = useCallback((qid: string) => {
-    openCancel.current?.();
-    openCancel.current = openBuiltView(qid);
+  /**
+   * The rating goes to the server and the SERVER'S copy comes back, rather than the page patching
+   * its own guess: the reason is normalised and cleared there, and a rating that only looked
+   * applied is exactly the shape this module keeps being bitten by.
+   */
+  const rate = useCallback(async (id: string, rating: "up" | "down" | null, reason?: string) => {
+    const result = await rateMessage(id, rating, reason);
+    if (!result.ok) { setProblem(result.message); return; }
+    setIndex((current) => ({
+      ...current,
+      messages: current.messages.map((row) => (row.id === id ? result.value : row)),
+    }));
   }, []);
 
+  /** A built view opens WHERE THE READER ALREADY IS: the toggle flips, the list follows. */
+  const preview = useCallback((qid: string) => {
+    pickMode("query");
+    selectQuery(qid);
+  }, [pickMode, selectQuery]);
+
   const empty = messages.length === 0;
   const composer = (
     <div className="as-composer">
@@ -274,9 +525,15 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
             <span className="as-pick-label">Model</span>
             <select className="as-pick-select" value={model} aria-label="Model"
               onChange={(event) => setModel(event.currentTarget.value)}>
-              {index.models.map((choice) => (
-                <option key={choice} value={choice}>{modelLabel(choice)}</option>
-              ))}
+              {index.models.map((choice) => {
+                const blocked = modelBlocked(choice);
+                return (
+                  <option key={choice} value={choice} disabled={!!blocked}
+                    title={blocked || undefined}>
+                    {blocked ? `${modelLabel(choice)} (not configured)` : modelLabel(choice)}
+                  </option>
+                );
+              })}
             </select>
           </label>
           {/* ⚠ ONLY WHEN THE ANSWER IS AMBIGUOUS. Every generated view names ONE database (R3);
@@ -338,6 +595,23 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
     <div className="as-chat" aria-label="AI assistant">
       {/* Airtable's panel: one door to a new chat, then the history. */}
       <aside className="as-history">
+        {/* C2: two values, directly ABOVE "+ New chat". It changes which LIST shows, not the route. */}
+        <div className="as-mode-toggle" role="tablist" aria-label="Chat or Query">
+          {(["chat", "query"] as const).map((value) => (
+            <button type="button" key={value} role="tab" aria-selected={mode === value}
+              className={"as-mode" + (mode === value ? " is-on" : "")}
+              onClick={() => pickMode(value)}>
+              {value === "chat" ? "Chat" : "Query"}
+            </button>
+          ))}
+        </div>
+        {mode === "query" ? (
+          /* The SAME rail the standalone page renders; only its host changed, so the differences
+             are CSS in assistant.css and nothing here. */
+          <QueryRail groups={queryList} activeId={activeQuery} onSelect={selectQuery}
+            onDelete={(id) => void removeQuery(id)} onChanged={upsertQuery} />
+        ) : (
+        <>
         <button type="button" className="as-new" onClick={newChat}>
           <svg viewBox="0 0 16 16" aria-hidden="true" width="14" height="14">
             <path d="M8 3.5v9M3.5 8h9" />
@@ -367,9 +641,27 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
             <p className="as-thread-empty">No chats yet.</p>
           ) : null}
         </nav>
+        </>
+        )}
       </aside>
       <main className="as-conversation">
-        {empty ? (
+        {mode === "query" ? (
+          queryList.length ? (
+            <Suspense fallback={<p className="as-working" role="status">
+              <span className="lp-spin" aria-hidden="true" />
+            </p>}>
+              <QueryWorkspace granted={granted} hostedRail refreshToken={queryRefresh}
+                selectedId={activeQuery} />
+            </Suspense>
+          ) : (
+            <div className="as-opening">
+              <h1 className="as-opening-h">No Query views yet</h1>
+              <p className="as-opening-p">
+                Ask a question in Chat. When the assistant builds a view, it is saved here.
+              </p>
+            </div>
+          )
+        ) : empty ? (
           <div className="as-opening">
             <h1 className="as-opening-h">How can I help?</h1>
             <p className="as-opening-p">
@@ -385,10 +677,16 @@ export default function AssistantPage({ granted }: AssistantPageProps) {
                 {messages.map((message) => (
                   <AssistantMessage key={message.id} message={message}
                     view={message.viewId ? viewById.get(message.viewId) : undefined}
-                    citations={index.citations} onPreview={preview} />
+                    citations={index.citations} onPreview={preview}
+                    onRate={message.role === "assistant" && !message.id.startsWith("pending_")
+                      ? rate : undefined} />
                 ))}
+                {/* R16's thinking animation is the app's ONE loading mark, not a second spinner
+                    vocabulary: `.lp-spin` is the same mark every surface uses and C is repainting
+                    it in the brand purple this wave. The label is for screen readers only, since
+                    an aria-hidden spinner inside a status region announces nothing. */}
                 {busy ? (
-                  <p className="as-working" role="status">
+                  <p className="as-working" role="status" aria-label="The assistant is thinking">
                     <span className="lp-spin" aria-hidden="true" />
                   </p>
                 ) : null}

web/src/assistant/assistant.css

@@ -40,6 +40,60 @@
   overflow: hidden;
 }
 
+/* ── R14 / C2: the Chat / Query toggle, directly above New chat ───────────── */
+
+.as-mode-toggle {
+  flex: 0 0 auto;
+  display: flex;
+  gap: 2px;
+  margin-bottom: 10px;
+  padding: 2px;
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface-2);
+}
+
+.as-mode {
+  flex: 1 1 0;
+  min-width: 0;
+  min-height: 26px;
+  padding: 4px 8px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--lp-muted);
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.as-mode:hover { color: var(--lp-ink); }
+.as-mode.is-on { background: var(--lp-surface); color: var(--lp-ink); }
+
+/* The Query list is the SAME `QueryRail` the standalone page renders — only its host changed.
+   These are the overrides a rail needs when it is nested inside a panel that is already one rail
+   wide: it must FILL that panel rather than claim a second `--lp-rail-w` beside it, and it must
+   not draw a second divider against the one `.as-history` already has.
+   `.qy-rail-ask` goes because it links to the Assistant, which is the surface it is now inside. */
+.as-history .qy-rail {
+  flex: 1 1 auto;
+  width: auto;
+  min-width: 0;
+  height: auto;
+  min-height: 0;
+  padding: 0;
+  border-right: 0;
+}
+
+.as-history .qy-rail-ask { display: none; }
+
+/* Query fills the conversation column while the toggle is on Query. */
+.as-conversation > .shell-db-frame,
+.as-conversation > .qy-empty {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
 .as-new {
   flex: 0 0 auto;
   display: flex;
@@ -285,6 +339,80 @@
 .as-preview-name { color: var(--lp-ink); font-size: var(--lp-fs-xs); font-weight: 600; }
 .as-preview-meta { color: var(--lp-blue-solid); font-size: var(--lp-fs-2xs); font-weight: 600; }
 
+/* ── R20: the thumbs, which the server reads back into the next turn ───────── */
+
+.as-rate {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  margin-top: 10px;
+}
+
+.as-rate-btn {
+  width: 26px;
+  height: 26px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--lp-muted);
+  cursor: pointer;
+}
+
+.as-rate-btn svg {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.3;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.as-rate-btn:hover { background: var(--lp-surface-2); color: var(--lp-ink); }
+.as-rate-btn.is-on { background: var(--lp-blue-tint); color: var(--lp-blue-solid); }
+
+.as-rate-why-said {
+  margin-left: 4px;
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-2xs);
+}
+
+.as-rate-why {
+  display: flex;
+  gap: 6px;
+  margin-top: 6px;
+}
+
+.as-rate-input {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 6px 10px;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface);
+  color: var(--lp-ink);
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+}
+
+.as-rate-input:focus { outline: none; border-color: var(--lp-blue-solid); }
+
+.as-rate-send {
+  flex: 0 0 auto;
+  padding: 6px 12px;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface);
+  color: var(--lp-ink);
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.as-rate-send:hover { background: var(--lp-surface-2); }
+
 .as-sources { margin-top: 8px; }
 
 .as-sources-btn {

web/src/automation/AutomationChat.tsx

@@ -0,0 +1,251 @@
+// ---------------------------------------------------------------------------
+// automation/AutomationChat.tsx — the Chat view of the Agent module (R17).
+//
+// Owner, ruling R17: *"The Agent module needs a Chat view beside the builder, where the user asks
+// the AI to build the automation."*
+//
+// ⛔⛔ WHAT THIS IS NOT: a second way to save an automation. `POST /automations/draft` writes
+// NOTHING and says so on the wire (`saved: false`); accepting a draft is the ordinary
+// `POST /automations` that the Canvas already uses. That is R3's *"indistinguishable from a
+// hand-built one"* achieved by there being ONE write path, not two that look alike. If a future
+// change makes this component write directly, that property is gone and nothing will report it.
+//
+// ⛔ AND `dropped` IS RENDERED, ALWAYS. The route runs the real save-door validator over the
+// model's answer and diffs it, because `clean_actions` discards an unrecognised config key and
+// still answers 200. Every entry is something the reader was SHOWN that will not survive the
+// save. Hiding it would make the Canvas disagree with the transcript that produced it, which is
+// the exact complaint D-75 was opened for.
+// ---------------------------------------------------------------------------
+import { useCallback, useRef, useState } from "react";
+
+import type { AutomationDraft } from "./automationApi";
+import { AutomationError, draftAutomation } from "./automationApi";
+import "./automation.css";
+
+/**
+ * One turn. `error` is a KIND of message rather than a separate banner, because a failed turn is
+ * part of the conversation a person is having: they will rephrase and try again, and a toast that
+ * has already faded cannot be re-read while they do.
+ */
+interface Turn {
+  who: "you" | "agent";
+  text: string;
+  error?: boolean;
+  dropped?: string[];
+}
+
+export interface AutomationChatProps {
+  /** Applied to the Canvas when the reader accepts. Returns once the write has been attempted. */
+  onAccept: (draft: AutomationDraft["draft"]) => Promise<void> | void;
+  /** The automation being edited, for the empty state's sentence. */
+  name?: string;
+}
+
+/** How many steps a draft may carry before the accept bar states the number rather than implying
+ *  it. Not a limit — a limit here would be a second, quieter copy of the server's. */
+const MANY_STEPS = 6;
+
+export default function AutomationChat({ onAccept, name }: AutomationChatProps) {
+  const [turns, setTurns] = useState<Turn[]>([]);
+  const [text, setText] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [pending, setPending] = useState<AutomationDraft["draft"] | null>(null);
+  const [applying, setApplying] = useState(false);
+  const logRef = useRef<HTMLDivElement | null>(null);
+
+  const scrollDown = useCallback(() => {
+    // The transcript grows at the bottom, so a reader who has just sent something expects to be
+    // there. `requestAnimationFrame` because the row is appended in the same commit.
+    requestAnimationFrame(() => {
+      const el = logRef.current;
+      if (el) el.scrollTop = el.scrollHeight;
+    });
+  }, []);
+
+  const ask = useCallback(async () => {
+    const prompt = text.trim();
+    if (!prompt || busy) return;
+    /*
+     * ⭐ THE USER'S LINE GOES UP FIRST AND THE COMPOSER CLEARS FIRST. Waiting for the server to
+     * echo it is what makes a chat feel broken: the reader presses enter, the text sits in the
+     * box, and they press it again. Same reasoning as R16's clause for the Assistant.
+     * ⚠ The optimistic row is never RECONCILED away on failure — it genuinely happened, they
+     * genuinely said it — so the failure arrives as the NEXT turn rather than by deleting theirs.
+     */
+    setTurns((t) => [...t, { who: "you", text: prompt }]);
+    setText("");
+    setBusy(true);
+    scrollDown();
+    try {
+      const res = await draftAutomation(prompt);
+      const actions = res.draft?.actions || [];
+      const label = res.draft?.name ? `"${res.draft.name}"` : "a flow";
+      setTurns((t) => [...t, {
+        who: "agent",
+        text: actions.length
+          ? `I drafted ${label} with ${actions.length} step${actions.length === 1 ? "" : "s"}. `
+            + "Nothing is saved yet. Read it below and put it on the Canvas if it is right."
+          : `I could not turn that into steps. Try naming the database and what should happen.`,
+        // ⚠ BOTH CHANNELS, and they are different questions. `dropped` is what the SAVE-DOOR
+        // validator discarded from the model's answer; `notes` is what the ROUTE corrected or
+        // could not keep (a trigger this deployment does not have, steps past the draft cap).
+        // Rendering only one of them shows a person half of what changed under them.
+        // ⛔ `dropped` IS `{kind, keys}`, NOT A SENTENCE. Spreading it into a string list
+        // compiled and would have painted `[object Object]` on the one line that exists to say
+        // what changed under the reader. It is turned into words HERE, once.
+        ...(res.dropped?.length || res.notes?.length
+          ? {
+              dropped: [
+                ...(res.dropped || []).map(
+                  (d) => `on the ${d.kind} step: ${(d.keys || []).join(", ")}`
+                ),
+                ...(res.notes || []),
+              ],
+            }
+          : {}),
+      }]);
+      setPending(actions.length ? res.draft : null);
+    } catch (e) {
+      /*
+       * ⛔ THE SERVER'S OWN SENTENCE, NEVER A GENERIC ONE. The route answers 400 with one plain
+       * sentence saying WHY it refused (no prompt, nothing draftable, a kind this deployment
+       * cannot run) and that sentence is the only useful thing on the screen. Replacing it with
+       * "something went wrong" would throw away the one part a person can act on.
+       */
+      setTurns((t) => [...t, {
+        who: "agent",
+        error: true,
+        text: e instanceof AutomationError
+          ? e.message
+          : "The agent service did not answer. Try again in a moment.",
+      }]);
+      setPending(null);
+    } finally {
+      setBusy(false);
+      scrollDown();
+    }
+  }, [text, busy, scrollDown]);
+
+  const accept = useCallback(async () => {
+    if (!pending || applying) return;
+    setApplying(true);
+    try {
+      await onAccept(pending);
+      setPending(null);
+      setTurns((t) => [...t, {
+        who: "agent",
+        text: "Put it on the Canvas. Edit it there like any other agent.",
+      }]);
+    } catch (e) {
+      setTurns((t) => [...t, {
+        who: "agent",
+        error: true,
+        text: e instanceof AutomationError ? e.message : "That draft could not be applied.",
+      }]);
+    } finally {
+      setApplying(false);
+      scrollDown();
+    }
+  }, [pending, applying, onAccept, scrollDown]);
+
+  const steps = pending?.actions?.length || 0;
+
+  return (
+    <div className="autoc-chat">
+      <div className="autoc-log" ref={logRef}>
+        {!turns.length ? (
+          <p className="autoc-empty">
+            Describe what {name ? `"${name}"` : "this agent"} should do and the assistant will
+            draft the steps. Name the database and what should happen, for example: when a new row
+            is added, look up its website and fill in the company size.
+          </p>
+        ) : null}
+        {turns.map((t, i) => (
+          <div key={i} className="autoc-turn">
+            <div
+              className={
+                "autoc-msg " + (t.error ? "is-error" : t.who === "you" ? "is-you" : "is-agent")
+              }
+            >
+              {t.text}
+            </div>
+            {/* R6's second sentence, on screen: what the validator would not keep, named. */}
+            {t.dropped?.length ? (
+              <div className="autoc-dropped">
+                Some of what it asked for will not be kept:
+                <ul>
+                  {t.dropped.map((d, j) => (
+                    <li key={j}>{d}</li>
+                  ))}
+                </ul>
+              </div>
+            ) : null}
+          </div>
+        ))}
+        {busy ? (
+          <div className="autoc-pending" role="status">
+            {/* ⚠ `.lp-spin` is the ONE loading mark in this application and it is purple as of
+                this wave. A second spinner vocabulary in a new surface is how an app stops
+                having one. */}
+            <span className="lp-spin" aria-hidden="true" />
+            Drafting the steps
+          </div>
+        ) : null}
+      </div>
+
+      {pending ? (
+        <div className="autoc-accept">
+          <span className="autoc-accept-note">
+            {steps} step{steps === 1 ? "" : "s"} drafted
+            {steps > MANY_STEPS ? ", which is a long flow. Read it before you accept." : "."}{" "}
+            Nothing is saved until you put it on the Canvas.
+          </span>
+          <button
+            type="button"
+            className="auto-btn"
+            disabled={applying}
+            onClick={() => setPending(null)}
+          >
+            Discard
+          </button>
+          <button
+            type="button"
+            className="auto-btn is-primary"
+            disabled={applying}
+            onClick={() => void accept()}
+          >
+            {applying ? "Adding" : "Put it on the Canvas"}
+          </button>
+        </div>
+      ) : null}
+
+      <div className="autoc-compose">
+        <textarea
+          className="autoc-input"
+          rows={2}
+          value={text}
+          placeholder="Describe what this agent should do"
+          aria-label="Describe what this agent should do"
+          disabled={busy}
+          onChange={(e) => setText(e.target.value)}
+          onKeyDown={(e) => {
+            // Enter sends; shift+enter is a newline. The composer is two rows tall because these
+            // descriptions are sentences, not search terms.
+            if (e.key === "Enter" && !e.shiftKey) {
+              e.preventDefault();
+              void ask();
+            }
+          }}
+        />
+        <button
+          type="button"
+          className="auto-btn is-primary"
+          disabled={busy || !text.trim()}
+          onClick={() => void ask()}
+        >
+          Send
+        </button>
+      </div>
+    </div>
+  );
+}

web/src/automation/AutomationDetail.tsx

@@ -23,7 +23,18 @@
 import { useCallback, useEffect, useState } from "react";
 
 import AutomationBuilder from "./AutomationBuilder";
+// ⭐ WAVE 34 · W34-T41/T42 (R17) — the Chat view. A STATIC import, deliberately, unlike
+// `AutomationSurface`'s `lazy()` of this file: that one exists because the editor is 88 KB behind
+// a rail that must paint first, while this component is small and is reached by a tab click on a
+// surface already loaded. A second lazy boundary here would buy a spinner, not a page.
+import AutomationChat from "./AutomationChat";
 import AutomationFind from "./AutomationFind";
+// ⚠ IMPORTED HERE TOO, and not only by `AutomationChat`. This file's own run-log disclosure
+// (`.autor-*`, W34-T45) lives in that sheet, and relying on a SIBLING component's import to pull
+// it in would mean the rules arrive only while that sibling is in the bundle. Today it always is
+// (a static import); the day somebody makes the chat lazy, the run log would silently lose its
+// styling with nothing red anywhere. CSS imports are idempotent, so the cost is zero.
+import "./automation.css";
 import AutomationTrigger from "./AutomationTrigger";
 import type {
   ActionCatalogRow,
@@ -338,6 +349,42 @@ export default function AutomationDetail({
    * setting, and `aria-pressed` on each would tell a screen reader about two independent
    * toggles that can both be off — a state this control cannot express.
    */
+  /**
+   * ⭐⭐ WAVE 34 · W34-T41 / R17 — CANVAS | CHAT, the surface's own view switch.
+   *
+   * Owner: *"The Agent module needs a Chat view beside the builder, where the user asks the AI to
+   * build the automation. Rename Builder to Canvas."*
+   *
+   * ⛔ THERE WAS NO SWITCH TO RENAME. `.auto-head-title` held a DEAD
+   * `<span className="autox-view is-on">Builder</span>` — no state, no handler, no second arm —
+   * left behind when `AutomationBoard.tsx` was deleted (its stub is still commented in
+   * `automation_engine.py`). The ticket's own `how:` calls it "a MODE inside AutomationSurface",
+   * which has not been true for two waves. So this is built, not renamed.
+   * ⭐ AND IT NEEDS NO NEW CSS. `.autox-views` was a complete rule with ZERO call sites and
+   * `.autox-view` (with `:hover`, `.is-on`, `:focus-visible`) had exactly one, the dead span — the
+   * strip was styled a wave before it was cancelled. Reusing it also means the two arms cannot
+   * drift from the rest of the module's chrome.
+   * ⚠ SAME RADIOGROUP REASONING as `panelTabs` below, for the same reason: two values of ONE
+   * setting, so `aria-pressed` on each would describe two toggles that can both be off.
+   */
+  const [view, setView] = useState<"canvas" | "chat">("canvas");
+  const viewTabs = (
+    <div className="autox-views" role="radiogroup" aria-label="Editor view">
+      {([["canvas", "Canvas"], ["chat", "Chat"]] as const).map(([k, label]) => (
+        <button
+          key={k}
+          type="button"
+          role="radio"
+          aria-checked={view === k}
+          className={"autox-view" + (view === k ? " is-on" : "")}
+          onClick={() => setView(k)}
+        >
+          {label}
+        </button>
+      ))}
+    </div>
+  );
+
   const panelTabs = (
     <div className="auto-paneltabs" role="radiogroup" aria-label="Right-hand panel">
       {([["properties", "Properties"], ["runs", "Run history"]] as const).map(([k, label]) => (
@@ -556,7 +603,7 @@ export default function AutomationDetail({
   const heldNote = (): string => {
     const held = heldCount();
     if (held < 1) return "";
-    return `Saved — ${held} condition${held === 1 ? " was" : "s were"} not saved yet, `
+    return `Saved. ${held} condition${held === 1 ? " was" : "s were"} not saved yet, `
       + `${held === 1 ? "it needs" : "they need"} a value.`;
   };
 
@@ -815,7 +862,7 @@ export default function AutomationDetail({
       setMessage(
         held < 1
           ? "Started. The node dots follow it."
-          : `Started — running without ${held} condition${held === 1 ? "" : "s"} that still `
+          : `Started. Running without ${held} condition${held === 1 ? "" : "s"} that still `
             + `${held === 1 ? "needs" : "need"} a value.`
       );
       await onSaved(automation.id);
@@ -1127,7 +1174,9 @@ export default function AutomationDetail({
                       </select>
                     </div>
                     <div className="auto-field">
-                      <label htmlFor="auto-fieldkey">Automation column</label>
+                      {/* ⭐ WAVE 34 · R12 — "Automation column" became "Agent column". It names
+                          the column THIS one writes into, so it takes the singular. */}
+                      <label htmlFor="auto-fieldkey">Agent column</label>
                       <select
                         id="auto-fieldkey"
                         className="auto-input"
@@ -1306,9 +1355,7 @@ export default function AutomationDetail({
           automation's. See the dated amendment under C-DETAIL: the contract's premise was wrong
           on that point and the consequence (no name in the Board view) is booked, not patched.
         */}
-        <div className="auto-head-title">
-          <span className="autox-view is-on">Builder</span>
-        </div>
+        <div className="auto-head-title">{viewTabs}</div>
         <div className="auto-head-actions">
           {/*
             ⭐ W24-W1 — WHAT IT IS DOING, beside the button that started it. This is the whole of
@@ -1352,7 +1399,23 @@ export default function AutomationDetail({
           >
             {saving ? "Saving…" : "Save"}
           </button>
-          <button type="button" className="auto-btn is-danger" onClick={() => void remove()}>
+          {/* ⭐⭐ WAVE 34 · CONTRACTS C3 + C4 — A SYSTEM AGENT SAYS SO ON THE ITEM, NOT ON THE
+              CLICK. The server refuses `409 system_agent` whatever this renders, so the wall is
+              never the disabling — but leaving a live-looking Delete that answers with a telling
+              off is the exact shape `InboxPage` records as a defect in its own words: "you pressed
+              this and were told off" rather than "this is unavailable". The button carries the
+              server's reason as its tooltip, so the explanation is in the same place as the
+              refusal it explains. */}
+          <button
+            type="button"
+            className="auto-btn is-danger"
+            disabled={!!automation.system}
+            {...(automation.system
+              ? { title: "This agent is part of the workspace setup. Open its column or its "
+                         + "connector to change it." }
+              : {})}
+            onClick={() => void remove()}
+          >
             Delete
           </button>
         </div>
@@ -1382,6 +1445,38 @@ export default function AutomationDetail({
           engine's own steps AND what the owner added, from data the rail already had) and there
           is no longer a state in which the reader gets it by accident.
         */}
+        {view === "chat" ? (
+          /*
+           * ⭐⭐ WAVE 34 · W34-T42 / R17 — the Chat view, and it writes through the SAME door.
+           *
+           * ⛔ `onAccept` IS `writeDefinition`, the function the Canvas's own Save calls. It is not
+           * "similar to" it: R3 asks for a drafted automation to be indistinguishable from a
+           * hand-built one, and the only way to guarantee that is for there to be one write path.
+           * `POST /automations/draft` deliberately saves nothing, so this is where a draft becomes
+           * real, and it becomes real by the ordinary route.
+           * ⚠ SWITCHING TABS UNMOUNTS THE BUILDER, and the cost is named rather than hidden: the
+           * builder's own local state (which step card is selected, its scroll position) is lost on
+           * the round trip. Everything a person has TYPED is safe — `name`, `touched`, the cron
+           * text and every panel value are this component's state, held above both views, so a
+           * half-edited name survives a visit to Chat and back. Keeping the builder mounted behind
+           * `hidden` would preserve the selection too, at the price of two live editors of one
+           * automation; the selection is the cheaper thing to lose.
+           */
+          <AutomationChat
+            name={automation.name}
+            onAccept={async (draft) => {
+              await writeDefinition({
+                ...(draft.name ? { name: draft.name } : {}),
+                // ⚠ `draft.trigger` IS A BARE KEY STRING on this route, not `{key}`. Written the
+                // other way it compiles, reads `undefined`, and every accepted flow lands with no
+                // trigger and never fires, with nothing red anywhere. See the type's own note.
+                ...(draft.trigger ? { trigger: { key: draft.trigger } } : {}),
+                flow: { actions: draft.actions || [] },
+              });
+              setView("canvas");
+            }}
+          />
+        ) : (
         <>
           <AutomationBuilder
             automation={automation}
@@ -1491,15 +1586,51 @@ export default function AutomationDetail({
                           answers "how many" and the summary answers "roughly what"; neither
                           could ever answer "why", which is the only question somebody opens this
                           panel with. These are the vendor's own sentences, not our paraphrase.
-                          ⚠ Rendered unconditionally rather than behind the drill-down: the drill
-                          is a paid-ish round trip that lists ROWS, and a reason you have to go
-                          looking for is most of the way back to not having it. */}
+
+                          ⭐⭐ WAVE 34 · W34-T45 / R21 — "Run logs are too wordy. Cut them down."
+                          MEASURED BEFORE CUTTING, because the ticket asks for that and because the
+                          obvious target was the wrong one: `summary` is capped at 400 chars and in
+                          practice reads "3 new, 2 updated", while `notes` is capped at 300 chars x
+                          25 entries = **up to 7,500 characters per run, rendered unconditionally,
+                          over MAX_RUNS = 20 runs**. The notes are the wordiness; the summary is
+                          not. Nothing was cut from the server.
+
+                          ⛔ AND THE OLD COMMENT HERE WAS RIGHT, WHICH IS WHY THIS IS A SPLIT AND
+                          NOT A COLLAPSE. It read: *"a reason you have to go looking for is most of
+                          the way back to not having it"* — true of a run that FAILED or hit a cap,
+                          and the exact case R6's standing rule protects (a limit that cannot be
+                          removed must be REPORTED). It is not true of the twentieth consecutive
+                          successful run, whose notes nobody reads and which is what makes the
+                          panel a wall of text. So: still unconditional when it MATTERS, one click
+                          away when it does not.
+
+                          ⚠ THE PREDICATE IS THE CODEBASE'S OWN LIMIT SIGNAL, NOT A TEXT HEURISTIC.
+                          `counts.capped` is already what the row above paints `is-warn` for, so
+                          "did this run hit a limit" has one answer in one place. Sniffing the note
+                          STRINGS for words like "limit" would be a second, quieter definition that
+                          drifts the first time a vendor rewords a sentence. */}
                       {r.notes?.length ? (
-                        <ul className="auto-run-notes">
-                          {r.notes.map((n, i) => (
-                            <li key={i}>{n}</li>
-                          ))}
-                        </ul>
+                        !r.ok || !!r.counts?.capped ? (
+                          <ul className="auto-run-notes">
+                            {r.notes.map((n, i) => (
+                              <li key={i}>{n}</li>
+                            ))}
+                          </ul>
+                        ) : (
+                          /* Native `<details>`: keyboard-reachable and screen-reader-announced for
+                             free, and the count is IN the summary so the disclosure says how much
+                             is behind it rather than being an anonymous chevron. */
+                          <details className="autor-notes">
+                            <summary className="autor-notes-toggle">
+                              {r.notes.length} note{r.notes.length === 1 ? "" : "s"}
+                            </summary>
+                            <ul className="auto-run-notes">
+                              {r.notes.map((n, i) => (
+                                <li key={i}>{n}</li>
+                              ))}
+                            </ul>
+                          </details>
+                        )
                       ) : null}
                       {drillFor === r.ts && drill ? (
                         <div className="auto-drill">
@@ -1539,6 +1670,7 @@ export default function AutomationDetail({
             </>
           </aside>
         </>
+        )}
       </div>
     </div>
   );

web/src/automation/AutomationFind.tsx

@@ -589,7 +589,7 @@ export default function AutomationFind({
             title={
               cats.length
                 ? "Values this workspace has actually seen, most-seen first. Adds to the list."
-                : "No category values have been seen in your data yet — type one."
+                : "No category values have been seen in your data yet. Type one."
             }
             value=""
             disabled={!cats.length}

web/src/automation/AutomationSurface.tsx

@@ -1,806 +1,814 @@
-// ---------------------------------------------------------------------------
-// automation/AutomationSurface.tsx — the Automation surface (contract C-AUTONAV).
-//
-// ⛔ THE CONTRACT THIS FILE GUARANTEES, verbatim: this module path, a DEFAULT
-// export, and NO PROPS. The shell mounts `<AutomationSurface />` and hands it
-// nothing; it fetches its own data from `/api/v1/automations`. That is the whole
-// interface, and it is stated here because the mount line lives in a file this
-// session does not own — a named export would cost a cross-session round trip.
-//
-// "Automation replaces the Views rail" (owner) is implemented the way the wave
-// scout established: the secondary rail is NOT a shell concept — each surface
-// owns its own. So this renders a sibling of `.cg-views` built from the same
-// `--lp-rail-w` tokens and the same fold behaviour, and the Views rail is
-// untouched.
-// ---------------------------------------------------------------------------
-import type { KeyboardEvent as ReactKeyboardEvent } from "react";
-import { Suspense, lazy, useCallback, useEffect, useRef, useState } from "react";
-
-import type { AutomationOpenDetail } from "../apiContract";
-import { AUTOMATION_OPEN_EVENT } from "../apiContract";
-// ⭐ WAVE 26 · ITEM 18 / R14 + C7 — THE LOOPABLE LOOP MARK, CONSUMED, NEVER REDRAWN.
-// The owner's reason is the mark's own geometry: *"these automations are basically loops."*
-// C7 says consume the existing icon component and do not inline a new SVG path, and
-// `shell/Brand.tsx`'s header says why in more detail than a rule could: the mark's one source of
-// truth is generated, it has already been hand-redrawn once, and the copy silently painted LAST
-// WAVE'S BRAND while a comment asserted parity. So this imports the component that POINTS at the
-// generated artifact. [[loopable-nav-logo-toggle]] — one element paints the mark.
-import { Mark } from "../shell/Brand";
-import type { Automation, AutomationList } from "./automationApi";
-import {
-  AutomationError,
-  cachedAutomations,
-  createAutomation,
-  listAutomations,
-  liveStepOf,
-  patchAutomation,
-  rememberAutomation,
-} from "./automationApi";
-
-/**
- * ⭐⭐ WAVE 30 · T21 (owner items 4 + 5) — THE EDITOR STOPS SHIPPING INSIDE THE LIST.
- *
- * ⛔ THIS `lazy()` IS THE TICKET. `AutomationDetail` was a STATIC import, and it statically pulls
- * `AutomationBuilder` (which in turn pulls `CondBuilder`, `PresetPlan` and `TriggerPicker`),
- * `AutomationFind` and `AutomationTrigger` — so the whole editor was linked into the one chunk a
- * person must download before the RAIL can paint a list of names. MEASURED at 88,771 B, against
- * `HomePage` at 4,814 and `ConnectorsPage` at 3,551. That is the "Automation takes forever to
- * load" complaint, and it had survived two waves because nothing asserted a number.
- *
- * ⛔ AND IT NEEDS ITS OWN `<Suspense>`, NOT `Shell.tsx`'s. `Lazily` already wraps this whole
- * surface, but a Suspense boundary catches ANY suspending descendant — so without an inner
- * boundary, opening an automation would suspend the boundary that owns the RAIL and blank the
- * list you just clicked in. The inner one keeps the rail painted while the editor streams in.
- * `fallback={null}` is deliberate and is `Lazily`'s own choice, not a shortcut: the work area is
- * simply not there for the moment the chunk is in flight, which is what every other route in this
- * product already does. ⚠ A skeleton here would be a NEW loading screen in the same wave that
- * exists to remove one (T22).
- * ⚠ Default export, checked: `Shell.tsx:53` records that `lazy()` over a NAMED export fails at
- * runtime, on click, and only for that one surface — `AutomationDetail` exports default.
- */
-const AutomationDetail = lazy(() => import("./AutomationDetail"));
-
-/**
- * The run poll's cadence (item 6). Named constants because they are a MEASURED trade-off, not a
- * taste: `POLL_MAX_MS` is the longest a finished run can still look live, and it is the only
- * cost the backoff has.
- */
-const POLL_MIN_MS = 2500;
-const POLL_MAX_MS = 8000;
-
-/*
- * ⭐ WAVE 26 · ITEM 18 / R14 — `stateTitle` STOOD HERE AND IS DELETED WITH THE DOT IT DESCRIBED.
- *
- * It composed the dot's tooltip ("Running now — <step>", "Last run failed — <summary>"), so it had
- * exactly one reader and no reason to outlive it. Deleting the render and keeping the composer is
- * how a file accumulates functions that look live and are not — and `noUnusedLocals` would have
- * caught this one, which is not a reason to lean on it: the NEXT such function might still have a
- * second caller and compile fine.
- *
- * ⛔ WHY THE TOOLTIP WAS NOT MOVED ONTO THE MARK INSTEAD. R14 is "same mark on every automation;
- * no status colour". Hanging "Last run failed" off a mark that is deliberately status-free just
- * moves the status channel into `title`/`aria-label`, where it is worse: invisible to the eye,
- * announced to a screen reader, and contradicting the visual. The run state has a home one click
- * away — the Builder's own "Last run succeeded / failed" lines, which R13 explicitly keeps.
- *
- * ⚠ `stateOf` ITSELF IS UNTOUCHED in `automationApi.ts`. `Shell.tsx:64/1095` imports it and
- * `liveStepOf` calls it — deleting the export to tidy up this file would break a fence I do not own.
- */
-
-/**
- * The rail's second line — ONE fact, not two.
- *
- * ⚠ It carried "Next 2026-08-04 06:00 · last 2026-08-04 00:20", and the rail is `--lp-rail-w`
- * wide, so it rendered as "Next 2026-08-04 06:00 · l…" — a second line whose only complete word
- * was "Next". Two facts that both truncate are worth less than one that fits. The forward-looking
- * one wins when a schedule exists (it is the question the rail answers: does this run itself?),
- * the last run otherwise. The full picture is one click away in the editor's run history, and the
- * row's `title` already says both.
- *
- * Caught by READING the screenshot: the DOM was correct and the CSS ellipsis was doing exactly
- * its job. [[ui-invisible-to-assertions]] — judge the pixels even when everything is green.
- */
-function railSubtitle(a: Automation): string {
-  /*
-   * ⭐ WAVE 24 (owner item 6, "Run once now is laggy / looks stuck") — WHILE IT IS RUNNING,
-   * THE ONE FACT WORTH THE LINE IS WHAT IT IS DOING.
-   *
-   * MEASURED, not guessed (`scratchpad/perf_automations.py`, mailbox D-5): the engine has been
-   * publishing a live step the whole time (`status.step`, `routes_automation.py:50-51`) and NO
-   * SURFACE HAS EVER RENDERED IT. So a `discover_instagram` run parked in its legitimate
-   * `BD_FILTER_WAIT = 120 s` vendor wait and a genuinely hung thread were pixel-identical: a
-   * pulsing blue dot and a subtitle still reciting the schedule. "Looks stuck" was not a
-   * performance problem — the poll costs 23 ms — it was the product declining to say.
-   *
-   * It takes the line rather than joining it, for the reason this function's note already
-   * gives: the rail is `--lp-rail-w` wide and two facts that both truncate are worth less than
-   * one that fits. The schedule is still one click away and the dot's `title` carries both.
-   */
-  const step = liveStepOf(a);
-  if (step) return step;
-  if (a.schedule?.enabled) return a.nextRunAt ? `Next ${a.nextRunAt}` : "Scheduled";
-  /*
-   * ⭐ WAVE 26 · ITEM 19 / R13 — `Last run 2026-08-06 13:58` IS DELETED FROM THIS LINE.
-   *
-   * ⛔ SCOPE, because R13 draws a line that is easy to over-read: the ruling names THIS secondary
-   * line under the automation's name. The Builder's "Last run succeeded / failed" RESULT lines
-   * (`AutomationBuilder.tsx:1676`, `:1679`) are a different surface and are explicitly NOT in
-   * scope — they are the answer to "Run once now", so deleting them would leave a button with no
-   * outcome.
-   *
-   * "Manual only" STAYS, and the distinction is the ruling's own: a dated run record is a
-   * changing FACT ABOUT THE PAST, while "this one has no schedule" is a stable property of the
-   * automation — the same question `Next …`/`Scheduled` answers for its siblings. Dropping it too
-   * would leave a manual automation with a blank second line and nothing saying why.
-   */
-  return "Manual only";
-}
-
-/*
- * ⛔ W23-W5's LISTENER IS AT MODULE SCOPE, AND THAT IS THE POINT — not a stylistic choice.
- *
- * The frame's click-through sets `window.location.hash = "#/automation"` and signals on the
- * VERY NEXT LINE (Shell.tsx:1647-1650, and its comment is right that the order matters). But a
- * hash write does not mount anything synchronously: `hashchange` is delivered as a task, the
- * router state then updates, React renders, and only THEN does a component effect subscribe.
- * A listener registered in `useEffect` therefore misses every click that arrives from another
- * page — which is every click, since a reader looking at Alerts is by definition not already
- * on this surface. The event would dispatch into nothing and every gate would stay green:
- * exactly the wave-20 item-25 failure the contract's own note describes, reproduced one layer
- * down.
- *
- * This module is imported statically by the shell, so this listener exists from app start. It
- * LATCHES the request; the component consumes the latch when it mounts and hears live events
- * while it is mounted. A request nobody claims is dropped on the next one — the latch is a
- * one-slot mailbox, never a queue.
- */
-let pendingOpen: AutomationOpenDetail | null = null;
-const openSubscribers = new Set<(detail: AutomationOpenDetail) => void>();
-
-if (typeof window !== "undefined") {
-  window.addEventListener(AUTOMATION_OPEN_EVENT, (event) => {
-    const detail = (event as CustomEvent<AutomationOpenDetail>).detail;
-    if (!detail?.autoId) return;
-    if (openSubscribers.size) {
-      for (const notify of openSubscribers) notify(detail);
-      return;
-    }
-    pendingOpen = detail;
-  });
-}
-
-/*
- * ⛔ THE `AUTOMATION_CREATE_EVENT` LISTENER STOOD HERE AND IS DELETED WITH ITS SIGNALLER
- * (wave 25 item 5a, ruling R8) — latch, subscriber set and all.
- *
- * Wave 24 built it to close the opposite defect: the event was declared, signalled from
- * `Shell.tsx`, and consumed NOWHERE, so all three "Automated database" doors navigated to
- * `#/automation` and then did nothing, in production, with every gate green. R8 now deletes those
- * three doors — creating a database and pointing an automation at it are two acts — and they were
- * the event's only signaller.
- *
- * ⛔ SO THIS SIDE GOES TOO, IN THE SAME CHANGE. A listener with no signaller is the same defect
- * read from the other end: it compiles, it costs nothing at runtime, and it reads to the next
- * person as a live channel. The rule that catches both is now DERIVED rather than remembered —
- * `verify_automation_ui.py` enumerates every `AUTOMATION_*_EVENT` in `apiContract.ts` and demands
- * a signal site AND a listener site for each.
- *
- * ⚠ NOTHING ABOUT CREATING AN AUTOMATION IS LOST. `createAndOpen` is untouched and still has two
- * doors, both on this surface: the rail's button and the empty state's. What is gone is the claim
- * that a database can be created BY asking for an automation.
- */
-
-/**
- * A default name for a brand-new automation, and it has to be one the server ACCEPTS.
- *
- * MEASURED against the live route rather than assumed (`scratchpad/probe_names.py`): a create
- * with no name is a 400 (`name the automation`), and duplicate names are ALLOWED. So the name
- * cannot be omitted, and a fixed literal would stack "New automation" three deep in a rail that
- * sorts by name with nothing to tell the rows apart. Numbering from the existing list is a
- * client-side convenience over a server that does not care: if two tabs race, the loser gets a
- * duplicate name, which is legal, visible and renameable — never an error the user has to read.
- */
-function nextAutomationName(existing: Automation[]): string {
-  const taken = new Set(existing.map((a) => (a.name || "").trim().toLowerCase()));
-  for (let n = existing.length + 1; ; n += 1) {
-    const candidate = `Automation ${n}`;
-    if (!taken.has(candidate.toLowerCase())) return candidate;
-  }
-}
-
-export default function AutomationSurface() {
-  /* ⭐ T22 — SEEDED FROM THE CLIENT MEMO, so a revisit inside the freshness window never passes
-     through `data === null` and therefore never paints the skeleton. The lazy initialiser runs
-     once, on mount, BEFORE the first paint — `useState(cachedAutomations())` would call it on
-     every render instead, which is the same value at needless cost. A cold start still returns
-     null and still gets the skeleton: it is made rare, not removed (see `automationApi.ts`). */
-  const [data, setData] = useState<AutomationList | null>(() => cachedAutomations());
-  const [error, setError] = useState("");
-  const [activeId, setActiveId] = useState<string>("");
-  const [railShut, setRailShut] = useState(false);
-  const [busy, setBusy] = useState("");
-  /**
-   * ⭐ WAVE 24 / C-CREATE — a create is now a ROUND TRIP, not a local wizard, so the door has to
-   * say it is busy. Without this a second click while the POST is in flight makes a second
-   * automation, and the server allows duplicate names, so the user gets two rows that look
-   * identical and no error to explain either of them.
-   */
-  const [creatingNow, setCreatingNow] = useState(false);
-  /** An open request waiting for the list to arrive (see the resolver below). */
-  const [openRequest, setOpenRequest] = useState<AutomationOpenDetail | null>(null);
-  /* ⛔ `createRequest` LEFT WITH THE EVENT THAT SET IT (wave 25, R8) — see the tombstone above. */
-  const listRef = useRef<HTMLDivElement | null>(null);
-
-  /**
-   * ⛔ C14 LEG 2 — THE ID THE USER LAST ASKED FOR, and it is a ref because it has to be
-   * written SYNCHRONOUSLY, inside the click, before any promise that was already in flight
-   * can resolve. State would not do: a resolution racing React's commit would read the
-   * previous value, which is the exact window this guard exists to close.
-   */
-  const wantedId = useRef("");
-
-  /**
-   * ⭐ THE ONLY PLACE THE RAIL'S SELECTION MOVES ON PURPOSE. Every deliberate change of
-   * automation — a rail click, a create, a delete — goes through here, so "what the user
-   * asked for" and "what is on screen" are written in one statement and cannot drift apart.
-   * A resolution that wants to steer the rail compares itself against `wantedId` instead.
-   */
-  const select = useCallback((id: string, _stage = "") => {
-    wantedId.current = id;
-    setActiveId(id);
-  }, []);
-
-  /**
-   * ⭐⭐ W33 (C-18, from lane C) — WHICH PANE AN INBOX ITEM ASKED FOR, and it was DROPPED here.
-   *
-   * ⛔ THE PAYLOAD WAS DECLARED, TRANSPORTED, AND IGNORED AT THE LAST HOP.
-   * `routes_alerts.py` sets `tab: "runs"` on a notification's target, `inboxModel.routeForTarget`
-   * forwards it and `Shell.tsx` signals `{autoId, tab}` — and this file read `openRequest.tab`
-   * NOWHERE. So a person clicking *"12 new creators found"* to see the RUN landed on Properties,
-   * which is [[flag-shipped-without-its-writer]] with the writer present and the READER missing.
-   * ⚠ NOT FIXED BY DELETING `tab` FROM THE CONTRACT, which was the other option C offered: the
-   * field is the only thing that carries "you clicked a run, so show runs", and an inbox that
-   * lands you on the wrong pane is the complaint, not the field.
-   * ⚠ IT IS A ONE-SHOT REQUEST, NOT A CONTROLLED VALUE. Forcing the pane on every render would
-   * take the pane control away from the person the moment after they used it — so this is
-   * consumed by `AutomationDetail` as an INITIAL value keyed on the automation, and cleared here
-   * with the request that carried it.
-   */
-  const [openTab, setOpenTab] = useState<"properties" | "runs" | "">("");
-
-  /**
-   * ⛔ C14 LEG 3 (the paint half) — A STALE READ MAY NOT REPAINT.
-   *
-   * Every call takes the next generation; only the newest one is allowed to `setData`. The
-   * defect this closes is not cosmetic: a poll issued BEFORE a delete resolves AFTER it, and
-   * a list that still contains the deleted automation puts a row back in the rail that the
-   * user has just watched disappear. Same for a toggle, and same for a create.
-   *
-   * ⚠ THE RETURN VALUE IS NOT GUARDED, deliberately. The caller asked a question and gets
-   * its own answer — coupling the two would mean a create whose `load()` was overtaken by a
-   * poll silently failed to select the automation it had just made.
-   */
-  const gen = useRef(0);
-
-  const load = useCallback(async (abort?: AbortSignal) => {
-    const mine = ++gen.current;
-    try {
-      const next = await listAutomations(abort);
-      if (mine === gen.current) {
-        setData(next);
-        setError("");
-      }
-      return next;
-    } catch (e) {
-      if ((e as Error)?.name === "AbortError") return null;
-      if (mine === gen.current)
-        setError(
-          e instanceof AutomationError
-            ? e.message
-            : "The automation service did not answer."
-        );
-      return null;
-    }
-  }, []);
-
-  /**
-   * ⭐⭐ WAVE 31 · T31 — one freshly-written automation replaces its own row, with no round trip.
-   *
-   * ⚠ IT TAKES THE GENERATION, and that is not decoration. `load`'s guard exists so a stale READ
-   * cannot repaint; a WRITE response is by definition newer than any read already in flight, so it
-   * must win the same race rather than sit outside it. Without the bump, a `GET /automations`
-   * issued before the save could resolve after the merge and paint the pre-save row back — the
-   * exact ghost `gen` was introduced for, arriving through the new door.
-   *
-   * ⚠ Returns FALSE when there is nothing to merge into (a cold surface has no memo), and the
-   * caller then does a real load. Painting a one-row list would be worse than a round trip.
-   */
-  const mergeSaved = useCallback((fresh: Automation) => {
-    const next = rememberAutomation(fresh);
-    if (!next) return false;
-    gen.current += 1;
-    setData(next);
-    setError("");
-    return true;
-  }, []);
-
-  useEffect(() => {
-    const ac = new AbortController();
-    void load(ac.signal);
-    return () => ac.abort();
-  }, [load]);
-
-  /**
-   * ⭐⭐ WAVE 24 / C-CREATE (a) — CREATE AND OPEN. This REPLACED the three-step wizard.
-   *
-   * R6 is what makes it possible: `plain` is a real kind with no machine graph nodes, and it is
-   * what `POST /automations` stores when the body names none. So "new automation" stopped being
-   * a question ("which of three kinds?" — two of which can no longer be created at all) and
-   * became what it says: a new automation, open, on its trigger picker. Choosing a SOURCE is now
-   * picking the `ig_profile_match` trigger, which is where that choice belongs.
-   *
-   * ⛔ THE GUARD IS A REF, not the `creatingNow` state, and this file already carries the scar
-   * that explains why (C14 leg 2): a state read inside a click closure is the value from the
-   * last render, so two fast clicks both see `false` and both POST. Duplicate names are legal
-   * server-side, so the user would get two identical rows and no error. The ref is written
-   * synchronously, inside the click, before anything can await.
-   */
-  const creatingRef = useRef(false);
-  const createAndOpen = useCallback(async () => {
-    if (creatingRef.current) return;
-    creatingRef.current = true;
-    setCreatingNow(true);
-    try {
-      const res = await createAutomation({
-        name: nextAutomationName(data?.automations || []),
-      });
-      const id = res?.automation?.id || "";
-      // The create flow is the one caller allowed to name a different id (C14 leg 2) — the
-      // automation did not exist when the click happened, so there is nothing to race with.
-      const next = await load();
-      if (id && next) select(id);
-    } catch (e) {
-      setError(
-        e instanceof AutomationError ? e.message : "The automation was not created."
-      );
-    } finally {
-      creatingRef.current = false;
-      setCreatingNow(false);
-    }
-  }, [data, load, select]);
-
-  // A run is a background thread on the server, so the surface has to ASK whether it
-  // finished. Polling only while something is actually running keeps an idle surface
-  // silent — a fixed interval would be a request every few seconds forever, for a page
-  // whose contents change a handful of times a day.
-  //
-  // ⛔ C14 LEG 3 (the abort half). It used to call `load()` bare — no signal, nothing to
-  // cancel — so a request the interval had already issued kept going after the effect that
-  // owned it was gone. One controller per effect run, aborted with the interval, means a poll
-  // cannot outlive the condition that justified it. The generation guard inside `load` covers
-  // the rest: a response that survives the abort still cannot repaint over a newer one.
-  //
-  // ⭐ WAVE 24 (item 6, C-PERF) — THE INTERVAL BECAME A BACKOFF, and the measurement is why it is
-  // a SMALL change rather than the big one the contract's hypothesis 2 asked for.
-  //
-  // MEASURED (`scratchpad/perf_automations.py`, mailbox D-5): this poll costs ~23 ms and 24 KB
-  // for a ten-automation tenant, and the engine work the hypothesis blamed — a `graph()` rebuild
-  // per automation — is **41 µs each**, i.e. under 4% of the request. The payload was never the
-  // problem, so nothing here gets a cheaper endpoint.
-  //
-  // What the numbers DO indict is the aggregate: a discovery run legitimately blocks up to
-  // `BD_FILTER_WAIT` = 120 s, and two independent 2.5 s polls across this file and the detail
-  // spend ~96 requests and ~2.3 MB over that window — in the same single process the run itself
-  // is a thread in. So the delay grows 2.5 → 5 → 8 s and stops there.
-  //
-  // ⚠ NOT "to learn nothing", and the distinction is the whole justification. That WAS true when
-  // this file rendered no live step: the poll's only observable effect was a dot that had already
-  // been pulsing for two minutes. It stopped being true in this same change — `liveStepOf` now
-  // paints `status.step`, so a poll carries the one fact worth having. The backoff is therefore
-  // NOT "stop asking a pointless question"; it is FEWER ROUND TRIPS FOR THE SAME INFORMATION, on
-  // a step text that changes every few seconds at most, not every 2.5.
-  // The cap is deliberately low: it bounds how long a FINISHED run can still look live, which is
-  // the only thing a backoff can make worse, and 8 s of that is worth ~⅔ fewer requests.
-  //
-  // ⛔ THE KEY IS THE RUNNING SET, NOT A BOOLEAN, and that is what makes the reset correct: the
-  // effect re-runs — and the delay drops back to 2.5 s — the moment a run starts or finishes, so
-  // a user who clicks Run now gets the fast cadence again instead of inheriting the tail of the
-  // previous run's backoff. A bare `anyRunning` boolean cannot see the second run start.
-  // A step text changing does NOT re-key it, so the interval never thrashes.
-  //
-  // C14 LEG 3 (the abort half) is unchanged and still load-bearing: one controller per effect
-  // run, aborted with the timer, so a poll cannot outlive the condition that justified it. The
-  // generation guard inside `load` covers the rest.
-  const runningKey = (data?.automations || [])
-    .filter((a) => a.running)
-    .map((a) => a.id)
-    .sort()
-    .join(",");
-  useEffect(() => {
-    if (!runningKey) return undefined;
-    const ac = new AbortController();
-    let delay = POLL_MIN_MS;
-    let timer = 0;
-    const tick = () => {
-      void load(ac.signal);
-      delay = Math.min(delay * 2, POLL_MAX_MS);
-      timer = window.setTimeout(tick, delay);
-    };
-    timer = window.setTimeout(tick, delay);
-    return () => {
-      window.clearTimeout(timer);
-      ac.abort();
-    };
-  }, [runningKey, load]);
-
-  // ── W23-W5, the surface's half: hear the request, then answer it when we CAN ──────────
-  useEffect(() => {
-    const notify = (detail: AutomationOpenDetail) => setOpenRequest(detail);
-    openSubscribers.add(notify);
-    if (pendingOpen) {
-      const latched = pendingOpen;
-      pendingOpen = null;
-      setOpenRequest(latched);
-    }
-    return () => {
-      openSubscribers.delete(notify);
-    };
-  }, []);
-
-  /* ⛔ THE C-CREATE(b) SUBSCRIBE EFFECT AND ITS RESOLVER STOOD HERE (wave 25, R8). They heard the
-     create event and, once the list had arrived, called `createAndOpen` — the "wait for the list
-     or every automation is named Automation 1" note lives on in `nextAutomationName`, which is
-     still numbered off `existing`. With no signaller there is nothing to hear. */
-
-  /**
-   * ⚠ THE REQUEST OUTLIVES THE FETCH, and it has to. The reader clicks a notification from
-   * another page, so this surface is mounting WITH AN EMPTY LIST — "select it if it is in the
-   * list" would drop every real click and keep only the one case where the reader was already
-   * here. So the request is held until `data` exists, and only then answered.
-   *
-   * An automation the reader can no longer open does NOTHING (the contract's own words): the
-   * request is cleared either way, so a stale id cannot sit here re-firing against every
-   * subsequent list.
-   */
-  useEffect(() => {
-    if (!openRequest || !data) return;
-    const found = (data.automations || []).some((a) => a.id === openRequest.autoId);
-    if (found) {
-      select(openRequest.autoId, openRequest.stageId || "");
-      // C-18: the pane the notification asked for, read at the one moment it means something.
-      const want = String((openRequest as { tab?: string }).tab || "");
-      setOpenTab(want === "runs" || want === "properties" ? want : "");
-    }
-    setOpenRequest(null);
-  }, [openRequest, data, select]);
-
-  const items = data?.automations || [];
-  const active = items.find((a) => a.id === activeId) || null;
-
-  /**
-   * ⭐⭐ WAVE 32 · T43 (owner item 2) — TURNING AN AUTOMATION ON OR OFF STOPS TAKING FOREVER.
-   *
-   * Owner: turning an automation on or off "takes forever". ⛔ THE TICKET'S HYPOTHESIS WAS THE
-   * SERVER AND IT IS NOT — MEASURED. `engine.patch` for a schedule-only body takes ONE
-   * `automations` bucket read, ZERO `user_tables` reads and ~1 ms against a 2.8 MB fixture, and
-   * `GET /automations` is one read too since W30-T12. The cost was never the document shape
-   * (D-179/D-175's family): it was that this handler paid **two sequential round trips** for one
-   * click, and painted nothing until BOTH had landed. The second one re-downloaded the entire
-   * rail payload — 88,771 B measured, see the note at the top of this file — to learn one boolean
-   * the first response had already returned.
-   *
-   * ⛔ AND THE FIX ALREADY EXISTED IN THIS FILE, POINTED AT A DIFFERENT BUTTON. `mergeSaved` is
-   * W31-T31, built for the detail pane's saves, with its own note about the write response being
-   * newer than any read in flight. The rail's own switch never got it — a fix applied to one of
-   * two twins, which is this wave's recurring shape.
-   *
-   * Three states, in order, and the middle one is what the owner actually asked for:
-   *   1. FLIP IT NOW. The switch is the user's instruction, not a question; painting it after a
-   *      network round trip is what "takes forever" describes even when the round trip is fast.
-   *   2. adopt the server's own answer when it lands, which carries the derived fields an
-   *      optimistic row cannot invent (`nextRunAt`, the status line).
-   *   3. put the OLD row back if the write failed, beside the error — an optimistic switch that
-   *      stays on after a refusal is a lie, and a worse one than a slow switch.
-   *
-   * ⚠ `mergeSaved` TAKES THE GENERATION, which is what stops [[refetch-eats-its-own-write]] here:
-   * a `GET /automations` issued before the click can still resolve after it, and without the bump
-   * it would paint the pre-toggle row back over both the optimistic flip and the confirmation.
-   * ⚠ `busy` is no longer what makes the switch look right — it stays only to keep a second click
-   * from racing the first.
-   */
-  const toggleEnabled = async (a: Automation) => {
-    const flipped: Automation = {
-      ...a,
-      schedule: { ...a.schedule, enabled: !a.schedule.enabled },
-    };
-    setBusy(a.id);
-    const painted = mergeSaved(flipped);
-    try {
-      const { automation: fresh } = await patchAutomation(a.id, {
-        schedule: { cron: a.schedule.cron, enabled: !a.schedule.enabled },
-      });
-      // A cold surface has no memo to merge into (`mergeSaved` answers false), and a one-row
-      // repaint would be worse than a round trip — the same rule `onSaved` follows.
-      if (!fresh || !mergeSaved(fresh)) await load();
-    } catch (e) {
-      if (painted) mergeSaved(a);
-      setError(e instanceof AutomationError ? e.message : "That change was not saved.");
-    } finally {
-      setBusy("");
-    }
-  };
-
-  const onRailKey = (event: ReactKeyboardEvent<HTMLDivElement>) => {
-    if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
-    const rows = Array.from(
-      listRef.current?.querySelectorAll<HTMLButtonElement>(".auto-row-main") || []
-    );
-    if (!rows.length) return;
-    event.preventDefault();
-    const at = rows.indexOf(document.activeElement as HTMLButtonElement);
-    const next = event.key === "ArrowDown" ? (at + 1) % rows.length
-      : (at - 1 + rows.length) % rows.length;
-    rows[next < 0 ? 0 : next]?.focus();
-  };
-
-  return (
-    <div className="auto-surface">
-      <aside
-        className={"auto-rail" + (railShut ? " is-collapsed" : "")}
-        aria-label="Automations"
-      >
-        {/* The same three-bars fold control the Views rail carries — the two rails are
-            one idea, so they must not fold with two different affordances. */}
-        <div className="auto-rail-top">
-          <button
-            type="button"
-            className="cg-rail-toggle"
-            aria-label={railShut ? "Expand automations" : "Minimize automations"}
-            aria-expanded={!railShut}
-            title={railShut ? "Expand automations" : "Minimize automations"}
-            onClick={() => setRailShut((v) => !v)}
-          >
-            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
-              <path
-                d="M2.5 4.4h11M2.5 8h11M2.5 11.6h11"
-                stroke="currentColor"
-                strokeWidth="1.35"
-                strokeLinecap="round"
-              />
-            </svg>
-          </button>
-        </div>
-
-        <div className="auto-create">
-          <button
-            type="button"
-            className="auto-create-btn"
-            disabled={creatingNow}
-            onClick={() => void createAndOpen()}
-          >
-            <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
-              <path
-                d="M8 3.4v9.2M3.4 8h9.2"
-                stroke="currentColor"
-                strokeWidth="1.5"
-                strokeLinecap="round"
-              />
-            </svg>
-            New automation
-          </button>
-        </div>
-
-        <div className="auto-list" ref={listRef} onKeyDown={onRailKey}>
-          {items.map((a) => {
-            return (
-              <div
-                key={a.id}
-                className={"auto-row" + (a.id === activeId ? " is-active" : "")}
-              >
-                <button
-                  type="button"
-                  className="auto-row-main"
-                  onClick={() => select(a.id)}
-                >
-                  {/* ⭐ ITEM 18 / R14 — THE LOOP MARK, WHERE THE STATUS DOT WAS. Same mark on
-                      every row, no status colour: the owner's point is that an automation IS a
-                      loop, not that this one is green. The `.auto-loopmark` wrapper is what sizes
-                      it — `.lp-mark` is shell-owned CSS and outside this session's region, so the
-                      box is mine and the mark is theirs. */}
-                  <span className="auto-loopmark">
-                    <Mark size={15} />
-                  </span>
-                  <span className="auto-row-text">
-                    <span className="auto-row-name">{a.name}</span>
-                    <span className="auto-row-desc">{railSubtitle(a)}</span>
-                  </span>
-                </button>
-                <button
-                  type="button"
-                  className={"auto-row-switch" + (a.schedule?.enabled ? " is-on" : "")}
-                  disabled={busy === a.id}
-                  aria-pressed={!!a.schedule?.enabled}
-                  title={
-                    a.schedule?.enabled
-                      ? `Scheduled: ${a.schedule.cron}. Click to pause.`
-                      : "Not scheduled. Click to enable."
-                  }
-                  onClick={() => void toggleEnabled(a)}
-                >
-                  <span className="auto-row-switch-knob" />
-                </button>
-              </div>
-            );
-          })}
-          {/* ONE LINE (R13). It used to describe the kinds — "one reads a public web page…
-              the other fills an automation column…" — which was two sentences, wrong by the
-              time a third kind shipped, and printed inside a `--lp-rail-w` column. What the
-              kinds are belongs to the create form, which is one click away and lists all of
-              them from the server. */}
-          {/* ⭐ WAVE 29 (W29-T01) — A LOADING RAIL IS NOT AN EMPTY ONE. `data` is null until the
-              first `listAutomations()` resolves, and this branch read only `items.length`, so
-              every visit to Automation asserted "No automations yet." to a person who has
-              several — then replaced it with their list. Half of owner item 5's "takes a while
-              to appear" is that sentence: the wait is real, but being told you own nothing is
-              what makes it read as broken rather than slow. `data === null` is the one state
-              that means NOBODY HAS LOOKED, and it gets skeleton rows, not a claim. */}
-          {data === null && !error ? (
-            <div className="auto-rail-loading" aria-hidden="true">
-              <span className="auto-rail-skel" />
-              <span className="auto-rail-skel" />
-              <span className="auto-rail-skel" />
-            </div>
-          ) : null}
-          {data !== null && !items.length && !error ? (
-            <p className="auto-rail-empty">No automations yet.</p>
-          ) : null}
-        </div>
-      </aside>
-
-      <section className="auto-main">
-        {error ? (
-          <div className="auto-banner is-error" role="alert">
-            {error}
-          </div>
-        ) : null}
-        {data && !data.storeAvailable ? (
-          <div className="auto-banner is-warn" role="status">
-            The tenant store is unavailable, so nothing can be saved right now.
-          </div>
-        ) : null}
-
-        {/*
-          ⛔ THE `creating` BRANCH IS GONE (wave 24, C-CREATE a / owner items 3 + 4).
-          `AutomationCreate` used to render here — a three-step wizard whose first step asked
-          which DATABASE to write into (an existing one, a new one, or one the automation itself
-          would create) and whose second asked which of three KINDS.
-          R6 retires that question at the root: two of the three kinds can no longer be created
-          at all, and the third is now reached by picking a trigger. A new automation is created
-          the moment it is asked for (`createAndOpen`) and opens on its own Builder, so there is
-          no intermediate face left to render and no `creating` state to hold.
-          ⭐ WAVE 25 (R8) retires the LAST of that vocabulary: the third answer was the
-          "automated database", and it is gone from every door in the product. This button is now
-          one of exactly two ways to make an automation, and both are on this surface.
-          The import went with it — it is what would break `npx tsc -b` for the WHOLE client the
-          moment session B deletes the file, which is why this deletion is sequenced first.
-        */}
-        {/* T21: the editor's own Suspense boundary — see the `lazy()` above for why it cannot be
-            `Shell.tsx`'s. `fallback={null}`, matching `Lazily`. */}
-        {active ? (
-          <Suspense fallback={null}>
-          <AutomationDetail
-            key={active.id}
-            automation={active}
-            /* C-18: which pane the Inbox asked for, or "" for the ordinary open. Consumed ONCE,
-               as an initial value — see `openTab`'s note on why it is not controlled. */
-            openTab={openTab}
-            /* ⛔ `kinds={data?.kinds || []}` LEFT HERE WITH THE PROP IT FED (wave 25, D-57) —
-               both halves in one change, because either alone is a `tsc` error. */
-            cronPresets={data?.cronPresets || []}
-            paidReady={!!data?.paidReady}
-            discover={data?.discover}
-            // The trigger vocabulary (C3). Forwarded as-is — absent stays absent, so the
-            // trigger face can tell "the server offered nothing" from "the server offered
-            // an empty list" rather than collapsing both into a picker with no options.
-            triggers={data?.triggers}
-            // C4's action menu + the builder's ceilings. Forwarded as-is for the same reason
-            // `triggers` is: absent must stay absent, so the builder can tell "the server
-            // offered nothing" from "the server offered an empty list".
-            catalog={data?.actionsCatalog}
-            vocab={data?.flow}
-            // `?? null` and never `|| {enabled:false}`: an absent tick bit is "the server did
-            // not say", which Step 1 prints as its own sentence. Defaulting it here would
-            // turn a missing field into a claim about production (C6 amendment #1).
-            tick={data?.tick ?? null}
-            /*
-             * ⭐ W24-W1 (item 6) — WHAT THIS RUN IS DOING, on the one surface that survives in
-             * BOTH views. REQUIRED on the far side deliberately: an optional prop that nobody
-             * passes degrades to "the feature does not exist", which is indistinguishable from
-             * "it was never built" — and this whole item exists because a live step text rode
-             * the wire for three waves with nothing rendering it.
-             * `liveStepOf` returns the step ONLY while the automation is running; a stale step
-             * from a finished run is a worse answer than none.
-             */
-            liveStep={liveStepOf(active)}
-            /*
-             * ⛔ C14 LEG 2 — THE STALE-ID WRITE-BACK, and this is the ghost's second cause.
-             *
-             * The detail calls `onSaved(automation.id)` from six places (save, the trigger
-             * picker, a schedule change, a node switch, a card move, a run). Each closure
-             * captures the automation it was mounted for, so a save that resolves AFTER the
-             * user has clicked a different row used to call `setActiveId(the OLD id)` — the
-             * rail jumped back, the detail remounted, and what the user saw was the previous
-             * automation reappearing over the one they had just opened. It looked like a
-             * rendering bug; it was a resolution steering the selection.
-             *
-             * A resolution may no longer steer anything. It reloads the list — that part was
-             * always right — and it re-asserts the selection ONLY when its id is still the one
-             * the user asked for, which makes the write a no-op in the good case and nothing
-             * at all in the bad one.
-             */
-            onSaved={async (id, fresh) => {
-              // ⭐⭐ WAVE 31 · T31 — CORRECT THE ONE ROW WE WERE JUST TOLD ABOUT.
-              // `patchAutomation` and `toggleNode` return the updated definition; re-reading the
-              // whole list to learn it is the second of the two round trips "Saving…" used to
-              // span. `mergeSaved` keeps the memo and the component in step (see
-              // `automationApi.rememberAutomation`) and takes the generation, because a write
-              // response is newer than any read still in flight — the same rule `load` follows,
-              // pointed the other way.
-              if (fresh && mergeSaved(fresh)) {
-                if (id && id === wantedId.current) select(id);
-                return;
-              }
-              const next = await load();
-              if (id && next && id === wantedId.current) select(id);
-            }}
-            onDeleted={async () => {
-              select("");
-              await load();
-            }}
-          />
-          </Suspense>
-        ) : (
-          /*
-           * THE EMPTY STATE IS ONE LINE AND A BUTTON (owner ruling R13 — "never
-           * over-explain", now a DESIGN.md law).
-           *
-           * It was a heading, a three-sentence paragraph and a 130-word bulleted list
-           * describing all three kinds. Every word of it was true and none of it was READ:
-           * an empty state is passed through, not studied, and the person looking at it has
-           * already decided to make an automation. The kinds are described where the choice
-           * is actually made — the create form lists them FROM THE SERVER, so that copy also
-           * cannot go stale the way this list had (it described two kinds after a third
-           * shipped).
-           *
-           * The button is here rather than only in the rail because this pane is where the
-           * eye is; a create affordance the user has to go find is the same defect as the
-           * paragraph, spent differently.
-           */
-          <div className="autob-empty">
-            {/*
-              ⛔ NO TITLE HERE ANY MORE (C13, owner item 2). This pane carried an `h1`
-              reading "Automations" at 20px/600 — a THIRD title treatment on a page that
-              also had the header's editable 16px/700 input, against every database page's
-              single 16px/650 `shell-db-name`. The shell now wraps this branch in the same
-              `shell-db-frame` + `DbHead` a database gets (wiring W23-W1), so the page's name
-              is drawn once, by the one component that draws every other page's name. A
-              stand-in restyled to match would have been a second copy of the same fact,
-              free to drift the day the header moves.
-            */}
-            <p className="autob-empty-line">
-              A job this workspace runs for you, on demand or on a schedule.
-            </p>
-            <button
-              type="button"
-              className="auto-btn is-primary"
-              disabled={creatingNow}
-              onClick={() => void createAndOpen()}
-            >
-              New automation
-            </button>
-          </div>
-        )}
-      </section>
-    </div>
-  );
-}
+// ---------------------------------------------------------------------------
+// automation/AutomationSurface.tsx — the Automation surface (contract C-AUTONAV).
+//
+// ⛔ THE CONTRACT THIS FILE GUARANTEES, verbatim: this module path, a DEFAULT
+// export, and NO PROPS. The shell mounts `<AutomationSurface />` and hands it
+// nothing; it fetches its own data from `/api/v1/automations`. That is the whole
+// interface, and it is stated here because the mount line lives in a file this
+// session does not own — a named export would cost a cross-session round trip.
+//
+// "Automation replaces the Views rail" (owner) is implemented the way the wave
+// scout established: the secondary rail is NOT a shell concept — each surface
+// owns its own. So this renders a sibling of `.cg-views` built from the same
+// `--lp-rail-w` tokens and the same fold behaviour, and the Views rail is
+// untouched.
+// ---------------------------------------------------------------------------
+import type { KeyboardEvent as ReactKeyboardEvent } from "react";
+import { Suspense, lazy, useCallback, useEffect, useRef, useState } from "react";
+
+import type { AutomationOpenDetail } from "../apiContract";
+import { AUTOMATION_OPEN_EVENT } from "../apiContract";
+// ⭐ WAVE 26 · ITEM 18 / R14 + C7 — THE LOOPABLE LOOP MARK, CONSUMED, NEVER REDRAWN.
+// The owner's reason is the mark's own geometry: *"these automations are basically loops."*
+// C7 says consume the existing icon component and do not inline a new SVG path, and
+// `shell/Brand.tsx`'s header says why in more detail than a rule could: the mark's one source of
+// truth is generated, it has already been hand-redrawn once, and the copy silently painted LAST
+// WAVE'S BRAND while a comment asserted parity. So this imports the component that POINTS at the
+// generated artifact. [[loopable-nav-logo-toggle]] — one element paints the mark.
+import { Mark } from "../shell/Brand";
+import type { Automation, AutomationList } from "./automationApi";
+import {
+  AutomationError,
+  cachedAutomations,
+  createAutomation,
+  listAutomations,
+  liveStepOf,
+  patchAutomation,
+  rememberAutomation,
+} from "./automationApi";
+
+/**
+ * ⭐⭐ WAVE 30 · T21 (owner items 4 + 5) — THE EDITOR STOPS SHIPPING INSIDE THE LIST.
+ *
+ * ⛔ THIS `lazy()` IS THE TICKET. `AutomationDetail` was a STATIC import, and it statically pulls
+ * `AutomationBuilder` (which in turn pulls `CondBuilder`, `PresetPlan` and `TriggerPicker`),
+ * `AutomationFind` and `AutomationTrigger` — so the whole editor was linked into the one chunk a
+ * person must download before the RAIL can paint a list of names. MEASURED at 88,771 B, against
+ * `HomePage` at 4,814 and `ConnectorsPage` at 3,551. That is the "Automation takes forever to
+ * load" complaint, and it had survived two waves because nothing asserted a number.
+ *
+ * ⛔ AND IT NEEDS ITS OWN `<Suspense>`, NOT `Shell.tsx`'s. `Lazily` already wraps this whole
+ * surface, but a Suspense boundary catches ANY suspending descendant — so without an inner
+ * boundary, opening an automation would suspend the boundary that owns the RAIL and blank the
+ * list you just clicked in. The inner one keeps the rail painted while the editor streams in.
+ * `fallback={null}` is deliberate and is `Lazily`'s own choice, not a shortcut: the work area is
+ * simply not there for the moment the chunk is in flight, which is what every other route in this
+ * product already does. ⚠ A skeleton here would be a NEW loading screen in the same wave that
+ * exists to remove one (T22).
+ * ⚠ Default export, checked: `Shell.tsx:53` records that `lazy()` over a NAMED export fails at
+ * runtime, on click, and only for that one surface — `AutomationDetail` exports default.
+ */
+const AutomationDetail = lazy(() => import("./AutomationDetail"));
+
+/**
+ * The run poll's cadence (item 6). Named constants because they are a MEASURED trade-off, not a
+ * taste: `POLL_MAX_MS` is the longest a finished run can still look live, and it is the only
+ * cost the backoff has.
+ */
+const POLL_MIN_MS = 2500;
+const POLL_MAX_MS = 8000;
+
+/*
+ * ⭐ WAVE 26 · ITEM 18 / R14 — `stateTitle` STOOD HERE AND IS DELETED WITH THE DOT IT DESCRIBED.
+ *
+ * It composed the dot's tooltip (the running step, or the last run's failure summary), so it had
+ * exactly one reader and no reason to outlive it. Deleting the render and keeping the composer is
+ * how a file accumulates functions that look live and are not — and `noUnusedLocals` would have
+ * caught this one, which is not a reason to lean on it: the NEXT such function might still have a
+ * second caller and compile fine.
+ *
+ * ⛔ WHY THE TOOLTIP WAS NOT MOVED ONTO THE MARK INSTEAD. R14 is "same mark on every automation;
+ * no status colour". Hanging "Last run failed" off a mark that is deliberately status-free just
+ * moves the status channel into `title`/`aria-label`, where it is worse: invisible to the eye,
+ * announced to a screen reader, and contradicting the visual. The run state has a home one click
+ * away — the Builder's own "Last run succeeded / failed" lines, which R13 explicitly keeps.
+ *
+ * ⚠ `stateOf` ITSELF IS UNTOUCHED in `automationApi.ts`. `Shell.tsx:64/1095` imports it and
+ * `liveStepOf` calls it — deleting the export to tidy up this file would break a fence I do not own.
+ */
+
+/**
+ * The rail's second line — ONE fact, not two.
+ *
+ * ⚠ It carried "Next 2026-08-04 06:00 · last 2026-08-04 00:20", and the rail is `--lp-rail-w`
+ * wide, so it rendered as "Next 2026-08-04 06:00 · l…" — a second line whose only complete word
+ * was "Next". Two facts that both truncate are worth less than one that fits. The forward-looking
+ * one wins when a schedule exists (it is the question the rail answers: does this run itself?),
+ * the last run otherwise. The full picture is one click away in the editor's run history, and the
+ * row's `title` already says both.
+ *
+ * Caught by READING the screenshot: the DOM was correct and the CSS ellipsis was doing exactly
+ * its job. [[ui-invisible-to-assertions]] — judge the pixels even when everything is green.
+ */
+function railSubtitle(a: Automation): string {
+  /*
+   * ⭐ WAVE 24 (owner item 6, "Run once now is laggy / looks stuck") — WHILE IT IS RUNNING,
+   * THE ONE FACT WORTH THE LINE IS WHAT IT IS DOING.
+   *
+   * MEASURED, not guessed (`scratchpad/perf_automations.py`, mailbox D-5): the engine has been
+   * publishing a live step the whole time (`status.step`, `routes_automation.py:50-51`) and NO
+   * SURFACE HAS EVER RENDERED IT. So a `discover_instagram` run parked in its legitimate
+   * `BD_FILTER_WAIT = 120 s` vendor wait and a genuinely hung thread were pixel-identical: a
+   * pulsing blue dot and a subtitle still reciting the schedule. "Looks stuck" was not a
+   * performance problem — the poll costs 23 ms — it was the product declining to say.
+   *
+   * It takes the line rather than joining it, for the reason this function's note already
+   * gives: the rail is `--lp-rail-w` wide and two facts that both truncate are worth less than
+   * one that fits. The schedule is still one click away and the dot's `title` carries both.
+   */
+  const step = liveStepOf(a);
+  if (step) return step;
+  if (a.schedule?.enabled) return a.nextRunAt ? `Next ${a.nextRunAt}` : "Scheduled";
+  /*
+   * ⭐ WAVE 26 · ITEM 19 / R13 — `Last run 2026-08-06 13:58` IS DELETED FROM THIS LINE.
+   *
+   * ⛔ SCOPE, because R13 draws a line that is easy to over-read: the ruling names THIS secondary
+   * line under the automation's name. The Builder's "Last run succeeded / failed" RESULT lines
+   * (`AutomationBuilder.tsx:1676`, `:1679`) are a different surface and are explicitly NOT in
+   * scope — they are the answer to "Run once now", so deleting them would leave a button with no
+   * outcome.
+   *
+   * "Manual only" STAYS, and the distinction is the ruling's own: a dated run record is a
+   * changing FACT ABOUT THE PAST, while "this one has no schedule" is a stable property of the
+   * automation — the same question `Next …`/`Scheduled` answers for its siblings. Dropping it too
+   * would leave a manual automation with a blank second line and nothing saying why.
+   */
+  return "Manual only";
+}
+
+/*
+ * ⛔ W23-W5's LISTENER IS AT MODULE SCOPE, AND THAT IS THE POINT — not a stylistic choice.
+ *
+ * The frame's click-through sets `window.location.hash = "#/automation"` and signals on the
+ * VERY NEXT LINE (Shell.tsx:1647-1650, and its comment is right that the order matters). But a
+ * hash write does not mount anything synchronously: `hashchange` is delivered as a task, the
+ * router state then updates, React renders, and only THEN does a component effect subscribe.
+ * A listener registered in `useEffect` therefore misses every click that arrives from another
+ * page — which is every click, since a reader looking at Alerts is by definition not already
+ * on this surface. The event would dispatch into nothing and every gate would stay green:
+ * exactly the wave-20 item-25 failure the contract's own note describes, reproduced one layer
+ * down.
+ *
+ * This module is imported statically by the shell, so this listener exists from app start. It
+ * LATCHES the request; the component consumes the latch when it mounts and hears live events
+ * while it is mounted. A request nobody claims is dropped on the next one — the latch is a
+ * one-slot mailbox, never a queue.
+ */
+let pendingOpen: AutomationOpenDetail | null = null;
+const openSubscribers = new Set<(detail: AutomationOpenDetail) => void>();
+
+if (typeof window !== "undefined") {
+  window.addEventListener(AUTOMATION_OPEN_EVENT, (event) => {
+    const detail = (event as CustomEvent<AutomationOpenDetail>).detail;
+    if (!detail?.autoId) return;
+    if (openSubscribers.size) {
+      for (const notify of openSubscribers) notify(detail);
+      return;
+    }
+    pendingOpen = detail;
+  });
+}
+
+/*
+ * ⛔ THE `AUTOMATION_CREATE_EVENT` LISTENER STOOD HERE AND IS DELETED WITH ITS SIGNALLER
+ * (wave 25 item 5a, ruling R8) — latch, subscriber set and all.
+ *
+ * Wave 24 built it to close the opposite defect: the event was declared, signalled from
+ * `Shell.tsx`, and consumed NOWHERE, so all three "Automated database" doors navigated to
+ * `#/automation` and then did nothing, in production, with every gate green. R8 now deletes those
+ * three doors — creating a database and pointing an automation at it are two acts — and they were
+ * the event's only signaller.
+ *
+ * ⛔ SO THIS SIDE GOES TOO, IN THE SAME CHANGE. A listener with no signaller is the same defect
+ * read from the other end: it compiles, it costs nothing at runtime, and it reads to the next
+ * person as a live channel. The rule that catches both is now DERIVED rather than remembered —
+ * `verify_automation_ui.py` enumerates every `AUTOMATION_*_EVENT` in `apiContract.ts` and demands
+ * a signal site AND a listener site for each.
+ *
+ * ⚠ NOTHING ABOUT CREATING AN AUTOMATION IS LOST. `createAndOpen` is untouched and still has two
+ * doors, both on this surface: the rail's button and the empty state's. What is gone is the claim
+ * that a database can be created BY asking for an automation.
+ */
+
+/**
+ * A default name for a brand-new automation, and it has to be one the server ACCEPTS.
+ *
+ * MEASURED against the live route rather than assumed (`scratchpad/probe_names.py`): a create
+ * with no name is a 400 (`name the automation`), and duplicate names are ALLOWED. So the name
+ * cannot be omitted, and a fixed literal would stack "New automation" three deep in a rail that
+ * sorts by name with nothing to tell the rows apart. Numbering from the existing list is a
+ * client-side convenience over a server that does not care: if two tabs race, the loser gets a
+ * duplicate name, which is legal, visible and renameable — never an error the user has to read.
+ */
+function nextAutomationName(existing: Automation[]): string {
+  const taken = new Set(existing.map((a) => (a.name || "").trim().toLowerCase()));
+  for (let n = existing.length + 1; ; n += 1) {
+    // ⭐ WAVE 34 · R12 — "Agent N", not "Automation N". ⚠ THIS ONE IS STORED, so it is the only
+    // string in the rename that leaves a visible seam: automations created before today keep
+    // "Automation 3" as their NAME until somebody renames them. That is correct and deliberate —
+    // a name is a person's own text, and rewriting stored names to match a caption change would
+    // edit user data to tidy a word. The seam is in the rail for a while and then gone.
+    const candidate = `Agent ${n}`;
+    if (!taken.has(candidate.toLowerCase())) return candidate;
+  }
+}
+
+export default function AutomationSurface() {
+  /* ⭐ T22 — SEEDED FROM THE CLIENT MEMO, so a revisit inside the freshness window never passes
+     through `data === null` and therefore never paints the skeleton. The lazy initialiser runs
+     once, on mount, BEFORE the first paint — `useState(cachedAutomations())` would call it on
+     every render instead, which is the same value at needless cost. A cold start still returns
+     null and still gets the skeleton: it is made rare, not removed (see `automationApi.ts`). */
+  const [data, setData] = useState<AutomationList | null>(() => cachedAutomations());
+  const [error, setError] = useState("");
+  const [activeId, setActiveId] = useState<string>("");
+  const [railShut, setRailShut] = useState(false);
+  const [busy, setBusy] = useState("");
+  /**
+   * ⭐ WAVE 24 / C-CREATE — a create is now a ROUND TRIP, not a local wizard, so the door has to
+   * say it is busy. Without this a second click while the POST is in flight makes a second
+   * automation, and the server allows duplicate names, so the user gets two rows that look
+   * identical and no error to explain either of them.
+   */
+  const [creatingNow, setCreatingNow] = useState(false);
+  /** An open request waiting for the list to arrive (see the resolver below). */
+  const [openRequest, setOpenRequest] = useState<AutomationOpenDetail | null>(null);
+  /* ⛔ `createRequest` LEFT WITH THE EVENT THAT SET IT (wave 25, R8) — see the tombstone above. */
+  const listRef = useRef<HTMLDivElement | null>(null);
+
+  /**
+   * ⛔ C14 LEG 2 — THE ID THE USER LAST ASKED FOR, and it is a ref because it has to be
+   * written SYNCHRONOUSLY, inside the click, before any promise that was already in flight
+   * can resolve. State would not do: a resolution racing React's commit would read the
+   * previous value, which is the exact window this guard exists to close.
+   */
+  const wantedId = useRef("");
+
+  /**
+   * ⭐ THE ONLY PLACE THE RAIL'S SELECTION MOVES ON PURPOSE. Every deliberate change of
+   * automation — a rail click, a create, a delete — goes through here, so "what the user
+   * asked for" and "what is on screen" are written in one statement and cannot drift apart.
+   * A resolution that wants to steer the rail compares itself against `wantedId` instead.
+   */
+  const select = useCallback((id: string, _stage = "") => {
+    wantedId.current = id;
+    setActiveId(id);
+  }, []);
+
+  /**
+   * ⭐⭐ W33 (C-18, from lane C) — WHICH PANE AN INBOX ITEM ASKED FOR, and it was DROPPED here.
+   *
+   * ⛔ THE PAYLOAD WAS DECLARED, TRANSPORTED, AND IGNORED AT THE LAST HOP.
+   * `routes_alerts.py` sets `tab: "runs"` on a notification's target, `inboxModel.routeForTarget`
+   * forwards it and `Shell.tsx` signals `{autoId, tab}` — and this file read `openRequest.tab`
+   * NOWHERE. So a person clicking *"12 new creators found"* to see the RUN landed on Properties,
+   * which is [[flag-shipped-without-its-writer]] with the writer present and the READER missing.
+   * ⚠ NOT FIXED BY DELETING `tab` FROM THE CONTRACT, which was the other option C offered: the
+   * field is the only thing that carries "you clicked a run, so show runs", and an inbox that
+   * lands you on the wrong pane is the complaint, not the field.
+   * ⚠ IT IS A ONE-SHOT REQUEST, NOT A CONTROLLED VALUE. Forcing the pane on every render would
+   * take the pane control away from the person the moment after they used it — so this is
+   * consumed by `AutomationDetail` as an INITIAL value keyed on the automation, and cleared here
+   * with the request that carried it.
+   */
+  const [openTab, setOpenTab] = useState<"properties" | "runs" | "">("");
+
+  /**
+   * ⛔ C14 LEG 3 (the paint half) — A STALE READ MAY NOT REPAINT.
+   *
+   * Every call takes the next generation; only the newest one is allowed to `setData`. The
+   * defect this closes is not cosmetic: a poll issued BEFORE a delete resolves AFTER it, and
+   * a list that still contains the deleted automation puts a row back in the rail that the
+   * user has just watched disappear. Same for a toggle, and same for a create.
+   *
+   * ⚠ THE RETURN VALUE IS NOT GUARDED, deliberately. The caller asked a question and gets
+   * its own answer — coupling the two would mean a create whose `load()` was overtaken by a
+   * poll silently failed to select the automation it had just made.
+   */
+  const gen = useRef(0);
+
+  const load = useCallback(async (abort?: AbortSignal) => {
+    const mine = ++gen.current;
+    try {
+      const next = await listAutomations(abort);
+      if (mine === gen.current) {
+        setData(next);
+        setError("");
+      }
+      return next;
+    } catch (e) {
+      if ((e as Error)?.name === "AbortError") return null;
+      if (mine === gen.current)
+        setError(
+          e instanceof AutomationError
+            ? e.message
+            : "The automation service did not answer."
+        );
+      return null;
+    }
+  }, []);
+
+  /**
+   * ⭐⭐ WAVE 31 · T31 — one freshly-written automation replaces its own row, with no round trip.
+   *
+   * ⚠ IT TAKES THE GENERATION, and that is not decoration. `load`'s guard exists so a stale READ
+   * cannot repaint; a WRITE response is by definition newer than any read already in flight, so it
+   * must win the same race rather than sit outside it. Without the bump, a `GET /automations`
+   * issued before the save could resolve after the merge and paint the pre-save row back — the
+   * exact ghost `gen` was introduced for, arriving through the new door.
+   *
+   * ⚠ Returns FALSE when there is nothing to merge into (a cold surface has no memo), and the
+   * caller then does a real load. Painting a one-row list would be worse than a round trip.
+   */
+  const mergeSaved = useCallback((fresh: Automation) => {
+    const next = rememberAutomation(fresh);
+    if (!next) return false;
+    gen.current += 1;
+    setData(next);
+    setError("");
+    return true;
+  }, []);
+
+  useEffect(() => {
+    const ac = new AbortController();
+    void load(ac.signal);
+    return () => ac.abort();
+  }, [load]);
+
+  /**
+   * ⭐⭐ WAVE 24 / C-CREATE (a) — CREATE AND OPEN. This REPLACED the three-step wizard.
+   *
+   * R6 is what makes it possible: `plain` is a real kind with no machine graph nodes, and it is
+   * what `POST /automations` stores when the body names none. So "new automation" stopped being
+   * a question ("which of three kinds?" — two of which can no longer be created at all) and
+   * became what it says: a new automation, open, on its trigger picker. Choosing a SOURCE is now
+   * picking the `ig_profile_match` trigger, which is where that choice belongs.
+   *
+   * ⛔ THE GUARD IS A REF, not the `creatingNow` state, and this file already carries the scar
+   * that explains why (C14 leg 2): a state read inside a click closure is the value from the
+   * last render, so two fast clicks both see `false` and both POST. Duplicate names are legal
+   * server-side, so the user would get two identical rows and no error. The ref is written
+   * synchronously, inside the click, before anything can await.
+   */
+  const creatingRef = useRef(false);
+  const createAndOpen = useCallback(async () => {
+    if (creatingRef.current) return;
+    creatingRef.current = true;
+    setCreatingNow(true);
+    try {
+      const res = await createAutomation({
+        name: nextAutomationName(data?.automations || []),
+      });
+      const id = res?.automation?.id || "";
+      // The create flow is the one caller allowed to name a different id (C14 leg 2) — the
+      // automation did not exist when the click happened, so there is nothing to race with.
+      const next = await load();
+      if (id && next) select(id);
+    } catch (e) {
+      setError(
+        e instanceof AutomationError ? e.message : "The automation was not created."
+      );
+    } finally {
+      creatingRef.current = false;
+      setCreatingNow(false);
+    }
+  }, [data, load, select]);
+
+  // A run is a background thread on the server, so the surface has to ASK whether it
+  // finished. Polling only while something is actually running keeps an idle surface
+  // silent — a fixed interval would be a request every few seconds forever, for a page
+  // whose contents change a handful of times a day.
+  //
+  // ⛔ C14 LEG 3 (the abort half). It used to call `load()` bare — no signal, nothing to
+  // cancel — so a request the interval had already issued kept going after the effect that
+  // owned it was gone. One controller per effect run, aborted with the interval, means a poll
+  // cannot outlive the condition that justified it. The generation guard inside `load` covers
+  // the rest: a response that survives the abort still cannot repaint over a newer one.
+  //
+  // ⭐ WAVE 24 (item 6, C-PERF) — THE INTERVAL BECAME A BACKOFF, and the measurement is why it is
+  // a SMALL change rather than the big one the contract's hypothesis 2 asked for.
+  //
+  // MEASURED (`scratchpad/perf_automations.py`, mailbox D-5): this poll costs ~23 ms and 24 KB
+  // for a ten-automation tenant, and the engine work the hypothesis blamed — a `graph()` rebuild
+  // per automation — is **41 µs each**, i.e. under 4% of the request. The payload was never the
+  // problem, so nothing here gets a cheaper endpoint.
+  //
+  // What the numbers DO indict is the aggregate: a discovery run legitimately blocks up to
+  // `BD_FILTER_WAIT` = 120 s, and two independent 2.5 s polls across this file and the detail
+  // spend ~96 requests and ~2.3 MB over that window — in the same single process the run itself
+  // is a thread in. So the delay grows 2.5 → 5 → 8 s and stops there.
+  //
+  // ⚠ NOT "to learn nothing", and the distinction is the whole justification. That WAS true when
+  // this file rendered no live step: the poll's only observable effect was a dot that had already
+  // been pulsing for two minutes. It stopped being true in this same change — `liveStepOf` now
+  // paints `status.step`, so a poll carries the one fact worth having. The backoff is therefore
+  // NOT "stop asking a pointless question"; it is FEWER ROUND TRIPS FOR THE SAME INFORMATION, on
+  // a step text that changes every few seconds at most, not every 2.5.
+  // The cap is deliberately low: it bounds how long a FINISHED run can still look live, which is
+  // the only thing a backoff can make worse, and 8 s of that is worth ~⅔ fewer requests.
+  //
+  // ⛔ THE KEY IS THE RUNNING SET, NOT A BOOLEAN, and that is what makes the reset correct: the
+  // effect re-runs — and the delay drops back to 2.5 s — the moment a run starts or finishes, so
+  // a user who clicks Run now gets the fast cadence again instead of inheriting the tail of the
+  // previous run's backoff. A bare `anyRunning` boolean cannot see the second run start.
+  // A step text changing does NOT re-key it, so the interval never thrashes.
+  //
+  // C14 LEG 3 (the abort half) is unchanged and still load-bearing: one controller per effect
+  // run, aborted with the timer, so a poll cannot outlive the condition that justified it. The
+  // generation guard inside `load` covers the rest.
+  const runningKey = (data?.automations || [])
+    .filter((a) => a.running)
+    .map((a) => a.id)
+    .sort()
+    .join(",");
+  useEffect(() => {
+    if (!runningKey) return undefined;
+    const ac = new AbortController();
+    let delay = POLL_MIN_MS;
+    let timer = 0;
+    const tick = () => {
+      void load(ac.signal);
+      delay = Math.min(delay * 2, POLL_MAX_MS);
+      timer = window.setTimeout(tick, delay);
+    };
+    timer = window.setTimeout(tick, delay);
+    return () => {
+      window.clearTimeout(timer);
+      ac.abort();
+    };
+  }, [runningKey, load]);
+
+  // ── W23-W5, the surface's half: hear the request, then answer it when we CAN ──────────
+  useEffect(() => {
+    const notify = (detail: AutomationOpenDetail) => setOpenRequest(detail);
+    openSubscribers.add(notify);
+    if (pendingOpen) {
+      const latched = pendingOpen;
+      pendingOpen = null;
+      setOpenRequest(latched);
+    }
+    return () => {
+      openSubscribers.delete(notify);
+    };
+  }, []);
+
+  /* ⛔ THE C-CREATE(b) SUBSCRIBE EFFECT AND ITS RESOLVER STOOD HERE (wave 25, R8). They heard the
+     create event and, once the list had arrived, called `createAndOpen` — the "wait for the list
+     or every automation is named Automation 1" note lives on in `nextAutomationName`, which is
+     still numbered off `existing`. With no signaller there is nothing to hear. */
+
+  /**
+   * ⚠ THE REQUEST OUTLIVES THE FETCH, and it has to. The reader clicks a notification from
+   * another page, so this surface is mounting WITH AN EMPTY LIST — "select it if it is in the
+   * list" would drop every real click and keep only the one case where the reader was already
+   * here. So the request is held until `data` exists, and only then answered.
+   *
+   * An automation the reader can no longer open does NOTHING (the contract's own words): the
+   * request is cleared either way, so a stale id cannot sit here re-firing against every
+   * subsequent list.
+   */
+  useEffect(() => {
+    if (!openRequest || !data) return;
+    const found = (data.automations || []).some((a) => a.id === openRequest.autoId);
+    if (found) {
+      select(openRequest.autoId, openRequest.stageId || "");
+      // C-18: the pane the notification asked for, read at the one moment it means something.
+      const want = String((openRequest as { tab?: string }).tab || "");
+      setOpenTab(want === "runs" || want === "properties" ? want : "");
+    }
+    setOpenRequest(null);
+  }, [openRequest, data, select]);
+
+  const items = data?.automations || [];
+  const active = items.find((a) => a.id === activeId) || null;
+
+  /**
+   * ⭐⭐ WAVE 32 · T43 (owner item 2) — TURNING AN AUTOMATION ON OR OFF STOPS TAKING FOREVER.
+   *
+   * Owner: turning an automation on or off "takes forever". ⛔ THE TICKET'S HYPOTHESIS WAS THE
+   * SERVER AND IT IS NOT — MEASURED. `engine.patch` for a schedule-only body takes ONE
+   * `automations` bucket read, ZERO `user_tables` reads and ~1 ms against a 2.8 MB fixture, and
+   * `GET /automations` is one read too since W30-T12. The cost was never the document shape
+   * (D-179/D-175's family): it was that this handler paid **two sequential round trips** for one
+   * click, and painted nothing until BOTH had landed. The second one re-downloaded the entire
+   * rail payload — 88,771 B measured, see the note at the top of this file — to learn one boolean
+   * the first response had already returned.
+   *
+   * ⛔ AND THE FIX ALREADY EXISTED IN THIS FILE, POINTED AT A DIFFERENT BUTTON. `mergeSaved` is
+   * W31-T31, built for the detail pane's saves, with its own note about the write response being
+   * newer than any read in flight. The rail's own switch never got it — a fix applied to one of
+   * two twins, which is this wave's recurring shape.
+   *
+   * Three states, in order, and the middle one is what the owner actually asked for:
+   *   1. FLIP IT NOW. The switch is the user's instruction, not a question; painting it after a
+   *      network round trip is what "takes forever" describes even when the round trip is fast.
+   *   2. adopt the server's own answer when it lands, which carries the derived fields an
+   *      optimistic row cannot invent (`nextRunAt`, the status line).
+   *   3. put the OLD row back if the write failed, beside the error — an optimistic switch that
+   *      stays on after a refusal is a lie, and a worse one than a slow switch.
+   *
+   * ⚠ `mergeSaved` TAKES THE GENERATION, which is what stops [[refetch-eats-its-own-write]] here:
+   * a `GET /automations` issued before the click can still resolve after it, and without the bump
+   * it would paint the pre-toggle row back over both the optimistic flip and the confirmation.
+   * ⚠ `busy` is no longer what makes the switch look right — it stays only to keep a second click
+   * from racing the first.
+   */
+  const toggleEnabled = async (a: Automation) => {
+    const flipped: Automation = {
+      ...a,
+      schedule: { ...a.schedule, enabled: !a.schedule.enabled },
+    };
+    setBusy(a.id);
+    const painted = mergeSaved(flipped);
+    try {
+      const { automation: fresh } = await patchAutomation(a.id, {
+        schedule: { cron: a.schedule.cron, enabled: !a.schedule.enabled },
+      });
+      // A cold surface has no memo to merge into (`mergeSaved` answers false), and a one-row
+      // repaint would be worse than a round trip — the same rule `onSaved` follows.
+      if (!fresh || !mergeSaved(fresh)) await load();
+    } catch (e) {
+      if (painted) mergeSaved(a);
+      setError(e instanceof AutomationError ? e.message : "That change was not saved.");
+    } finally {
+      setBusy("");
+    }
+  };
+
+  const onRailKey = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
+    const rows = Array.from(
+      listRef.current?.querySelectorAll<HTMLButtonElement>(".auto-row-main") || []
+    );
+    if (!rows.length) return;
+    event.preventDefault();
+    const at = rows.indexOf(document.activeElement as HTMLButtonElement);
+    const next = event.key === "ArrowDown" ? (at + 1) % rows.length
+      : (at - 1 + rows.length) % rows.length;
+    rows[next < 0 ? 0 : next]?.focus();
+  };
+
+  return (
+    <div className="auto-surface">
+      <aside
+        className={"auto-rail" + (railShut ? " is-collapsed" : "")}
+        /* ⭐ WAVE 34 · R12 — an aria-label IS user-facing copy. A screen reader announces this
+           landmark by name, so leaving it "Automations" would have the module answer to two
+           different words depending on how you read the page. */
+        aria-label="Agents"
+      >
+        {/* The same three-bars fold control the Views rail carries — the two rails are
+            one idea, so they must not fold with two different affordances. */}
+        <div className="auto-rail-top">
+          <button
+            type="button"
+            className="cg-rail-toggle"
+            aria-label={railShut ? "Expand automations" : "Minimize automations"}
+            aria-expanded={!railShut}
+            title={railShut ? "Expand automations" : "Minimize automations"}
+            onClick={() => setRailShut((v) => !v)}
+          >
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+              <path
+                d="M2.5 4.4h11M2.5 8h11M2.5 11.6h11"
+                stroke="currentColor"
+                strokeWidth="1.35"
+                strokeLinecap="round"
+              />
+            </svg>
+          </button>
+        </div>
+
+        <div className="auto-create">
+          <button
+            type="button"
+            className="auto-create-btn"
+            disabled={creatingNow}
+            onClick={() => void createAndOpen()}
+          >
+            <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+              <path
+                d="M8 3.4v9.2M3.4 8h9.2"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+              />
+            </svg>
+            New agent
+          </button>
+        </div>
+
+        <div className="auto-list" ref={listRef} onKeyDown={onRailKey}>
+          {items.map((a) => {
+            return (
+              <div
+                key={a.id}
+                className={"auto-row" + (a.id === activeId ? " is-active" : "")}
+              >
+                <button
+                  type="button"
+                  className="auto-row-main"
+                  onClick={() => select(a.id)}
+                >
+                  {/* ⭐ ITEM 18 / R14 — THE LOOP MARK, WHERE THE STATUS DOT WAS. Same mark on
+                      every row, no status colour: the owner's point is that an automation IS a
+                      loop, not that this one is green. The `.auto-loopmark` wrapper is what sizes
+                      it — `.lp-mark` is shell-owned CSS and outside this session's region, so the
+                      box is mine and the mark is theirs. */}
+                  <span className="auto-loopmark">
+                    <Mark size={15} />
+                  </span>
+                  <span className="auto-row-text">
+                    <span className="auto-row-name">{a.name}</span>
+                    <span className="auto-row-desc">{railSubtitle(a)}</span>
+                  </span>
+                </button>
+                <button
+                  type="button"
+                  className={"auto-row-switch" + (a.schedule?.enabled ? " is-on" : "")}
+                  disabled={busy === a.id}
+                  aria-pressed={!!a.schedule?.enabled}
+                  title={
+                    a.schedule?.enabled
+                      ? `Scheduled: ${a.schedule.cron}. Click to pause.`
+                      : "Not scheduled. Click to enable."
+                  }
+                  onClick={() => void toggleEnabled(a)}
+                >
+                  <span className="auto-row-switch-knob" />
+                </button>
+              </div>
+            );
+          })}
+          {/* ONE LINE (R13). It used to describe the kinds — "one reads a public web page…
+              the other fills an automation column…" — which was two sentences, wrong by the
+              time a third kind shipped, and printed inside a `--lp-rail-w` column. What the
+              kinds are belongs to the create form, which is one click away and lists all of
+              them from the server. */}
+          {/* ⭐ WAVE 29 (W29-T01) — A LOADING RAIL IS NOT AN EMPTY ONE. `data` is null until the
+              first `listAutomations()` resolves, and this branch read only `items.length`, so
+              every visit to Automation asserted "No automations yet." to a person who has
+              several — then replaced it with their list. Half of owner item 5's "takes a while
+              to appear" is that sentence: the wait is real, but being told you own nothing is
+              what makes it read as broken rather than slow. `data === null` is the one state
+              that means NOBODY HAS LOOKED, and it gets skeleton rows, not a claim. */}
+          {data === null && !error ? (
+            <div className="auto-rail-loading" aria-hidden="true">
+              <span className="auto-rail-skel" />
+              <span className="auto-rail-skel" />
+              <span className="auto-rail-skel" />
+            </div>
+          ) : null}
+          {data !== null && !items.length && !error ? (
+            <p className="auto-rail-empty">No agents yet.</p>
+          ) : null}
+        </div>
+      </aside>
+
+      <section className="auto-main">
+        {error ? (
+          <div className="auto-banner is-error" role="alert">
+            {error}
+          </div>
+        ) : null}
+        {data && !data.storeAvailable ? (
+          <div className="auto-banner is-warn" role="status">
+            The tenant store is unavailable, so nothing can be saved right now.
+          </div>
+        ) : null}
+
+        {/*
+          ⛔ THE `creating` BRANCH IS GONE (wave 24, C-CREATE a / owner items 3 + 4).
+          `AutomationCreate` used to render here — a three-step wizard whose first step asked
+          which DATABASE to write into (an existing one, a new one, or one the automation itself
+          would create) and whose second asked which of three KINDS.
+          R6 retires that question at the root: two of the three kinds can no longer be created
+          at all, and the third is now reached by picking a trigger. A new automation is created
+          the moment it is asked for (`createAndOpen`) and opens on its own Builder, so there is
+          no intermediate face left to render and no `creating` state to hold.
+          ⭐ WAVE 25 (R8) retires the LAST of that vocabulary: the third answer was the
+          "automated database", and it is gone from every door in the product. This button is now
+          one of exactly two ways to make an automation, and both are on this surface.
+          The import went with it — it is what would break `npx tsc -b` for the WHOLE client the
+          moment session B deletes the file, which is why this deletion is sequenced first.
+        */}
+        {/* T21: the editor's own Suspense boundary — see the `lazy()` above for why it cannot be
+            `Shell.tsx`'s. `fallback={null}`, matching `Lazily`. */}
+        {active ? (
+          <Suspense fallback={null}>
+          <AutomationDetail
+            key={active.id}
+            automation={active}
+            /* C-18: which pane the Inbox asked for, or "" for the ordinary open. Consumed ONCE,
+               as an initial value — see `openTab`'s note on why it is not controlled. */
+            openTab={openTab}
+            /* ⛔ `kinds={data?.kinds || []}` LEFT HERE WITH THE PROP IT FED (wave 25, D-57) —
+               both halves in one change, because either alone is a `tsc` error. */
+            cronPresets={data?.cronPresets || []}
+            paidReady={!!data?.paidReady}
+            discover={data?.discover}
+            // The trigger vocabulary (C3). Forwarded as-is — absent stays absent, so the
+            // trigger face can tell "the server offered nothing" from "the server offered
+            // an empty list" rather than collapsing both into a picker with no options.
+            triggers={data?.triggers}
+            // C4's action menu + the builder's ceilings. Forwarded as-is for the same reason
+            // `triggers` is: absent must stay absent, so the builder can tell "the server
+            // offered nothing" from "the server offered an empty list".
+            catalog={data?.actionsCatalog}
+            vocab={data?.flow}
+            // `?? null` and never `|| {enabled:false}`: an absent tick bit is "the server did
+            // not say", which Step 1 prints as its own sentence. Defaulting it here would
+            // turn a missing field into a claim about production (C6 amendment #1).
+            tick={data?.tick ?? null}
+            /*
+             * ⭐ W24-W1 (item 6) — WHAT THIS RUN IS DOING, on the one surface that survives in
+             * BOTH views. REQUIRED on the far side deliberately: an optional prop that nobody
+             * passes degrades to "the feature does not exist", which is indistinguishable from
+             * "it was never built" — and this whole item exists because a live step text rode
+             * the wire for three waves with nothing rendering it.
+             * `liveStepOf` returns the step ONLY while the automation is running; a stale step
+             * from a finished run is a worse answer than none.
+             */
+            liveStep={liveStepOf(active)}
+            /*
+             * ⛔ C14 LEG 2 — THE STALE-ID WRITE-BACK, and this is the ghost's second cause.
+             *
+             * The detail calls `onSaved(automation.id)` from six places (save, the trigger
+             * picker, a schedule change, a node switch, a card move, a run). Each closure
+             * captures the automation it was mounted for, so a save that resolves AFTER the
+             * user has clicked a different row used to call `setActiveId(the OLD id)` — the
+             * rail jumped back, the detail remounted, and what the user saw was the previous
+             * automation reappearing over the one they had just opened. It looked like a
+             * rendering bug; it was a resolution steering the selection.
+             *
+             * A resolution may no longer steer anything. It reloads the list — that part was
+             * always right — and it re-asserts the selection ONLY when its id is still the one
+             * the user asked for, which makes the write a no-op in the good case and nothing
+             * at all in the bad one.
+             */
+            onSaved={async (id, fresh) => {
+              // ⭐⭐ WAVE 31 · T31 — CORRECT THE ONE ROW WE WERE JUST TOLD ABOUT.
+              // `patchAutomation` and `toggleNode` return the updated definition; re-reading the
+              // whole list to learn it is the second of the two round trips "Saving…" used to
+              // span. `mergeSaved` keeps the memo and the component in step (see
+              // `automationApi.rememberAutomation`) and takes the generation, because a write
+              // response is newer than any read still in flight — the same rule `load` follows,
+              // pointed the other way.
+              if (fresh && mergeSaved(fresh)) {
+                if (id && id === wantedId.current) select(id);
+                return;
+              }
+              const next = await load();
+              if (id && next && id === wantedId.current) select(id);
+            }}
+            onDeleted={async () => {
+              select("");
+              await load();
+            }}
+          />
+          </Suspense>
+        ) : (
+          /*
+           * THE EMPTY STATE IS ONE LINE AND A BUTTON (owner ruling R13 — "never
+           * over-explain", now a DESIGN.md law).
+           *
+           * It was a heading, a three-sentence paragraph and a 130-word bulleted list
+           * describing all three kinds. Every word of it was true and none of it was READ:
+           * an empty state is passed through, not studied, and the person looking at it has
+           * already decided to make an automation. The kinds are described where the choice
+           * is actually made — the create form lists them FROM THE SERVER, so that copy also
+           * cannot go stale the way this list had (it described two kinds after a third
+           * shipped).
+           *
+           * The button is here rather than only in the rail because this pane is where the
+           * eye is; a create affordance the user has to go find is the same defect as the
+           * paragraph, spent differently.
+           */
+          <div className="autob-empty">
+            {/*
+              ⛔ NO TITLE HERE ANY MORE (C13, owner item 2). This pane carried an `h1`
+              reading "Automations" at 20px/600 — a THIRD title treatment on a page that
+              also had the header's editable 16px/700 input, against every database page's
+              single 16px/650 `shell-db-name`. The shell now wraps this branch in the same
+              `shell-db-frame` + `DbHead` a database gets (wiring W23-W1), so the page's name
+              is drawn once, by the one component that draws every other page's name. A
+              stand-in restyled to match would have been a second copy of the same fact,
+              free to drift the day the header moves.
+            */}
+            <p className="autob-empty-line">
+              A job this workspace runs for you, on demand or on a schedule.
+            </p>
+            <button
+              type="button"
+              className="auto-btn is-primary"
+              disabled={creatingNow}
+              onClick={() => void createAndOpen()}
+            >
+              New agent
+            </button>
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}

web/src/automation/AutomationTrigger.tsx

@@ -98,8 +98,8 @@ function needsLabel(needs: string): string {
  * declared-but-not-built ("coming soon", R2) which is waiting on us.
  */
 function optionLabel(t: TriggerOption): string {
-  if (t.planned) return `${t.label} — coming soon`;
-  return t.ready === false ? `${t.label} — needs setting up` : t.label;
+  if (t.planned) return `${t.label}. Coming soon`;
+  return t.ready === false ? `${t.label}. Needs setting up` : t.label;
 }
 
 /**
@@ -119,13 +119,13 @@ function tickNote(tick: TickState | null): { text: string; tone: string } {
   // fire" as though it had been measured.
   if (!tick || typeof tick.enabled !== "boolean") {
     return {
-      text: "Whether this deployment runs schedules is not reported here yet — press Run now if you need it now.",
+      text: "Whether this deployment runs schedules is not reported here yet. Press Run now if you need it now.",
       tone: "is-unknown",
     };
   }
   if (!tick.enabled) {
     return {
-      text: "Schedules won't fire on this deployment — ask your admin to switch the scheduler on. Run now still works.",
+      text: "Schedules won't fire on this deployment. Ask your admin to switch the scheduler on. Run now still works.",
       tone: "is-off",
     };
   }
@@ -365,7 +365,7 @@ export default function AutomationTrigger({
         <div className="autob-needs">
           <span className="autob-needs-text">
             {connected
-              ? "Connected — this trigger is still being switched on for this deployment."
+              ? "Connected. This trigger is still being switched on for this deployment."
               : "This trigger is not set up yet."}
           </span>
           {!connected && startUrl ? (
@@ -392,7 +392,7 @@ export default function AutomationTrigger({
             ? tick && tick.enabled === false
               ? `It would run next at ${nextRunAt}, once a scheduler is running.`
               : `Next run ${nextRunAt}.`
-            : "Schedules start from the moment they are switched on — turning on a daily job after today's time does not fire it today."
+            : "Schedules start from the moment they are switched on. Turning on a daily job after today's time does not fire it today."
           : current === "manual"
             ? "It runs when you press Run now, and nothing else starts it."
             : /*

web/src/automation/automation.css

@@ -0,0 +1,176 @@
+/* ---------------------------------------------------------------------------
+   automation/automation.css — the Agent module's OWN stylesheet.
+
+   ⭐⭐ WAVE 34 · W34-T41 — THIS FILE IS NEW, AND ITS EXISTENCE IS THE POINT.
+
+   Until today this module had NO scoped CSS at all: every `auto-*`, `autob-*` and `autox-*` rule
+   lived in the shared global `src/index.css`, which the wave PRD assigns to session C. That made
+   any new rule here a cross-fence ask, for styling nobody else can see — the PRD's own remedy is
+   "put NEW rules in your own module stylesheet (`automation/*.css`)", and this is that file.
+
+   ⛔ WHAT DOES NOT BELONG HERE: an edit to an existing `auto-*` rule. Those still live in
+   `index.css` and are still C's. This file holds rules that did not exist before, so the two can
+   never disagree about one selector.
+
+   ⚠ EVERY COLOUR IS A TOKEN. No literal hex, for the reason the palette block in `index.css`
+   records: a hand-copied brand value silently paints last wave's brand while a comment asserts
+   parity. Light and dark both come free that way.
+   --------------------------------------------------------------------------- */
+
+/* ── the Chat view (R17) ──────────────────────────────────────────────────── */
+
+/* Mirrors `.autox-flow`'s box so switching Canvas <-> Chat does not move the frame around it:
+   same flex growth, same min-height:0 (without which a scrolling child of a flex parent grows
+   the parent instead of scrolling), same scroll ownership. */
+.autoc-chat {
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.autoc-log {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 20px 24px 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+/* The empty state is a SENTENCE, not an illustration: it says what to type, which is the only
+   thing a reader needs from a surface they have never used. DESIGN.md's "never over-explain". */
+.autoc-empty {
+  margin: 0;
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-sm);
+  max-width: 52ch;
+}
+
+.autoc-msg {
+  max-width: 60ch;
+  padding: 10px 14px;
+  border-radius: var(--lp-r-md);
+  font-size: var(--lp-fs-sm);
+  line-height: 1.5;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.autoc-msg.is-you {
+  align-self: flex-end;
+  background: var(--lp-surface-2);
+  color: var(--lp-ink);
+}
+.autoc-msg.is-agent {
+  align-self: flex-start;
+  border: 1px solid var(--lp-line);
+  color: var(--lp-ink);
+}
+/* ⛔ A FAILED TURN IS A MESSAGE, NOT A TOAST. A toast is gone before a reader has finished the
+   sentence, and this surface's failures are things you act on (rephrase, pick a database).
+   ⚠ `--lp-red-deep` / `--lp-red-tint`, CHECKED AGAINST THE PALETTE, not typed from memory: the
+   first draft of this rule used `--lp-danger` and `--lp-danger-line`, and NEITHER EXISTS. A ghost
+   custom property does not fail loudly — it falls back or inherits — so the error message would
+   have painted in ordinary ink and looked like an answer. Same defect T14 caught on
+   `--lp-ink-muted` in the same wave; the palette is the only source worth trusting. */
+.autoc-msg.is-error {
+  align-self: flex-start;
+  border: 1px solid var(--lp-red);
+  background: var(--lp-red-tint);
+  color: var(--lp-red-deep);
+}
+
+/* What the model asked for and the validator would not keep. ⚠ It renders as ORDINARY content,
+   not as a warning ornament: R6's standing rule is that a limit must be REPORTED, and a report
+   nobody reads because it looks like chrome is the same as no report. */
+.autoc-dropped {
+  align-self: flex-start;
+  max-width: 60ch;
+  margin: 0;
+  padding: 8px 12px;
+  border-left: 2px solid var(--lp-line);
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-xs);
+  line-height: 1.5;
+}
+.autoc-dropped ul { margin: 4px 0 0; padding-left: 18px; }
+
+.autoc-compose {
+  flex: 0 0 auto;
+  display: flex;
+  gap: 8px;
+  align-items: flex-end;
+  padding: 12px 24px 20px;
+  border-top: 1px solid var(--lp-line);
+}
+.autoc-input {
+  flex: 1 1 auto;
+  min-width: 0;
+  resize: none;
+  font: inherit;
+  font-size: var(--lp-fs-sm);
+  line-height: 1.5;
+  padding: 8px 10px;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface);
+  color: var(--lp-ink);
+}
+.autoc-input:focus-visible {
+  outline: 2px solid var(--lp-blue-deep);
+  outline-offset: 1px;
+}
+
+/* The pending row. ⚠ It uses `.lp-spin`, the ONE loading mark app-wide (purple as of this wave's
+   T24) — a second spinner vocabulary in a new surface is how an app stops having one. */
+.autoc-pending {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  align-self: flex-start;
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-sm);
+}
+
+/* The accept bar. It is deliberately NOT inside the transcript: accepting is an act on the
+   AUTOMATION, not a reply in the conversation, and putting it in the log would make it scroll
+   away from the thing it acts on. */
+.autoc-accept {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 24px;
+  border-top: 1px solid var(--lp-line);
+  background: var(--lp-surface-2);
+  font-size: var(--lp-fs-sm);
+}
+.autoc-accept-note { color: var(--lp-muted); margin-right: auto; }
+
+/* ── the run log's note disclosure (R21 / W34-T45) ────────────────────────── */
+
+/* ⭐ WAVE 34 · W34-T45. `notes` is up to 300 chars x 25 entries per run and was rendered
+   unconditionally over 20 runs; that is the "too wordy" the owner reported. It is still
+   unconditional for a run that FAILED or hit a cap (R6: a limit must be REPORTED) and behind this
+   disclosure otherwise.
+   ⚠ The list INSIDE stays `.auto-run-notes`, which is C's existing rule in `index.css`. Only the
+   wrapper is new, so the notes themselves cannot start looking different depending on which
+   branch rendered them. */
+.autor-notes {
+  margin: 2px 0 0;
+}
+.autor-notes-toggle {
+  cursor: pointer;
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-2xs);
+  /* The default triangle is the affordance; no custom marker, because a disclosure that does not
+     look like one is how a person decides there is nothing behind it. */
+  list-style: revert;
+}
+.autor-notes-toggle:hover { color: var(--lp-ink); }
+.autor-notes-toggle:focus-visible {
+  outline: 2px solid var(--lp-blue-deep);
+  outline-offset: 1px;
+}

web/src/automation/automationApi.ts

@@ -42,7 +42,18 @@ export type AutomationKind =
   | "field_instagram"
   | "discover_instagram"
   | "discover_tiktok"
-  | "plain";
+  | "plain"
+  /**
+   * ⭐⭐ WAVE 34 · CONTRACT C3 (R13) — an AI enrichment COLUMN, surfaced here as an agent.
+   *
+   * ⛔ NO AUTOMATION IS EVER STORED WITH THIS KIND. It arrives only on the SYNTHETIC rows
+   * `routes_automation._field_agent_rows` derives from field definitions, so it is absent from
+   * the server's `KINDS`, uncreatable by construction, and a `POST /automations` naming it is
+   * refused by the ordinary save door. It is in this union because the wire carries it and the
+   * rail renders it — the comment above this type records what it costs when the wire carries a
+   * value the caller cannot name.
+   */
+  | "field_agent";
 export type RunState = "idle" | "running" | "ok" | "error" | "partial";
 /*
  * ⭐ WAVE 28 · R5 — `CaptureTier` ("anonymous" | "brightdata") IS DELETED. It was the client's
@@ -131,6 +142,20 @@ export interface Automation {
   createdBy?: string;
   nextRunAt?: string;
   running?: boolean;
+  /**
+   * ⭐⭐ WAVE 34 · CONTRACTS C3 + C4 — WHY THIS AGENT CANNOT BE DELETED, as a slug.
+   *
+   * Absent on an ordinary agent. `"field_agent"` is an AI enrichment column surfaced here (R13);
+   * `"odoo_sync"` is the connector's own schedule (R22). ⚠ A STRING, NOT A BOOLEAN: the two
+   * contracts disagreed about that (ask `E-13`), and a slug is what lets the delete refusal NAME
+   * the reason and send the reader to the right place. Truthiness still answers "is this a system
+   * agent", so a caller that only needs that can keep asking it that way.
+   *
+   * ⛔ IT IS NOT A PERMISSION. The server refuses the delete with `409 system_agent` whatever the
+   * client renders; this field exists so the UI can explain BEFORE the click rather than after,
+   * and hiding a control is never the wall.
+   */
+  system?: string;
   /**
    * ⭐ WAVE 26 · ITEM 22 / D-70 / R12 — IS A PAID SEARCH ALREADY OUTSTANDING AT THE PROVIDER?
    *
@@ -471,6 +496,18 @@ export interface ActionCatalogRow {
   group: string;
   ready: boolean;
   detail: string;
+  /**
+   * ⭐⭐ WAVE 34 · W34-T44 / R18 — MAY THE PICKER OFFER IT? Distinct from `ready`, and the
+   * difference is who the row is FOR. `ready:false` is a row a person SHOULD see and cannot use
+   * yet (it answers "can this product do X"); `menu:false` is a row a person should never be
+   * offered but the builder must still be able to READ, because a step stored before the rule
+   * changed still has to render a name instead of its raw kind token.
+   * R18 collapsed six web actions into one; the other five carry `menu:false` and stay in the
+   * catalog because the surviving action composes its own steps out of them server-side.
+   * ⚠ OPTIONAL FOR ONE REASON ONLY: a server that predates this wave stamps nothing, and an
+   * absent value must mean OFFERED. `groupActions` tests `=== false` for exactly that.
+   */
+  menu?: boolean;
   /**
    * ⭐ WAVE 24 / C-ACT — THE SERVER DECIDES THE MENU'S GROUP ORDER, and the client sorts by
    * this number and **never by a literal list of group names**. A hard-coded
@@ -976,6 +1013,66 @@ export function createAutomation(body: unknown): Promise<{ automation: Automatio
   return send("/automations", { method: "POST", body: JSON.stringify(body) });
 }
 
+/**
+ * ⭐⭐ WAVE 34 · W34-T42 / R17 — a plain-English description becomes a DRAFT flow.
+ *
+ * ⛔ THE DOOR IS NOT NEW; THE CALLER IS. `POST /api/v1/automations/draft` shipped in wave 33 and
+ * `D-269` books it as having had NO front-end caller ever since — a whole, correct, unreachable
+ * feature, which is this repo's most-repeated failure shape. This function is that caller.
+ *
+ * ⛔ `saved: false` IS LOAD-BEARING AND MUST NOT BE OPTIMISED AWAY. The route deliberately writes
+ * NOTHING: accepting a draft is the ordinary `createAutomation`, so a drafted flow and a
+ * hand-built one are the same object by construction rather than by resemblance. A caller that
+ * treated the response as "created" would be inventing a second write path.
+ *
+ * ⚠ `dropped` IS THE HONEST HALF AND IT IS NOT AN ERROR LIST. The route runs the REAL save-door
+ * validator over the model's output and diffs it, because `clean_actions` silently discards a
+ * config key it does not recognise and still answers 200. Anything in `dropped` is something the
+ * person was shown that will NOT be there afterwards; rendering it is R6's second sentence.
+ */
+export interface AutomationDraft {
+  draft: {
+    name?: string;
+    /**
+     * ⚠ A STRING, NOT `{key}`, AND THE FIRST DRAFT OF THIS TYPE GOT IT WRONG. The route returns
+     * `"trigger": _trig or "manual"` — a bare trigger KEY — while a stored automation's own
+     * `trigger` is an object. Typed as `{key?: string}` it compiled, `draft.trigger?.key` read
+     * `undefined` on every draft, and every accepted flow would have silently landed with no
+     * trigger at all. Nothing would have been red: the save succeeds, the flow is valid, and it
+     * simply never fires. Read off the route's own `return`, not from the sibling shape.
+     */
+    trigger?: string;
+    table?: string;
+    actions?: { id?: string; kind?: string; config?: Record<string, unknown>; why?: string;
+                needs?: string[]; unknownField?: string }[];
+  };
+  provider?: string;
+  /**
+   * What the real save-door validator discarded from the model's answer (D-75's channel).
+   *
+   * ⛔ OBJECTS, NOT SENTENCES, AND TYPING IT `string[]` COMPILED. The route builds
+   * `{kind, keys}` per step whose config the validator changed. Rendered as a string each row
+   * would have painted `[object Object]` — a report about what silently changed, itself silently
+   * wrong. Read off the route's `dropped.append(...)`, not from the shape of `notes` beside it.
+   */
+  dropped?: { kind: string; keys: string[] }[];
+  /**
+   * The route's OTHER honest channel, and it is not the same as `dropped`: a trigger this
+   * deployment does not have (corrected to manual, and said), or steps beyond
+   * `MAX_DRAFT_ACTIONS` that were not kept. Both are things the reader must be told, and both
+   * arrive here rather than in `dropped`.
+   */
+  notes?: string[];
+  saved?: boolean;
+}
+
+export function draftAutomation(prompt: string): Promise<AutomationDraft> {
+  return send("/automations/draft", {
+    method: "POST",
+    body: JSON.stringify({ prompt }),
+  });
+}
+
 export function patchAutomation(
   id: string,
   body: unknown
@@ -1153,7 +1250,7 @@ export function runBlock(a: Automation): { blocked: boolean; label: string; why:
       label: "Waiting for results",
       why:
         "The search is already running at the provider and has been paid for. It collects on " +
-        "its own — starting another would buy a second search.",
+        "its own. Starting another would buy a second search.",
     };
   }
   return { blocked: false, label: "", why: "" };
@@ -1176,7 +1273,7 @@ export const COUNT_LABELS: [string, string][] = [
   // property of the data and usually benign; "not written — the database is
   // full" is a property of the system and never is. One chip for both is how a
   // time series stops growing without anybody being told.
-  ["capped", "Not written — the database is full"],
+  ["capped", "Not written. The database is full"],
   ["source_rows", "Rows read"],
   ["profiles", "Profiles"],
   ["ok", "Read in full"],

web/src/automation/steps.ts

@@ -367,11 +367,21 @@ export interface ActionGroup {
  * printed caption ("Web action", "Database", "Connected", "Advanced logic") — the server sends
  * no separate `groupLabel` for actions — so this returns `key` and the caller prints it. Adding
  * a `label` member that merely copied `key` would invent a second name for one string.
+ *
+ * ⭐⭐ WAVE 34 · W34-T44 / R18 — IT IS THE MENU, SO IT HONOURS `menu`. The server ships rows the
+ * picker must not OFFER but the builder must still be able to READ: R18 collapsed six web actions
+ * into one, and the other five stay in the catalog because `_ai_agent_plan` composes the surviving
+ * action's steps out of them. This is the ONE place the distinction is applied, because this is
+ * the one function whose output is a menu — the label lookup in `AutomationBuilder` walks the
+ * unfiltered catalog on purpose, so a step stored last month still renders a name and not a token.
+ * ⚠ `!== false` and not truthiness: the server stamps a real boolean on every row, and an older
+ * server that stamps nothing must keep offering its rows rather than showing an empty picker.
  */
 export function groupActions(rows: ActionCatalogRow[]): ActionGroup[] {
   const out: ActionGroup[] = [];
   const byKey = new Map<string, ActionGroup>();
   for (const c of rows) {
+    if (c.menu === false) continue;
     const key = c.group || "";
     let g = byKey.get(key);
     if (!g) {

web/src/customer-grid/ColumnMenu.tsx

@@ -84,6 +84,18 @@ interface FieldConfigExtra {
    *  it: `_clean_field` accepts a code column without one and it renders as plain text, so this
    *  is an ordinary edit rather than a create requirement. */
   code?: { language: string };
+  /** ⭐⭐ Wave-34 (owner ruling R13) — an AI ENRICHMENT column's config. REQUIRED, like `link`
+   *  and `rollup` and unlike `code`: `_clean_field` returns None for an `ai_enrich` column with
+   *  no bag, because a prompt is the only thing that can ever produce a value here. Shaped
+   *  exactly as `core.user_tables._clean_ai_enrich` stores it, so the panel and the store cannot
+   *  disagree about a key name. */
+  aiEnrich?: {
+    prompt: string;
+    model?: string;
+    maxTokens: number;
+    trigger: { mode: string; cron?: string };
+    overwrite: string;
+  };
 }
 
 interface ColumnMenuProps {
@@ -230,6 +242,11 @@ interface ColumnMenuProps {
    * the control is not rendered at all, so a base field cannot even be offered the action.
    */
   onDelete?: () => void;
+  /** ⭐⭐ Wave-34 (R13) — run this AI enrichment column over many rows.
+   *  `scope` is `"blank"` (only cells still empty) or `"always"` (every row the AI
+   *  wrote). OPTIONAL for `onDelete`'s reason: a host that has not wired the door shows
+   *  no row, rather than a row that does nothing. */
+  onEnrich?: (scope: "blank" | "always") => void;
   /** Wave-5 item 1 — Duplicate field. Supplied for creatable strata only (base Odoo fields
    *  offer no Duplicate — cloning the source of truth into an editable copy is out of scope). */
   onDuplicate?: () => void;
@@ -932,7 +949,7 @@ const AUTOMATION_KINDS: { key: string; label: string; hint: string }[] = [
     key: "instagram_profile",
     label: "Instagram profile",
     hint: "Reads what is anonymously public about the profile in the chosen URL column, and "
-      + "writes the result here. Runs from the Automation surface — on demand or on a schedule.",
+      + "writes the result here. Runs from the Automation surface, on demand or on a schedule.",
   },
 ];
 
@@ -1012,6 +1029,42 @@ function ScopeControl({
  * cannot drift: a FORMULA gets its source editor with live validation and a reference picker;
  * a RATING gets its star count (the contract's 2..10).
  */
+/**
+ * ⭐⭐ Wave-34 (R13) — the AI enrichment draft, as the panel holds it.
+ *
+ * FLAT, while the wire bag nests `trigger`. That is deliberate: a form is edited one control at a
+ * time and a nested draft makes every setter a two-level spread, which is where a patcher drops a
+ * sibling key. `extraFor` does the one nesting at the moment of sending.
+ */
+interface AiEnrichDraft {
+  prompt: string;
+  model: string;
+  maxTokens: number;
+  mode: string;
+  cron: string;
+  overwrite: string;
+}
+
+/** The three moments an enrichment column can run. Mirrors `AI_ENRICH_TRIGGER_MODES`. */
+const AI_ENRICH_MODES: ReadonlyArray<{ value: string; label: string }> = [
+  { value: "manual", label: "Only when I ask" },
+  { value: "on_change", label: "When a referenced column changes" },
+  { value: "schedule", label: "On a schedule" },
+];
+
+/**
+ * What an AUTOMATIC run may replace. ⛔ There is no "overwrite anything" option and there must
+ * not be: a cell somebody typed into is never overwritten by an agent, whatever is chosen here,
+ * so "Every row" means every row THE AI WROTE. The labels say that rather than leaving a user to
+ * discover it, because a control that quietly means less than it says is worse than a narrower
+ * control (`core.user_tables.ai_enrich_human_authored` is the law it is describing).
+ */
+const AI_ENRICH_OVERWRITE: ReadonlyArray<{ value: string; label: string }> = [
+  { value: "blank", label: "Only rows that are still empty" },
+  { value: "stale", label: "Empty rows, and AI answers whose inputs have changed" },
+  { value: "always", label: "Every row the AI wrote, every run" },
+];
+
 function ExtraTypeEditor({
   kind,
   fields,
@@ -1022,6 +1075,8 @@ function ExtraTypeEditor({
   onMaxValue,
   codeLanguage,
   onCodeLanguage,
+  aiEnrich,
+  onAiEnrich,
   idPrefix,
   showFormulaHelp = true,
   automationKind = "instagram_profile",
@@ -1073,6 +1128,12 @@ function ExtraTypeEditor({
    *  which draft it is editing. */
   codeLanguage: string;
   onCodeLanguage: (v: string) => void;
+  /** ⭐⭐ Wave-34 (R13) — the AI enrichment draft. REQUIRED for `codeLanguage`'s exact reason and
+   *  one step stronger: this pane renders the ONLY control that can make an `ai_enrich` column
+   *  creatable at all, so an unwired mount would render a prompt box that saves nothing and a
+   *  Create button that `canCreate` then blocks forever with no visible cause. */
+  aiEnrich: AiEnrichDraft;
+  onAiEnrich: (patch: Partial<AiEnrichDraft>) => void;
   idPrefix: string;
   showFormulaHelp?: boolean;
   /** C5-AUTOFIELD — the automation column's config drafts. Optional so the call sites that
@@ -1232,6 +1293,140 @@ function ExtraTypeEditor({
       </label>
     );
   }
+  if (kind === "ai_enrich") {
+    // ⭐⭐ WAVE-34 (owner ruling R13) — *"a prompt per row that populates text. Detailed
+    // configuration in the field's own config, including a token-usage limit."*
+    //
+    // ⛔ THE PROMPT IS FIRST AND IT IS THE ONLY REQUIRED CONTROL, because it is the only one
+    // without which the column can never hold anything (`_clean_field` refuses the field). The
+    // other four all have a working default, so a user who types one sentence and presses Create
+    // gets a column that runs.
+    // ⚠ Every control below is an EXISTING one (`cg-input`, `cg-select`, `cg-field-hint`,
+    // `<label><span>…`): `index.css` belongs to another lane this wave, so this panel is built
+    // from the vocabulary already in the file rather than from a rule I cannot add.
+    const refs = Array.from(
+      new Set((aiEnrich.prompt.match(/\{([a-zA-Z0-9_]{1,60})\}/g) ?? []).map((m) => m.slice(1, -1)))
+    );
+    const known = new Set(fields.map((f) => f.key));
+    const unknown = refs.filter((r) => !known.has(r));
+    return (
+      <>
+        <label>
+          <span>Prompt</span>
+          <textarea
+            id={`${idPrefix}-ai-prompt`}
+            className="cg-input"
+            rows={3}
+            value={aiEnrich.prompt}
+            placeholder="Summarise what {name} sells, in one line."
+            aria-label="Enrichment prompt"
+            onChange={(event) => onAiEnrich({ prompt: event.target.value })}
+          />
+          {/* ⛔ THE UNRESOLVED-TOKEN WARNING IS NOT DECORATION. A `{token}` naming no column is
+              sent verbatim to the model, which then answers a different question on every row and
+              returns text that looks exactly like a correct answer. The server reports it per row
+              at run time; saying it here costs one run nobody has paid for yet. */}
+          {unknown.length > 0 ? (
+            <span className="cg-field-hint">
+              {unknown.map((u) => `{${u}}`).join(", ")} is not a column on this database. Wrap a
+              column key in braces to put its value into the prompt.
+            </span>
+          ) : (
+            <span className="cg-field-hint">
+              Put a column key in braces to use its value, the way a formula does. Each row gets
+              its own answer.
+            </span>
+          )}
+        </label>
+        <label>
+          <span>When it runs</span>
+          <select
+            id={`${idPrefix}-ai-mode`}
+            className="cg-select"
+            value={aiEnrich.mode}
+            aria-label="When the enrichment runs"
+            onChange={(event) => onAiEnrich({ mode: event.target.value })}
+          >
+            {AI_ENRICH_MODES.map((m) => (
+              <option key={m.value} value={m.value}>
+                {m.label}
+              </option>
+            ))}
+          </select>
+        </label>
+        {/* A cadence box only where a cadence is read. A schedule stored under "Only when I ask"
+            is a setting the user can see and nothing will ever act on, which is the shape D-246
+            wears on the Odoo sync, so the server drops it and this never offers it. */}
+        {aiEnrich.mode === "schedule" ? (
+          <label>
+            <span>Schedule</span>
+            <input
+              id={`${idPrefix}-ai-cron`}
+              className="cg-input"
+              value={aiEnrich.cron}
+              placeholder="0 6 * * *"
+              aria-label="Enrichment schedule"
+              onChange={(event) => onAiEnrich({ cron: event.target.value })}
+            />
+            <span className="cg-field-hint">Minute, hour, day, month, weekday.</span>
+          </label>
+        ) : null}
+        <label>
+          <span>Which rows</span>
+          <select
+            id={`${idPrefix}-ai-overwrite`}
+            className="cg-select"
+            value={aiEnrich.overwrite}
+            aria-label="Which rows a run may fill"
+            onChange={(event) => onAiEnrich({ overwrite: event.target.value })}
+          >
+            {AI_ENRICH_OVERWRITE.map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))}
+          </select>
+          <span className="cg-field-hint">
+            A cell you have typed into is never overwritten by a run, whichever of these is chosen.
+          </span>
+        </label>
+        <label>
+          <span>Token limit per row</span>
+          <input
+            id={`${idPrefix}-ai-tokens`}
+            type="number"
+            className="cg-input"
+            min={16}
+            max={4000}
+            value={aiEnrich.maxTokens}
+            aria-label="Token limit per row"
+            onChange={(event) => onAiEnrich({ maxTokens: Number(event.target.value) || 300 })}
+          />
+          {/* R6's standing rule, at the control rather than in a support answer: a run that hits
+              its ceiling STOPS and says how far it got, so this number is the whole budget's
+              basis and not a soft target. */}
+          <span className="cg-field-hint">
+            Also sets the whole run's budget. A run that reaches it stops and reports how many
+            rows it filled.
+          </span>
+        </label>
+        <label>
+          <span>Model</span>
+          <input
+            id={`${idPrefix}-ai-model`}
+            className="cg-input"
+            value={aiEnrich.model}
+            placeholder="Leave empty for the default"
+            aria-label="Enrichment model"
+            onChange={(event) => onAiEnrich({ model: event.target.value })}
+          />
+          <span className="cg-field-hint">
+            Empty uses the cheapest provider configured on this deployment.
+          </span>
+        </label>
+      </>
+    );
+  }
   if (kind === "created_time") {
     return (
       <div className="cg-field-hint">
@@ -1661,7 +1856,7 @@ function ExtraTypeEditor({
         <RollupConditionList
           idPrefix={`${idPrefix}-rollup-cond`}
           title="Then keep only"
-          hint={"Applied AFTER the window above, over exactly the records it kept — which is "
+          hint={"Applied AFTER the window above, over exactly the records it kept, which is "
             + "what a “σ from the mean” threshold is measured against."}
           conditions={rollupConditions}
           onConditions={(v) => onRollupConditions?.(v)}
@@ -1698,7 +1893,7 @@ function ExtraTypeEditor({
         </label>
         <div className="cg-field-hint">
           {rollupMode === "source"
-            ? "Answered straight from the source — it can total hundreds of thousands of rows because none of them are copied into this database."
+            ? "Answered straight from the source. It can total hundreds of thousands of rows because none of them are copied into this database."
             : "Folds the records a link column reaches, which must already exist in this workspace."}
         </div>
         {rollupMode === "source" ? sourceEditor : linkEditor}
@@ -1740,6 +1935,7 @@ export default function ColumnMenu({
   onUnpin,
   onPeriod,
   onDelete,
+  onEnrich,
   onDuplicate,
   onPermissions,
   onFormat,
@@ -1776,6 +1972,31 @@ export default function ColumnMenu({
   /** ⭐ Wave-27 item 13 (R13) — the create form's code LANGUAGE. Seeded to `plain`, which is
    *  also what an absent bag means, so creating without touching this stores nothing extra. */
   const [codeLanguage, setCodeLanguage] = useState<string>("plain");
+  /**
+   * ⭐⭐ Wave-34 (owner ruling R13) — the create form's AI ENRICHMENT config.
+   *
+   * ⚠ ONE BAG AND ONE PATCHER, not six flat props. `link`/`rollup`/`automation` above are each a
+   * scatter of `xState`/`onXState` pairs, and the scouted consequence is concrete: the swap form
+   * mounts `ExtraTypeEditor` WITHOUT those setters, so choosing one of those kinds there renders
+   * a panel whose controls are wired to `undefined`. A single bag cannot be half-passed, so this
+   * kind cannot arrive at that door inert.
+   * ⚠ The defaults ARE the server's defaults (`AI_ENRICH_DEFAULT_TOKENS = 300`, `mode: manual`,
+   * `overwrite: blank`), so creating without touching anything but the prompt stores exactly what
+   * the panel showed.
+   */
+  const [aiEnrich, setAiEnrich] = useState<AiEnrichDraft>(() => ({
+    prompt: "",
+    model: "",
+    maxTokens: 300,
+    mode: "manual",
+    cron: "",
+    overwrite: "blank",
+  }));
+  /** ⚠ FUNCTIONAL UPDATE, not `setAiEnrich({...aiEnrich, ...patch})`. Two controls in this panel
+   *  can change in one tick (picking `schedule` reveals the cron box, which the user then types
+   *  into), and a spread over a captured `aiEnrich` would drop whichever landed first. */
+  const patchAiEnrich = (patch: Partial<AiEnrichDraft>) =>
+    setAiEnrich((prev) => ({ ...prev, ...patch }));
   /** C5-AUTOFIELD — the create form's automation config. */
   const [automationKind, setAutomationKind] = useState(AUTOMATION_KINDS[0].key);
   const [automationUrlField, setAutomationUrlField] = useState(
@@ -1987,6 +2208,10 @@ export default function ColumnMenu({
     // creating one without this gate produces a column that is named, configured and simply
     // absent on the next read. The same "permanently blank column" argument as the two rules
     // above, one step worse — the column does not exist at all.
+    // ⭐⭐ Wave-34 (R13) — the same argument one kind over: `_clean_field` returns None for an
+    // `ai_enrich` column with no prompt, so creating one without this gate produces a column that
+    // is named, configured and simply absent on the next read.
+    (kind !== "ai_enrich" || aiEnrich.prompt.trim() !== "") &&
     (kind !== "link" || linkTable !== "") &&
     (kind !== "rollup" || (rollupMode === "source"
       // ⭐ 2026-08-09 — the read-through bag. ALL FOUR keys are required by `_clean_rollup`
@@ -2015,6 +2240,26 @@ export default function ColumnMenu({
     // "switch this column back to Plain text" a change that saves. Omitting it instead would
     // inherit the previous language (the patch path's omit-means-keep rule).
     if (t === "code") return { code: { language: lang } };
+    // ⭐⭐ Wave-34 (R13) — the enrichment bag, shaped exactly as `_clean_ai_enrich` stores it.
+    // ⚠ `cron` TRAVELS ONLY WITH `schedule`, and `model` only when set: the server drops both in
+    // those cases anyway, so sending them would put keys in the payload that come back absent,
+    // which is how a panel starts looking like it does not save. Same rule the rollup bags above
+    // follow for `limit`/`sortBy`.
+    if (t === "ai_enrich")
+      return {
+        aiEnrich: {
+          prompt: aiEnrich.prompt.trim(),
+          ...(aiEnrich.model.trim() ? { model: aiEnrich.model.trim() } : {}),
+          maxTokens: aiEnrich.maxTokens,
+          trigger: {
+            mode: aiEnrich.mode,
+            ...(aiEnrich.mode === "schedule" && aiEnrich.cron.trim()
+              ? { cron: aiEnrich.cron.trim() }
+              : {}),
+          },
+          overwrite: aiEnrich.overwrite,
+        },
+      };
     if (t === "automation")
       return {
         automation: {
@@ -2114,7 +2359,20 @@ export default function ColumnMenu({
     swapToNewType != null &&
     swapLabel.trim() !== "" &&
     (!needsOptions(swapToNewType) || swapNewOptions.length > 0) &&
-    (swapToNewType !== "formula" || swapFormulaCheck.ok);
+    (swapToNewType !== "formula" || swapFormulaCheck.ok) &&
+    // ⭐⭐ Wave-34 (R13) — the SAME completeness gate `canCreate` carries, on this door too.
+    //
+    // ⛔ AND THIS DOOR HAD NO SUCH GATE FOR ANY KIND, WHICH IS A PRE-EXISTING DEFECT I AM NOT
+    // FIXING HERE, ONLY REPORTING. `canCreate` refuses a `link` with no target, a `rollup` with
+    // no function and an `automation` with no URL column; this predicate refuses none of them,
+    // and the swap form's own `<ExtraTypeEditor>` mount passes none of their setters either, so
+    // picking one of those three from "Change field" renders a panel wired to nothing and Save
+    // ships whatever stale draft the CREATE pane happens to hold. Booked for the register rather
+    // than repaired mid-ticket ([[defects-that-mask-each-other]] is why: the missing gate and the
+    // missing props hide each other, and fixing one alone arms the other).
+    // ⚠ `ai_enrich` cannot arrive here inert, because it is ONE bag and one patcher rather than a
+    // scatter of optional setters, so this conjunct is the whole of its half.
+    (swapToNewType !== "ai_enrich" || aiEnrich.prompt.trim() !== "");
 
   const createAndSwap = () => {
     if (!swapToNewType || !canCreateSwap) return;
@@ -2219,6 +2477,11 @@ export default function ColumnMenu({
         editLinkSingle !== (field.link?.single === true));
   const canSaveEdit =
     !editBlocked &&
+    // ⭐⭐ Wave-34 (R13) — the third door onto the same completeness rule (`canCreate` and
+    // `canCreateSwap` are the other two). Retyping a column to AI enrichment without a prompt
+    // is refused by the server, so Save is refused here instead: a 400 arriving after the click
+    // is the same "named, configured, gone" surprise one layer later.
+    (editType !== "ai_enrich" || aiEnrich.prompt.trim() !== "") &&
     (editingRelational
       ? (editRollupValid && (editRelationalTouched || editNameDirty) &&
          (field.type !== "link" || editLinkTable !== ""))
@@ -2282,6 +2545,27 @@ export default function ColumnMenu({
                 },
               }
             : {}),
+          // ⭐⭐ Wave-34 (R13) — RETYPING A COLUMN TO AI ENRICHMENT CARRIES ITS BAG, or the
+          // server refuses the whole write: `_clean_field` returns None for an `ai_enrich`
+          // column with no prompt. The edit pane renders the same panel the create pane does
+          // (`ExtraTypeEditor` is mounted with `kind={editType}`), so the draft the user just
+          // filled in is the one sent here.
+          ...(editType === "ai_enrich"
+            ? {
+                aiEnrich: {
+                  prompt: aiEnrich.prompt.trim(),
+                  ...(aiEnrich.model.trim() ? { model: aiEnrich.model.trim() } : {}),
+                  maxTokens: aiEnrich.maxTokens,
+                  trigger: {
+                    mode: aiEnrich.mode,
+                    ...(aiEnrich.mode === "schedule" && aiEnrich.cron.trim()
+                      ? { cron: aiEnrich.cron.trim() }
+                      : {}),
+                  },
+                  overwrite: aiEnrich.overwrite,
+                },
+              }
+            : {}),
           ...(editNameDirty ? { label: cleanRename } : {}),
         }
       );
@@ -2487,6 +2771,8 @@ export default function ColumnMenu({
             </>
           )}
           <ExtraTypeEditor
+            aiEnrich={aiEnrich}
+            onAiEnrich={patchAiEnrich}
             kind={kind}
             fields={fields}
             formulaText={formulaText}
@@ -2657,6 +2943,8 @@ export default function ColumnMenu({
                 {field.type === "rollup" ? "Rollup" : "Linked records"}
               </span>
               <ExtraTypeEditor
+                aiEnrich={aiEnrich}
+                onAiEnrich={patchAiEnrich}
                 kind={field.type}
                 fields={fields}
                 linkTargets={linkTargets}
@@ -2729,6 +3017,8 @@ export default function ColumnMenu({
             <div className="cg-type-block">
               <span className="cg-type-title">Automation</span>
               <ExtraTypeEditor
+                aiEnrich={aiEnrich}
+                onAiEnrich={patchAiEnrich}
                 kind="automation"
                 fields={fields}
                 formulaText={editFormulaText}
@@ -2878,6 +3168,8 @@ export default function ColumnMenu({
           )}
           {!onRetype && field.type === "formula" && onFormula && (
             <ExtraTypeEditor
+              aiEnrich={aiEnrich}
+              onAiEnrich={patchAiEnrich}
               kind="formula"
               fields={fields}
               formulaText={editFormulaText}
@@ -2978,6 +3270,8 @@ export default function ColumnMenu({
                     />
                   </label>
                   <ExtraTypeEditor
+                    aiEnrich={aiEnrich}
+                    onAiEnrich={patchAiEnrich}
                     kind={swapToNewType}
                     fields={fields}
                     formulaText={swapFormulaText}
@@ -3501,6 +3795,40 @@ export default function ColumnMenu({
         >
           <MenuLabel icon="hide" text="Hide field" />
         </button>
+        {/* ⭐⭐ WAVE-34 (owner ruling R13) — THE BULK RUN, and it is TWO rows rather than one
+            because "run this column" is two different questions with two different bills.
+            ⛔ NEITHER LABEL SAYS "everything". `ai_enrich_may_write` refuses a human-edited cell
+            under every policy, so "All rows" means every row the AI wrote; saying "all" flat
+            would be a control that quietly means less than it says, which is worse than a
+            narrower control. The server takes these as `scope: "blank" | "always"`.
+            ⚠ `onEnrich` is OPTIONAL, exactly as `onDelete` above it is: a host that has not
+            wired the door renders no row rather than a row that does nothing.
+            ⛔ THE GLYPH IS `FieldTypeIcon`, NOT A `MenuIcon` NAME, and that is not a style
+            choice. `MenuLabel`'s prop is `MenuIconName | ReactNode`, and `ReactNode` admits
+            any string, so `icon="sparkle"` COMPILES and renders an empty glyph box forever
+            (`MENU_ICONS` has no such key). Reusing the type icon paints the same mark the
+            column header and the add-field picker already wear, from one geometry source, and
+            needs no new key in a file no lane owns. [[schema-role-is-not-a-value-wall]] */}
+        {field.type === "ai_enrich" && onEnrich && (
+          <>
+            <button
+              type="button"
+              title="Fills only the cells that are still empty. Costs nothing for rows that already have an answer."
+              onClick={() => onEnrich("blank")}
+            >
+              <MenuLabel icon={<FieldTypeIcon type="ai_enrich" size={16} />}
+                text="Fill rows never filled" />
+            </button>
+            <button
+              type="button"
+              title="Re-asks the model for every row the AI wrote. A cell you have typed into is left alone."
+              onClick={() => onEnrich("always")}
+            >
+              <MenuLabel icon={<FieldTypeIcon type="ai_enrich" size={16} />}
+                text="Fill all rows again" />
+            </button>
+          </>
+        )}
         {!schemaLocked && onDelete && (
           <button
             type="button"
@@ -3523,11 +3851,11 @@ export default function ColumnMenu({
               field.measure
                 ? "Removes this formula column from the workspace."
                 : field.automation?.preset === true
-                ? "Part of this database's built-in schema — it will be re-created on the " +
+                ? "Part of this database's built-in schema. It will be re-created on the " +
                   "next run. Hide it to keep it off the grid."
                 : field.type === "rollup" || field.type === "link" ||
                   field.type === "formula"
-                ? "Removes this column. No values are lost — it holds none of its own."
+                ? "Removes this column. No values are lost. It holds none of its own."
                 : "Removes this field AND its values on every row."
             }
             onClick={() => (confirmDelete ? onDelete() : setConfirmDelete(true))}

web/src/customer-grid/CustomerGrid.tsx

@@ -60,7 +60,7 @@ import { NAV_MINIMIZE_EVENT, ROWS_STALE_EVENT, TOAST_EVENT, VIEW_OPEN_EVENT,
   from "../apiContract";
 import type { ViewOpenDetail } from "../apiContract";
 import { addTableField, addTableRow, deleteTableField, deleteTableRow, fetchLinkTargets,
-  fetchRollupSources, patchTableField } from "./apiBridge";
+  fetchRollupSources, patchTableField, enrichField } from "./apiBridge";
 import type { LinkTarget, RollupSourceOffer } from "./apiBridge";
 import SelectFromFile from "./SelectFromFile";
 import ImportDialog from "./ImportDialog";
@@ -76,7 +76,7 @@ import { buildTsCsv, tsSheetToTable } from "./timeSeriesData";
 import type { TsSheet } from "./timeSeriesData";
 import { echoReemit, reconcileEchoView } from "./viewEcho";
 import { pruneStamps, reconcileFields } from "./optimism";
-import { applyViewOrder, newFolderId, pruneFolderStamps, reconcileFolders,
+import { applyViewOrder, isSyntheticFolderId, newFolderId, pruneFolderStamps, reconcileFolders,
   resolveFolderId } from "./folders";
 import type { FolderStamps } from "./folders";
 // ⭐ WAVE 27 item 22 — the cells the active view's filter forces on a record added under it.
@@ -2105,8 +2105,8 @@ function CustomerGridSurface({
         if (moved)
           signal(
             TOAST_EVENT,
-            `${moved} restored record${moved === 1 ? "" : "s"} came back under a new id — ` +
-              `something had taken the original while it was gone.`
+            `${moved} restored record${moved === 1 ? "" : "s"} came back under a new id. ` +
+              `Something had taken the original while it was gone.`
           );
         signal(ROWS_STALE_EVENT);
       } else if (op.kind === "rowDelete") {
@@ -2244,7 +2244,7 @@ function CustomerGridSurface({
       if (offscreen.length) {
         signal(
           TOAST_EVENT,
-          `Nothing was deleted — ${offscreen.length} of the ${pids.length} selected ` +
+          `Nothing was deleted. ${offscreen.length} of the ${pids.length} selected ` +
             `record${pids.length === 1 ? " is" : "s are"} not shown in this view. Clear the ` +
             `filter (or scroll them into view) and select again.`
         );
@@ -2305,9 +2305,9 @@ function CustomerGridSurface({
           `${risky.length} of these ${one ? "records was" : "records were"} FOUND by an ` +
             `automation. Deleting ${one ? "it" : "them"} is not undone by a re-find` +
             (losses.length
-              ? `: ${losses.join(", ")} — so a card somebody had already moved on comes back ` +
+              ? `: ${losses.join(", ")}, so a card somebody had already moved on comes back ` +
                 `undecided`
-              : ` — ${one ? "it" : "they"} would come back as a new record with no history`) +
+              : `, so ${one ? "it" : "they"} would come back as a new record with no history`) +
             `. Press Delete again (or click again) to confirm.`
         );
         return false;
@@ -2319,7 +2319,7 @@ function CustomerGridSurface({
       for (const r of captured)
         if (await deleteTableRow(scope, r.rid)) gone.push(r);
       if (!gone.length) {
-        signal(TOAST_EVENT, "Nothing was deleted — the server refused.");
+        signal(TOAST_EVENT, "Nothing was deleted: the server refused.");
         return false;
       }
       undoBook.current[scope] = pushUndo(stackFor(undoBook.current, scope), {
@@ -2351,7 +2351,7 @@ function CustomerGridSurface({
         TOAST_EVENT,
         `Deleted ${gone.length} record${gone.length === 1 ? "" : "s"}. Ctrl+Z to undo.` +
           (fedByAutomation
-            ? " If this automation finds one again it comes back as a NEW candidate — first-found" +
+            ? " If this automation finds one again it comes back as a NEW candidate: first-found" +
               " and times-found reset, and its stage back to Review. Undo keeps all of that."
             : "")
       );
@@ -2581,7 +2581,7 @@ function CustomerGridSurface({
         // returns the label by identity when it fits, so this asks the renderer what it did
         // rather than re-running the measurement and hoping the two agree.
         const cut = !!field && !!colDef && colDef.title !== field.label;
-        const text = cut && field ? (note ? `${field.label} — ${note}` : field.label) : note;
+        const text = cut && field ? (note ? `${field.label}: ${note}` : field.label) : note;
         const bounds = args.bounds;
         if (text && bounds) {
           setHeaderTip((prev) =>
@@ -3698,7 +3698,7 @@ function CustomerGridSurface({
       if (serverWindowed) {
         out[id] =
           "No count: this database is read through its source in windows, so the browser holds " +
-          "one page rather than the whole table — a number from it would be the size of that " +
+          "one page rather than the whole table. A number from it would be the size of that " +
           "page, not of this view. Counting it honestly needs a server-side count per view.";
       } else if (pendingMeasures(view.config.filters, measureSets) > 0) {
         out[id] =
@@ -3961,7 +3961,7 @@ function CustomerGridSurface({
         if (!sheet) return refuse("a time series");
         if (sheet.empty) {
           signal(TOAST_EVENT,
-                 `"${view.name}" has no metrics on its sheet yet — add one, then export.`);
+                 `"${view.name}" has no metrics on its sheet yet. Add one, then export.`);
           return;
         }
         if (format === "csv") {
@@ -3987,7 +3987,7 @@ function CustomerGridSurface({
       if (spec?.mode === "catalog") {
         signal(
           TOAST_EVENT,
-          `"${view.name}" is a catalog — open it and use Print to save it as a PDF. ` +
+          `"${view.name}" is a catalog. Open it and use Print to save it as a PDF. ` +
             `A spreadsheet of its products is not what it draws.`
         );
         return;
@@ -5177,7 +5177,7 @@ function CustomerGridSurface({
   const kanbanReason = !kanbanField
     ? null
     : kanbanField.type === "status"
-      ? `Stacked by ${kanbanField.label} — read-only, computed from the source system.`
+      ? `Stacked by ${kanbanField.label}. That field is read-only, computed from the source system.`
       : !canEditField(kanbanField)
         ? "You do not have permission to edit this field, so cards cannot be moved."
         : null;
@@ -5187,7 +5187,7 @@ function CustomerGridSurface({
   const swipeReason = !swipeField
     ? null
     : swipeField.type === "status"
-      ? `Bound to ${swipeField.label} — read-only, computed from the source system.`
+      ? `Bound to ${swipeField.label}. That field is read-only, computed from the source system.`
       : !canEditField(swipeField)
         ? "You do not have permission to edit this field, so records cannot be decided."
         : null;
@@ -5545,6 +5545,16 @@ function CustomerGridSurface({
               } as unknown as HostEvent);
             }}
             onItemMove={(viewId, folderId) => {
+              // ⛔ WAVE 34 · T25 — REFUSE A SYNTHETIC FOLDER ID AT THE ONE PLACE THE WRITE LEAVES.
+              // "Shared with me" and each shared-FOLDER group are READINGS of the view list, not
+              // records: their ids exist in nobody's store. The rail already withholds drop
+              // handlers from those groups, so nothing constructs this call today, and the server
+              // refuses an unknown target anyway (`grid_events.py`'s `item_move` checks the id
+              // against the caller's own folder list). This is the third layer, and it is here
+              // rather than in the rail because this callback is the single choke point every
+              // future surface will reach through: a second caller would otherwise inherit no
+              // client-side check at all. Raised by T25's verifier, which traced exactly that gap.
+              if (isSyntheticFolderId(folderId)) return;
               stampFolder((p) => ({
                 ...p,
                 moved: { ...p.moved, [viewId]: { at: Date.now(), folderId } },
@@ -5982,7 +5992,7 @@ function CustomerGridSurface({
               canEdit={!!activeView && mayEditView(activeView, viewer)}
               readOnlyReason={
                 !activeView
-                  ? "A form lives on a saved view — save this one first."
+                  ? "A form lives on a saved view. Save this one first."
                   : mayEditView(activeView, viewer)
                     ? null
                     : "You have view-only access to this view, so its form cannot be changed."
@@ -6396,6 +6406,45 @@ function CustomerGridSurface({
               ? (w) => changeMeasurePeriod(menuField.key, w)
               : undefined
           }
+          /**
+           * ⭐⭐ WAVE 34 (R13, `W34-T54`) — THE BULK ENRICHMENT RUN.
+           *
+           * ⛔ WIRED AT CLOSE-OUT BY THE INTEGRATOR, and the reason belongs here. Lane F built the
+           * server door, the field kind and the menu row, then offered this prop as optional with
+           * *"nothing breaks if you decline"*. True of the BUILD, false of the FEATURE: this is
+           * the ONLY call site that makes the bulk run reachable, and `W34-T54`'s `done-when`
+           * reads *"the bulk menu offers at least all rows and rows never filled"*. Declining it
+           * would have left that ticket BUILT with its own acceptance test unreachable.
+           * ⭐ OPTIONAL IN THE TYPE IS STILL RIGHT — `ColumnMenu` renders no row when the host
+           * passes nothing, so a host that has not wired it shows nothing rather than a control
+           * that does nothing. What was wrong was leaving the one real host unwired.
+           * ⚠ IT SPENDS MONEY, so the result is REPORTED, never swallowed: the server answers a
+           * run report and the sentence names what actually happened. A run that filled 3 of 900
+           * because a token ceiling bit is the silent cap R6's standing rule forbids.
+           * ⚠ Gated on `isUserTable` for the same reason every schema write here is: the door
+           * itself rides `_field_or_refuse`, so this is the affordance agreeing with the wall
+           * rather than a second opinion about it.
+           */
+          onEnrich={
+            isUserTable && menuField.type === "ai_enrich"
+              ? async (runScope) => {
+                  setColumnMenu(null);
+                  const report = await enrichField(scope, menuField.key, runScope);
+                  if (!report) return;   // apiBridge already said why
+                  const filled = report.filled ?? 0;
+                  const failed = report.failed ?? 0;
+                  const capped =
+                    report.limit !== undefined && (report.tokens ?? 0) >= report.limit;
+                  signal(
+                    TOAST_EVENT,
+                    `${filled} filled` +
+                      (failed ? `, ${failed} failed` : "") +
+                      (capped ? ". The token ceiling was reached, so the rest were left." : ".")
+                  );
+                  signal(ROWS_STALE_EVENT, scope);
+                }
+              : undefined
+          }
           onDelete={
             menuField.custom && menuField.key !== lockedKey
               ? () => {
@@ -6726,7 +6775,7 @@ function CustomerGridSurface({
           </div>
           {addCandidates.length > 50 && (
             <div className="cg-field-hint">
-              Showing the first 50 of {addCandidates.length.toLocaleString()} matches — keep
+              Showing the first 50 of {addCandidates.length.toLocaleString()} matches. Keep
               typing to narrow.
             </div>
           )}

web/src/customer-grid/ViewSidebar.tsx

@@ -47,7 +47,15 @@ import { ROOT_FOLDER_ID } from "./folders";
 // menu vocabulary. The Inbox module's header wears the SAME component (`ui/icons.BellIcon`),
 // so the bell that opens the Inbox and the bell that fills it cannot drift apart.
 import { BellIcon, StarIcon } from "../ui/icons";
-import { SHARED_FOLDER_ID, groupByFolder, reorderFolderIds } from "./folders";
+// ⚠ `SHARED_FOLDER_ID` is no longer imported: W34-T25 replaced both of its call sites with
+// `isSyntheticFolderId`, and `noUnusedLocals` turns a leftover import into a build error rather
+// than into dead weight. The constant itself is still exported and still used by `folders.ts`.
+import {
+  groupByFolder,
+  isSyntheticFolderId,
+  mayFileView,
+  reorderFolderIds,
+} from "./folders";
 
 /* ─────────────────────────────────────────────────────────────────────────────────────────
    ⭐ WAVE 27 · OWNER ITEM 1 — a MARK on each "Who can edit" row.
@@ -506,7 +514,29 @@ export default function ViewSidebar({
      * is not: a surface with folders switched off must still be able to show you somebody
      * else's view under a heading that says whose it is.
      */
-    (v) => v.shared === true
+    (v) => v.shared === true,
+    /**
+     * ⭐⭐ WAVE 34 · T25 (ruling R11) — WHICH shared folder this view arrived through.
+     *
+     * ⚠ READ STRUCTURALLY, and that is a deliberate, temporary compromise rather than sloppiness.
+     * `core/grid_events.py::_granted_views` has stamped `sharedFolder` on every folder-granted
+     * view since `D-37`, its three siblings `shared` / `sharedRole` / `owner` are all declared on
+     * `SavedView`, and this one never was: a census of `web/src` found ZERO occurrences before
+     * this line. `types.ts` is another session's file this wave (`ASK C-1` is out for the
+     * one-line declaration), so rather than block R11 on a type, the field is read through a
+     * narrow local shape and validated here. ⛔ When C-1 lands, delete this cast and take the
+     * declared field: a private spelling of a wire field is exactly how two layers drift.
+     */
+    (v) => {
+      const via = (v as { sharedFolder?: unknown }).sharedFolder;
+      const name = typeof via === "string" ? via.trim() : "";
+      const owner = typeof v.owner === "string" ? v.owner.trim() : "";
+      // ⛔ BOTH, and the owner is not optional. Keyed on the NAME alone, two colleagues who each
+      // share a folder called "Reports" merge into ONE group whose head then attributes every
+      // view in it to whichever of them happens to sort first. `owner` is already stamped on
+      // every projected view by `_granted_views`, so this costs nothing on the wire.
+      return name && owner ? { name, owner } : null;
+    }
   );
   const folderMenuF = folderMenu ? folders?.find((f) => f.id === folderMenu.id) : undefined;
   const addPreview = addTarget && folderAddPreview ? folderAddPreview(addTarget) : null;
@@ -553,6 +583,25 @@ export default function ViewSidebar({
             if (!foldersOn) return;
             e.preventDefault();
             setDropTarget(null);
+            // ⭐⭐ WAVE 34 · T21 (ruling R3) — THE ROW STOPS BEING FADED HERE, AND ONLY HERE.
+            //
+            // Owner: moving a View INTO a folder must not leave the view's icon and row blurred
+            // "until i move it around". `viewDrag` is set in the view row's `onDragStart` and was
+            // cleared in exactly two places: that row's own `onDragEnd`, and the SIBLING-REORDER
+            // drop in `viewDropHandlers`. Filing into a folder is NEITHER — it is this handler,
+            // which cleared `dropTarget` and never touched `viewDrag`.
+            //
+            // ⛔ AND `onDragEnd` CANNOT COVER IT, which is why the fade was permanent rather than
+            // one frame long. `onItemMove` below re-parents the row, so React unmounts the node
+            // that started the drag and the browser never dispatches `dragend` on a node removed
+            // mid-gesture. The state stayed set and the FRESH row rendered wearing
+            // `is-viewdrag` (opacity .45) until some later interaction happened to clear it.
+            //
+            // ⚠ Ordered BEFORE `onItemMove`, and that is free rather than delicate: `onItemMove`
+            // is synchronous and React batches both state writes into the same commit, so there
+            // is no frame in which the row is re-parented and still faded.
+            setViewDrag(null);
+            setViewOver(null);
             const id = e.dataTransfer.getData("text/plain");
             // ⭐⭐ W32-T27 (owner item 20) — DROPPING ON ROOT SENDS A VALUE, NOT `null`.
             //
@@ -574,6 +623,47 @@ export default function ViewSidebar({
   const noteView = noteFor
     ? views.find((view) => view.id === noteFor.viewId)
     : undefined;
+  /**
+   * ⭐⭐ WAVE 34 · T20 (R1, contract C1) — THE SENTENCE THE BARE NUMBER CANNOT CARRY.
+   *
+   * R1 drops the word "Important" from this badge, so what is left on screen is a figure with
+   * no noun. W33-T16's own note argued the opposite ("an unlabelled figure at the top of a list
+   * of views reads as a count OF VIEWS") and it was right about the risk; the owner's ruling
+   * settles the pixels, and this is where the meaning goes instead. Hover and screen reader get
+   * the whole fact, in one string, on the one element.
+   *
+   * ⛔ THE `counted === 0` BRANCH IS D-252, NOT A TIDY-UP. On a fully server-windowed database
+   * every marked view returns no number, so `importantTotal` is `{sum: 0, counted: 0, marked: N}`
+   * — TRUTHY — and the rail painted "Important 0+". Drop the word and that becomes a bare "0+",
+   * which is strictly worse: a real zero and an unknown are the same three pixels. So a total
+   * that could count NOTHING wears the same is-unknown mark a single uncountable view wears
+   * (T14), and never a manufactured 0.
+   *
+   * ⚠ THE CAUSE IS QUOTED, NOT INVENTED. The two reasons a count is missing (a windowed grid, an
+   * unresolved measure) produce different sentences and this rail cannot tell them apart, so it
+   * reads the FIRST marked view's own `countNotes` entry rather than asserting one of them. No
+   * note at all still gets a sentence with a next step, never silence — R6's second half.
+   */
+  let importantNote = "";
+  if (importantTotal) {
+    const { sum, counted, marked } = importantTotal;
+    const nViews = `${marked} view${marked === 1 ? "" : "s"} marked important in this database`;
+    if (counted === 0) {
+      const cause = views
+        .filter((v) => v.config?.important)
+        .map((v) => countNotes?.[v.id])
+        .find(Boolean);
+      importantNote =
+        `No number yet for the ${nViews}. `
+        + (cause || "Open a marked view to see why its own count is missing.");
+    } else if (counted < marked) {
+      importantNote =
+        `${sum.toLocaleString()} records across ${counted} of the ${nViews}. `
+        + `The rest cannot be counted in the browser, so this total is lower than the real one.`;
+    } else {
+      importantNote = `${sum.toLocaleString()} records across the ${nViews}.`;
+    }
+  }
 
   const create = () => {
     const value = name.trim();
@@ -710,35 +800,58 @@ export default function ViewSidebar({
             Owner: the database should carry the SUM of its marked views' numbers, whenever at
             least one view in it is marked.
             ⛔ HERE, and not in the shell's database header, DELIBERATELY: this rail belongs to
-            the OPEN database, so a total in it needs no database name to be unambiguous — and
-            the shell header is another session's file. Named honestly ("Important") rather than
-            floating a bare number, because an unlabelled figure at the top of a list of views
-            reads as a count OF VIEWS.
-            ⚠ `counted < marked` is a PARTIAL total — some marked view could not be counted (a
+            the OPEN database, so a total in it needs no database name to be unambiguous.
+            ⚠ `counted < marked` is a PARTIAL total: some marked view could not be counted (a
             windowed grid, an unresolved measure). It says so instead of presenting a short sum
-            as a whole one, which is D-205's rule one level up. */}
+            as a whole one, which is D-205's rule one level up.
+
+            ⭐⭐ WAVE 34 · T20 (R1) REVERSED THE LABEL DECISION, AND THE REVERSAL IS THE OWNER'S.
+            T16 shipped this as the word "Important" plus a badge, on the argument recorded in
+            its own note: "an unlabelled figure at the top of a list of views reads as a count OF
+            VIEWS". R1 answers that directly, in the owner's words: the count belongs in the
+            database NAVIGATION (B's flyout, contract C1), and what stays here is the number
+            alone, smaller, with no word. The risk T16 named is real and is answered by
+            `importantNote` rather than by a label: the badge carries the whole sentence in its
+            `title` AND its `aria-label`, so hover and screen reader both get the noun the pixels
+            gave up. ⛔ Do not re-add the word to satisfy the old note; `verify_grid_ux`'s
+            `[VIEWS RAIL]` scan reds on it, with a control that reproduces the regression. */}
         {importantTotal && (
           <span
             className={
               "cg-views-important" +
-              (importantTotal.counted < importantTotal.marked ? " is-partial" : "")
-            }
-            title={
-              importantTotal.counted < importantTotal.marked
-                ? `${importantTotal.sum.toLocaleString()} records across `
-                  + `${importantTotal.counted} of the ${importantTotal.marked} views marked `
-                  + `important here — the rest cannot be counted in the browser, so this total `
-                  + `is lower than the real one`
-                : `${importantTotal.sum.toLocaleString()} records across the `
-                  + `${importantTotal.marked} view${importantTotal.marked === 1 ? "" : "s"} `
-                  + `marked important in this database`
+              // ⚠ PARTIAL means "the number you can see is real and short". A total that counted
+              // NOTHING has no number to be short, so it must not wear the dashed-purple partial
+              // mark as well as the is-unknown one — two statements about one absence.
+              (importantTotal.counted > 0 && importantTotal.counted < importantTotal.marked
+                ? " is-partial"
+                : "")
             }
           >
-            Important
-            <span className="cg-view-count">
-              {importantTotal.sum.toLocaleString()}
-              {importantTotal.counted < importantTotal.marked ? "+" : ""}
-            </span>
+            {/* ⚠ `role="img"` ON BOTH, and it is not decoration. An `aria-label` on a plain
+                roleless inline `<span>` is not reliably exposed by assistive technology, and
+                this badge is now the ONLY carrier of a noun the pixels no longer say. `img` is
+                the correct role for "a graphic whose whole meaning is its label", and it also
+                stops a screen reader announcing the bare digits as loose text. */}
+            {importantTotal.counted === 0 ? (
+              <span
+                className="cg-view-count is-unknown"
+                role="img"
+                title={importantNote}
+                aria-label={importantNote}
+              >
+                -
+              </span>
+            ) : (
+              <span
+                className="cg-view-count"
+                role="img"
+                title={importantNote}
+                aria-label={importantNote}
+              >
+                {importantTotal.sum.toLocaleString()}
+                {importantTotal.counted < importantTotal.marked ? "+" : ""}
+              </span>
+            )}
           </span>
         )}
       </div>
@@ -985,7 +1098,7 @@ export default function ViewSidebar({
                       // host-side, so say that rather than letting the user think they
                       // shared it.
                       <span className="cg-perm-empty">
-                        No other accounts to pick — this will save as Personal.
+                        No other accounts to pick. This will save as Personal.
                       </span>
                     ) : (
                       userOptions.map((u) => (
@@ -1079,7 +1192,11 @@ export default function ViewSidebar({
          * server would store. The row menu was already suppressed for this id in wave 20;
          * the DRAG surfaces were not, because nothing ever constructed the group.
          */
-        const isSynthetic = gid === SHARED_FOLDER_ID;
+        // ⭐ W34-T25 (R11): `isSyntheticFolderId`, NOT `=== SHARED_FOLDER_ID`. There is more than
+        // one synthesised group now (one per shared FOLDER), and a rail that suppressed writes on
+        // "Shared with me" while offering them on a colleague's folder would emit `item_move` /
+        // `folder_rename` / `folder_delete` against an id that exists in nobody's store.
+        const isSynthetic = isSyntheticFolderId(gid);
         const shut = gid != null && collapsed.has(gid);
         return (
         <div
@@ -1101,7 +1218,27 @@ export default function ViewSidebar({
             //
             // The `is-drop-above` line above got this right (`&& foldDrag &&`), which is the
             // tell: two conditions written minutes apart, one guarded and one not.
-            (foldDrag !== null && foldDrag === gid ? " is-folddrag" : "")
+            (foldDrag !== null && foldDrag === gid ? " is-folddrag" : "") +
+            // ⭐⭐ WAVE 34 · T22 (ruling R4) — THE ROOT SECTION IS A DROP TARGET WITH NO PIXELS.
+            //
+            // ⛔ THIS IS THE HALF `D-249` DOES NOT NAME, and on its own it reproduces the owner's
+            // whole report. `groupByFolder` ALWAYS pushes the root group, so a user who has filed
+            // every view into folders gets `<div class="cg-fold-root">` with no head, no rows and
+            // no min-height: a ZERO-PIXEL drop zone. The drag starts fine (that is B1's fix) and
+            // there is physically nowhere to release it. Even a POPULATED root is barely better —
+            // this element has no padding, so its box is exactly the union of its rows, and each
+            // row's own `onDragOver` calls `stopPropagation` to claim the reorder gesture. The
+            // only surface that ever meant "file at the top level" was the sliver between rows.
+            //
+            // So while a VIEW drag is in flight the root section is given real height and a real
+            // strip below its last row (index.css `.cg-fold-root.is-viewdrop`). The hover paint is
+            // the existing `.is-drop` rule: this ticket supplies the AREA, not a second vocabulary.
+            //
+            // ⚠ `viewDrag !== null` explicitly, never a bare truthiness test on a value that idles
+            // at `null` beside a `gid` that is `null` for this very section — that is the
+            // `foldDrag === gid` trap two lines up, which faded the whole ungrouped section
+            // permanently once already. `isRoot` is a separate boolean, so the two cannot collide.
+            (isRoot && viewDrag !== null ? " is-viewdrop" : "")
           }
           {/* No drop handlers on the synthetic group — see `isSynthetic`. Spreading `{}`
               rather than branching the element keeps ONE render path for every group. */
@@ -1173,7 +1310,23 @@ export default function ViewSidebar({
                     }}
                   />
                 ) : (
-                  <span className="cg-fold-name">{group.folder.name}</span>
+                  <span
+                    className="cg-fold-name"
+                    /* ⭐ W34-T25 (R11) — WHOSE folder this is, on the folder itself.
+                       A synthesised shared-folder group looks exactly like one of the reader's
+                       own folders otherwise, and two people can share folders with the SAME
+                       NAME. The owner rides on every projected view (`_granted_views` stamps
+                       `owner`), so the group can answer it without a second wire field. Left as
+                       a `title` rather than painted into the name: the rail's indent is measured
+                       to the pixel and a second line here would push every view row. */
+                    title={
+                      isSynthetic && group.items[0]?.owner
+                        ? `Shared with you by ${group.items[0].owner}`
+                        : undefined
+                    }
+                  >
+                    {group.folder.name}
+                  </span>
                 )}
                 {/* ⛔ WAVE 20 item 21 — THE VIEW COUNT IS DELETED, and the item is not
                     really about the number. `.cg-view-more` (the "…" beside this button)
@@ -1196,7 +1349,11 @@ export default function ViewSidebar({
                   row the server would refuse is three fake affordances rather than
                   one. Views MOVE OUT of it normally (that is per-receiver placement),
                   which is the only thing anyone needs to do to it. */}
-              {group.folder.id === SHARED_FOLDER_ID ? null : (
+              {/* ⭐ W34-T25 (R11) — widened from `=== SHARED_FOLDER_ID` to EVERY synthesised
+                  group, for the reason the block above gives: a colleague's shared folder is no
+                  more the reader's to rename, duplicate or delete than "Shared with me" is, and
+                  every row of that menu would be refused by a server that has no such folder. */}
+              {isSynthetic ? null : (
               <button
                 type="button"
                 className="cg-view-more"
@@ -1242,8 +1399,13 @@ export default function ViewSidebar({
                   : "")
               }
               key={view.id}
+              // ⭐⭐ WAVE 34 · T22 (ruling R4, `D-249`) — `mayFileView`, NOT `mayEditView`.
+              // A read-only shared view could not BEGIN a drag, so it could never be filed OR
+              // taken back out. The full argument, and the two places the SERVER already
+              // disagreed with this line, are on `mayFileView` in `folders.ts` — which is where
+              // the predicate lives so `verify_folders.py` can run its truth table.
               draggable={(foldersOn || viewsReorderable) && !renaming
-                         && mayEditView(view, viewer)}
+                         && mayFileView(view, mayEditView(view, viewer))}
               onDragStart={(e) => {
                 // ⛔ TWO TYPES ON ONE DRAG, and that is the discrimination C7 asks for.
                 // `text/plain` is the FILE-INTO-A-FOLDER channel the folder groups already
@@ -1289,7 +1451,7 @@ export default function ViewSidebar({
                   // ellipsis at 188px, so the hover is now the only way to read either one in
                   // full. It used to show the note INSTEAD of the name, which meant a
                   // described view could not have its own truncated name revealed at all.
-                  title={view.note ? `${view.name} — ${view.note}` : view.name}
+                  title={view.note ? `${view.name}: ${view.note}` : view.name}
                 >
                   {/* I12 — the row wears the view's CURRENT display mode, not a kind dot.
                       Same geometry the mode switcher and the create flyout use, so "what
@@ -1339,10 +1501,10 @@ export default function ViewSidebar({
                       // number is the same fact; the promise attached to it is not.
                       title={
                         view.config?.important
-                          ? `${alertCounts[view.id].toLocaleString()} records match this view `
-                            + `— you marked it important`
+                          ? `${alertCounts[view.id].toLocaleString()} records match this view. `
+                            + `You marked it important.`
                           : `${alertCounts[view.id].toLocaleString()} records match this `
-                            + `view — you are alerted when a new one arrives`
+                            + `view. You are alerted when a new one arrives.`
                       }
                     >
                       {alertCounts[view.id].toLocaleString()}
@@ -1365,7 +1527,15 @@ export default function ViewSidebar({
                       title={countNotes[view.id]}
                       aria-label={countNotes[view.id]}
                     >
-                      –
+                      {/* ⚠ W34-T26 (R6): an ASCII hyphen, not the EN DASH this shipped with.
+                          The en dash is exactly the character the standing rule bans from copy
+                          that reaches a screen, and `web_prose` CANNOT SEE IT: its JSX pass
+                          requires the text run to contain no newline, and this span has enough
+                          attributes that Prettier puts the closing `>` on its own line. Reported
+                          to A in mailbox C-3 as a structural hole rather than worked around
+                          silently. ⭐ It is also what makes T20's header badge and this one ONE
+                          mark rather than two that merely claim to match. */}
+                      -
                     </span>
                   )}
                   {/* ⭐ wave17 R1 / C-LOCKV — ONE mark, TWO meanings, and they are genuinely
@@ -1406,7 +1576,7 @@ export default function ViewSidebar({
                       title={
                         (view.owner
                           ? `Shared with you by ${view.owner}.`
-                          : "Shared with you — someone gave you access to this view.") +
+                          : "Shared with you. Someone gave you access to this view.") +
                         (view.sharedRole === "edit"
                           ? " You can edit it."
                           : " You can view it, not change it.")
@@ -1437,12 +1607,12 @@ export default function ViewSidebar({
                       }
                       title={
                         view.kind === "locked"
-                          ? "Locked — this view shows only the records locked into it. " +
+                          ? "Locked: this view shows only the records locked into it. " +
                             "Filters, sorts and columns still narrow within them." +
                             (isModeFrozen(view)
                               ? ` It also stays a ${MODE_LABELS[mode].toLowerCase()}.`
                               : "")
-                          : `Locked — this view stays a ${MODE_LABELS[
+                          : `Locked: this view stays a ${MODE_LABELS[
                               mode
                             ].toLowerCase()}. Filters, sorts and columns are still editable.`
                       }
@@ -1492,7 +1662,7 @@ export default function ViewSidebar({
           );
         })}
         {group.folder && !shut && group.items.length === 0 && (
-          <div className="cg-fold-empty">Empty — drag a view here.</div>
+          <div className="cg-fold-empty">Empty. Drag a view here.</div>
         )}
         </div>
         );
@@ -1661,7 +1831,7 @@ export default function ViewSidebar({
                   setLockFor(null);
                 }}
               >
-                Unlock — show the whole table again
+                Unlock and show the whole table again
               </button>
             )}
           </AnchoredOverlay>
@@ -1692,7 +1862,7 @@ export default function ViewSidebar({
               Not included:
               {addPreview.skipped.map((sk) => (
                 <span key={sk.name} className="cg-fold-skip">
-                  {sk.name} — {sk.why}
+                  {sk.name}: {sk.why}
                 </span>
               ))}
             </div>
@@ -1826,10 +1996,17 @@ export default function ViewSidebar({
               </div>
             </>
           )}
-          {/* I17 (C4) — the view's IDENTITY (name, description, folder, deletion) is what
-              the view permission governs. Duplicate is deliberately NOT gated: making your
-              own copy changes nothing about this view, and it is how someone without edit
-              rights gets a version they can work in. */}
+          {/* I17 (C4) — the view's IDENTITY (name, description, deletion) is what the view
+              permission governs. Duplicate is deliberately NOT gated: making your own copy
+              changes nothing about this view, and it is how someone without edit rights gets a
+              version they can work in.
+              ⛔ W34-T22 REMOVED "folder" FROM THAT LIST, and the removal is the point rather
+              than a tidy-up. Filing a view writes a PLACEMENT into the reader's own workspace
+              stratum and never touches the owner's object, so it is navigation rather than an
+              identity edit; the drag site asks `mayFileView` now (`folders.ts`) while every row
+              below still asks `mayEditView`. Left as a correction rather than deleted, because
+              a sentence three hundred lines from the code it describes is exactly the shape that
+              went stale unnoticed here. */}
           {canEditMenuView && (
             <button
               type="button"
@@ -2177,7 +2354,20 @@ export default function ViewSidebar({
             {/* Wave-10 item 9 moved the description off the grid and onto the view's row,
                 so this sentence had to move with it — it described a banner that no longer
                 exists. */}
-            <span>Shown under this view's name in the list.</span>
+            {/* ⚠ W34-T26 — "the view name", not "this view's name", and the apostrophe is the
+                whole reason. `web_prose`'s TypeScript walk has no parser: an apostrophe in JSX
+                TEXT opens a single-quoted string it never closes, so the walk ran from here to
+                the end of this region, swallowing ~37 lines (this span's tail, the <textarea>
+                and its attributes, two <button>s and a `//` comment). It then reported the em
+                dash inside that swallowed COMMENT as a finding on this line: mislocated, and a
+                false positive by the gate's own contract, since comments are exempt.
+                ⛔ THE POINT OF THIS EDIT IS NOT THE GREEN. A walker that believes it is inside a
+                string also SKIPS every real string after it, so those 37 lines were unscanned;
+                removing the apostrophe restores the gate's sight over them. The underlying defect
+                is `verify_prose.py`'s and is reported to A (post C-3; lane B raised the same
+                thing as B-3, measuring 248 lines lost in one file). Do NOT rewrite the COMMENTS
+                it reports to silence it, which is the version of this that destroys reasoning. */}
+            <span>Shown under the view name in the list.</span>
             <textarea
               data-overlay-autofocus
               value={noteDraft}

web/src/customer-grid/apiBridge.ts

@@ -1401,3 +1401,60 @@ function standaloneSink(event: HostEvent): boolean {
 export function installStandaloneBridge(): void {
   setStandaloneSink(standaloneSink);
 }
+
+/**
+ * ⭐⭐ WAVE 34 (owner ruling R13, `W34-T54`) — RUN AN `ai_enrich` COLUMN OVER A SCOPE.
+ *
+ * `POST /api/v1/tables/{key}/fields/{fkey}/enrich`, body `{scope: "blank" | "always"}`.
+ * `blank` fills only cells nothing has written; `always` re-runs every row.
+ *
+ * ⛔ ADDED BY THE INTEGRATOR AT CLOSE-OUT, and the reason is worth stating rather than burying.
+ * Lane F built the server door, the menu row and the field kind, and left the host call site as an
+ * OPTIONAL prop with the note *"nothing breaks if you decline"*. That is true of the BUILD and
+ * false of the FEATURE: this is the only path that makes the bulk run reachable, and `W34-T54`'s
+ * own `done-when` reads *"the bulk menu offers at least all rows and rows never filled"*. Left
+ * unwired, that ticket would have been BUILT with its acceptance test unreachable — the exact
+ * shape this repo has shipped five times ([[mounted-is-not-callable]]).
+ *
+ * ⚠ IT SPENDS MONEY, so it reports rather than returns a boolean. The server answers a RUN REPORT
+ * (`filled`, `failed`, `skipped` by reason, `tokens`, `limit`) and the caller shows the sentence:
+ * a bulk enrichment that quietly did 3 of 900 rows because a ceiling bit is precisely the silent
+ * cap R6's standing rule forbids, and a `true` would hide it.
+ */
+export async function enrichField(
+  tableKey: string,
+  fieldKey: string,
+  scope: "blank" | "always"
+): Promise<EnrichReport | null> {
+  try {
+    const res = await fetch(
+      `${API_V1}/tables/${encodeURIComponent(tableKey)}/fields/${encodeURIComponent(fieldKey)}/enrich`,
+      {
+        method: "POST",
+        credentials: CREDENTIALS,
+        headers: JSON_HEADERS,
+        body: JSON.stringify({ scope }),
+      }
+    );
+    if (handledSession(res)) return null;
+    const body = (await readJson(res)) as (EnrichReport & { error?: { message?: string } }) | null;
+    if (!res.ok) {
+      // The server states WHY (no key, a token ceiling, a locked column). Its sentence beats ours.
+      signal(TOAST_EVENT, refusalMessage(body, res.status));
+      return null;
+    }
+    return body ?? null;
+  } catch {
+    signal(DATA_ERROR_EVENT, "The enrichment run could not be reached. Nothing was changed.");
+    return null;
+  }
+}
+
+/** What `POST .../enrich` answers. Shapes the sentence the caller shows. */
+export type EnrichReport = {
+  filled?: number;
+  failed?: number;
+  skipped?: Record<string, number>;
+  tokens?: number;
+  limit?: number;
+};

web/src/customer-grid/cells.ts

@@ -610,6 +610,43 @@ function baseCell(
         allowOverlay: false,
       };
     }
+    case "ai_enrich": {
+      // ⭐⭐ Wave-34 (owner ruling R13) — the AI ENRICHMENT cell. The value is an ordinary stored
+      // string, so this is a Text cell; what it is NOT is a `formula` (recomputed in the browser)
+      // or a `rollup` (read through from another table). Nobody has to be told a number came from
+      // somewhere else here, because the answer is words.
+      //
+      // Written the same way `code` and `json` are, and for their reason rather than a new one:
+      //   · `allowOverlay: false` — glide's ONE-LINE overlay editor over multi-line prose is an
+      //     editor that can only damage the value. The place a person edits an answer is the
+      //     record drawer, which shows the whole thing.
+      //   · `readonly` deliberately NOT set, so the paste path that legitimately writes a whole
+      //     answer still works.
+      //   · `copyData` the RAW text, never the preview, or copying this column would yield
+      //     "Ann is a florist  +2 more", which is not data and cannot be pasted back. That is the
+      //     lesson the image cell booked in wave 19 and the date cell repeated in wave 26.
+      //
+      // ⛔ EDITING IS THE POINT, NOT AN AFTERTHOUGHT, which is why the column is NOT in
+      // `READONLY_CELL_TYPES` and is NOT in `is_computed_cell` server-side: typing over a cell is
+      // what marks it the human's, and `core.user_tables.ai_enrich_human_authored` then protects
+      // it from every automatic run forever.
+      //
+      // ⚠ OWED, AND NAMED RATHER THAN FAKED: this branch cannot paint the agent-written /
+      // human-edited / stale / errored STATE, because `makeCell(field, v, editable, avatars)` is
+      // handed the value and never the row, and the per-cell mark lives in a stratum the row
+      // payload does not carry. The drawer shows the state; the canvas will once the call site in
+      // `CustomerGrid.tsx` (lane C's file) passes it. Rendering a guessed state here would be
+      // worse than none: "done" on a cell nothing has run for is a claim.
+      const raw = String(v ?? "");
+      const text = codePreview(raw);
+      return {
+        kind: GridCellKind.Text,
+        data: text,
+        displayData: text,
+        copyData: raw,
+        allowOverlay: false,
+      };
+    }
     case "rating": {
       const max = ratingMax(field);
       const n = Math.max(0, Math.min(max, Math.round(num(v))));

web/src/customer-grid/display.ts

@@ -675,6 +675,16 @@ export function formatDisplay(field: Field, v: CellValue): string {
       // for `json`'s exact reason: a snippet is multi-LINE, and falling through to `default`
       // would put raw newlines into a CSV cell, a kanban card and a calendar chip.
       return codePreview(v);
+    case "ai_enrich":
+      // ⭐⭐ Wave-34 (owner ruling R13) — an enrichment answer is model-authored PROSE and can run
+      // to several lines, so it is explicit here for exactly the reason `json` and `code` are:
+      // this function feeds ListView, KanbanView, the calendar, the record panel and all four
+      // EXPORT formats, and `default` would put raw newlines into a CSV cell.
+      // ⚠ `codePreview` is REUSED rather than given a prose-flavoured twin. Its "first line
+      // +N more" is already this product's one way of saying "a multi-line value in a one-line
+      // slot", and the count is checkable against what the drawer shows; a second helper would
+      // be a second answer to one question ([[one-question-two-normalizers]]).
+      return codePreview(v);
     case "automation":
       // The machine-written line, verbatim. Explicit rather than left to the `default` branch
       // below: `formula` fell through a default once and printed every text result as `0` for

web/src/customer-grid/folders.ts

@@ -239,6 +239,62 @@ export interface FolderGroup<T> {
 export const SHARED_FOLDER_ID = "__shared__";
 export const SHARED_FOLDER_NAME = "Shared with me";
 
+/**
+ * ⭐⭐ WAVE 34 · T25 (ruling R11) — A SHARED **FOLDER** GETS ITS OWN GROUP, under this prefix.
+ *
+ * R11: *"A folder (with the Views inside it) can be shared with a team member."* Everything below
+ * the client already worked and was VERIFIED before this was written: `core/shares.py::KINDS` has
+ * carried `'folder'` since wave 20, the rail already offers "Share folder", and
+ * `grid_events.py::_granted_views` has projected each granted folder's views since `D-37`. What
+ * did not work is the last inch: every shared view landed in ONE flat "Shared with me" group, so
+ * the receiver got loose views and **the folder itself was invisible**.
+ *
+ * ⭐ The name has been on the wire the whole time. `_granted_views` stamps
+ * `v['sharedFolder'] = <folder name>` with the comment *"so the client can group these together
+ * later"*, and a census found ZERO readers of it anywhere in `web/src` — a flag shipped without
+ * its reader. This is the reader.
+ *
+ * ⚠ A PREFIX RATHER THAN ONE RESERVED ID, because there can be several: two colleagues can each
+ * share a folder with you. {@link isSyntheticFolderId} is what every affordance must ask instead
+ * of comparing against `SHARED_FOLDER_ID` — a rail that suppressed actions on one synthetic group
+ * and offered them on another would emit `item_move`/`folder_rename` against a folder id that
+ * exists in nobody's store.
+ *
+ * ⛔⛔ THE KEY IS **OWNER + NAME**, NOT NAME, AND THE FIRST DRAFT OF THIS FUNCTION GOT IT WRONG.
+ * It keyed on the folder name alone while the comment right here claimed to handle two colleagues
+ * sharing folders with the SAME NAME — so those two folders merged into ONE group, and the head's
+ * `title` (which reads the first item's `owner`) misattributed every view from the second sharer.
+ * Per-view `sharedRole` was never affected, so nothing leaked; what broke was the rail telling you
+ * whose work you were reading, which is the entire point of the group. **A comment that describes
+ * the case the code does not handle is worse than no comment**, because it is what a reviewer
+ * checks against. Found by this ticket's own verifier reading the two side by side.
+ *
+ * ⛔ NOTHING MAY EVER WRITE ONE. Like `SHARED_FOLDER_ID` these ids are a READING of the view list,
+ * not a record: no `order`, no icon, no row in `folders`.
+ */
+export const SHARED_FOLDER_PREFIX = "__sharedfld__:";
+
+/**
+ * The synthetic group id for a folder somebody shared with you.
+ *
+ * ⚠ `owner` FIRST and separated by a character usernames cannot contain. `core/users.py` keeps
+ * usernames lower-case and non-empty; a folder NAME is free text and can contain anything a user
+ * types, `:` included. Putting the free-text half last means no pair of (owner, name) can spell
+ * another pair's id, whatever somebody calls a folder.
+ */
+export function sharedFolderGroupId(owner: string, name: string): string {
+  return `${SHARED_FOLDER_PREFIX}${owner}:${name}`;
+}
+
+/**
+ * Is this group id SYNTHESISED rather than stored? True for "Shared with me" and for every
+ * shared-folder group. Every drag, drop, rename and delete affordance in the rail asks this.
+ */
+export function isSyntheticFolderId(id: string | null | undefined): boolean {
+  return id === SHARED_FOLDER_ID
+    || (typeof id === "string" && id.startsWith(SHARED_FOLDER_PREFIX));
+}
+
 /**
  * ⭐⭐ WAVE 32 · T27 (owner item 20) — **"FILED AT ROOT", AS A VALUE.**
  *
@@ -293,11 +349,26 @@ export function groupByFolder<T>(
   items: T[],
   folders: GridFolder[],
   folderIdOf: (item: T) => string | null,
-  isShared?: (item: T) => boolean
+  isShared?: (item: T) => boolean,
+  /**
+   * ⭐ WAVE 34 · T25 (R11) — the folder a shared item arrived through, if it did.
+   *
+   * Returns the folder's NAME and its OWNER, because the pair is the identity: the wire carries
+   * no folder id for a grant (`_granted_views` stamps a name and an owner, never an id), and the
+   * name alone is not unique across sharers.
+   *
+   * Optional, so every existing caller (the cohort rail, the tests) keeps the pre-T25 shape
+   * byte-for-byte: with it omitted, every shared item falls into the flat "Shared with me"
+   * group exactly as before. Supplied, the shared views SPLIT by the folder that carried them,
+   * and the folder finally appears on the receiver's screen.
+   */
+  sharedFolderOf?: (item: T) => { name: string; owner: string } | null
 ): FolderGroup<T>[] {
   const buckets = new Map<string, T[]>(folders.map((f) => [f.id, []]));
   const root: T[] = [];
   const shared: T[] = [];
+  /** synthetic group id -> {name, views}. Keyed by OWNER+NAME; see `SHARED_FOLDER_PREFIX`. */
+  const sharedFolders = new Map<string, { name: string; items: T[] }>();
   for (const item of items) {
     const id = folderIdOf(item);
     const bucket = id == null ? undefined : buckets.get(id);
@@ -308,13 +379,38 @@ export function groupByFolder<T>(
     // value, `isShared` won, and a shared view dragged to root returned to "Shared with me" on
     // the next render — the owner's item 20, in one branch.
     else if (id === ROOT_FOLDER_ID) root.push(item);
-    else if (isShared?.(item)) shared.push(item);
+    else if (isShared?.(item)) {
+      // ⭐ W34-T25 (R11): a shared view that arrived through a FOLDER goes to that folder's own
+      // group; one that was granted directly still goes to the flat "Shared with me". The two
+      // are different facts and the receiver can see which is which.
+      const via = sharedFolderOf?.(item);
+      const name = via ? String(via.name || "").trim() : "";
+      const owner = via ? String(via.owner || "").trim() : "";
+      // ⚠ BOTH halves required. A folder name with no owner cannot be told apart from another
+      // sharer's folder of the same name, so it falls back to the flat group rather than
+      // inventing a group that might merge two people's work under one person's label.
+      if (name && owner) {
+        const key = sharedFolderGroupId(owner, name);
+        const bucket2 = sharedFolders.get(key);
+        if (bucket2) bucket2.items.push(item);
+        else sharedFolders.set(key, { name, items: [item] });
+      } else shared.push(item);
+    }
     else root.push(item);
   }
   const out: FolderGroup<T>[] = folders.map((f) => ({ folder: f, items: buckets.get(f.id) ?? [] }));
   out.push({ folder: null, items: root });
   if (shared.length)
     out.push({ folder: { id: SHARED_FOLDER_ID, name: SHARED_FOLDER_NAME }, items: shared });
+  // ⚠ SORTED, not first-seen. A Map preserves insertion order, which here is the order the VIEWS
+  // happen to arrive in — so one view moving could reorder whole folders in the rail for no reason
+  // a reader could name. Sorting on the composite ID (owner first) is stable across every payload
+  // AND groups one colleague's folders together, which reads better than interleaving two people's
+  // folders alphabetically by name.
+  for (const key of [...sharedFolders.keys()].sort((a, b) => a.localeCompare(b))) {
+    const grp = sharedFolders.get(key)!;
+    out.push({ folder: { id: key, name: grp.name }, items: grp.items });
+  }
   return out;
 }
 
@@ -356,6 +452,36 @@ export function reorderFolderIds(
   return next;
 }
 
+/**
+ * ⭐⭐ WAVE 34 · T22 (ruling R4, `D-249`) — MAY THIS VIEWER FILE THIS VIEW INTO A FOLDER?
+ *
+ * ⛔ NOT THE SAME QUESTION AS `mayEditView`, AND CONFLATING THEM IS THE DEFECT. The rail gated its
+ * `draggable` on `mayEditView`, which fail-closes on a shared view whose role is not `edit` — so a
+ * read-only shared view could not BEGIN a drag, and the owner's report is that a view cannot be
+ * taken out of a folder. Filing is not a content edit: it writes a PLACEMENT into the receiver's
+ * own workspace stratum and never touches the owner's object.
+ *
+ * ⭐ THE SERVER ALREADY AGREED, IN TWO PLACES, BEFORE THIS FUNCTION EXISTED. `grid_events.py::
+ * table_workspace` merges granted views into `ws['views']`, which is the very set `item_move`'s
+ * own-ids test reads — so the write this drag produces is ACCEPTED today. And the `view_reorder`
+ * branch beside it carries the rule in prose: *"NO OWNERSHIP FILTER … refusing ids they do not own
+ * would make exactly those un-draggable, which is the half of sharing people notice."* The client
+ * was the only refuser, and it was refusing a write the server was ready to take.
+ *
+ * ⚠ `mayEdit` IS A PARAMETER, NOT AN IMPORT, and that is deliberate: this module is
+ * "pure and React-free so verify_folders.py can run it under node" (see the header), and its only
+ * imports today are one constant and one type. Taking the verdict rather than the resolver keeps
+ * the truth table testable in isolation and keeps this file's dependency surface where its own
+ * header promised it would stay.
+ *
+ * ⚠ USE IT ONLY AT THE DRAG SITE. Every other affordance the rail gates on `mayEditView` — rename,
+ * description, delete, permissions — really is a content edit on somebody else's object, and the
+ * server really does refuse those.
+ */
+export function mayFileView(view: { shared?: boolean }, mayEdit: boolean): boolean {
+  return view.shared === true || mayEdit;
+}
+
 /** A fresh folder id. Client-generated, like every other id in this component. */
 export function newFolderId(): string {
   const rand =

web/src/customer-grid/iconShapes.ts

@@ -159,6 +159,18 @@ export const TYPE_SHAPES: Record<FieldType, IconShape[]> = {
     { d: "M4.8 8h6.4" },
     { d: "M6.6 11.6h2.8" },
   ],
+  // ⭐ WAVE 34 · T53 (R13), drawn by C on F's ask (`F-2`) — AI ENRICHMENT.
+  // The SPARKLE, because it is the product's own AI mark already: `Shell.tsx::SparkIcon` wears it
+  // on the Assistant rail row, so a column the AI fills reads as the same family rather than as a
+  // second vocabulary for one idea. Deliberately NOT the `automation` cycle-ring two entries up
+  // (that means "a job that runs, repeatedly", and an enrichment can be manual) and not a robot
+  // head (`Shell.tsx::RobotIcon` claims that for the Agents MODULE; a field is not a module).
+  // ⚠ TWO stars, not one: a lone four-point star at 16px with a 1.35 stroke reads as a plus sign.
+  // The small companion is what makes the mark say "sparkle".
+  ai_enrich: [
+    { d: "M6.6 2.6l1.3 3.1 3.1 1.3-3.1 1.3-1.3 3.1-1.3-3.1L2.2 7l3.1-1.3z" },
+    { d: "M11.9 9.8l.7 1.6 1.6.7-1.6.7-.7 1.6-.7-1.6-1.6-.7 1.6-.7z" },
+  ],
 };
 
 /**
@@ -617,6 +629,10 @@ export const TYPE_LABELS: Record<FieldType, string> = {
   // is called everywhere else in this wave (the ruling, the language picker, the viewer header),
   // and it says what the column holds without implying the product will run it.
   code: "Code",
+  // ⭐ WAVE 34 · T53 (R13), on F's ask (`F-2`) — the owner's own noun for the kind: "a field kind
+  // called AI enrichment". Not "AI field" (every field in an AI-built view would qualify) and not
+  // "Generate" (that names the verb, and the column's value is the point, not the act).
+  ai_enrich: "AI enrichment",
   status: "Lifecycle status (Odoo)", // never creatable; present so the map stays total
 };
 

web/src/customer-grid/types.ts

@@ -76,7 +76,31 @@ export type FieldType =
   // a per-column `language` that selects a HIGHLIGHTER and nothing else. R13: "syntax-highlighted
   // storage + language config, NO execution engine" — no value of `language` may ever reach a
   // run path, and there is none to reach.
-  | "code";
+  | "code"
+  // ⭐⭐ WAVE-34 (owner ruling R13) — AI ENRICHMENT: a prompt per row that populates text. The
+  // cell is an ordinary stored STRING, which is what separates it from `formula` (recomputed in
+  // the browser on every paint) and `rollup` (read through from another table). A person may type
+  // over it, and doing so permanently protects that cell from every automatic run, so it is
+  // deliberately NOT in `READONLY_CELL_TYPES`. Its config lives in `Field.aiEnrich`.
+  | "ai_enrich";
+
+/**
+ * ⭐⭐ WAVE-34 (owner ruling R13) — WHOSE VALUE IS IN THIS ENRICHMENT CELL.
+ *
+ * A row carries `_ai_<colId>` for every `ai_enrich` column that has a state to report, stamped by
+ * `routes_tables._stamp_ai_states` beside the `_created` / `lat` / `lon` keys the row already
+ * carries. An ABSENT key means nothing has run for that cell.
+ *
+ * ⚠ Declared HERE, once, because two client surfaces read it (the record drawer today, the grid
+ * cell when its call site can pass a row) and a prefix spelled twice is a prefix that will be
+ * spelled differently once. The server holds the matching constant in `routes_tables.py`.
+ * ⛔ Collision-proof by construction: `_clean_field` strips leading underscores off every field
+ * key, so no column can ever be named `_ai_*`.
+ */
+export const AI_STATE_PREFIX = "_ai_";
+
+/** What `_ai_<colId>` can say. `empty` is never stamped: an absent key IS empty. */
+export type AiCellState = "agent" | "human" | "stale" | "error";
 
 export type FieldSource = "odoo" | "overlay";
 
@@ -163,6 +187,18 @@ export const CREATABLE_TYPES: readonly FieldType[] = [
   // declared language stores and renders as plain text, which is a legitimate state. So
   // `ColumnMenu.canCreate` does not gate on it, and the language picker is an ordinary edit.
   "code",
+  // ⭐⭐ WAVE-34 (owner ruling R13) — AI enrichment, landing in the SAME change as `FieldType`,
+  // `UT_FIELD_TYPES`, `CUSTOM_FIELD_TYPES`, the shape/label tables and the cell renderer, for the
+  // reason the three comments above already give in their own words. ⚠ THE WAVE PLANNED IT AS TWO
+  // TICKETS (server in `W34-T51`, client in `W34-T53`) AND THAT SPLIT IS NOT BUILDABLE: three
+  // parity gates chain over these sets and none permits a partial landing. `api_api` went
+  // 969/969 to 968/969 on the server half alone, measured by another lane on the shared tree.
+  //
+  // ⛔ LIKE `link`/`rollup` AND UNLIKE `code`, IT REQUIRES ITS CONFIG BAG: `_clean_field` returns
+  // None for an `ai_enrich` column with no `aiEnrich` bag, because a prompt is the only thing
+  // that can ever produce a value here. So `ColumnMenu.canCreate` gates on it, or the create
+  // button is the "created, named, configured, gone" failure arriving one door earlier.
+  "ai_enrich",
 ];
 
 /**
@@ -1798,6 +1834,32 @@ export interface Field {
    *     `isMachineOwned` — a person types here, so it must NOT take the machine wash.
    */
   profile?: { source?: string };
+  /**
+   * ⭐⭐ WAVE-34 (owner ruling R13) — the AI ENRICHMENT column's config: a prompt per row that
+   * populates text, with the token ceiling in the field's own configuration.
+   *
+   * `prompt` may name other columns with `{key}` tokens, the same brace syntax a formula uses, so
+   * somebody who has written one already knows this one. `maxTokens` bounds ONE call's output and
+   * is also what the run's whole budget is derived from. `trigger.cron` is present only when
+   * `mode` is `"schedule"` — a cadence stored under `manual` is a setting nothing reads.
+   * `overwrite` decides what an automatic run may replace among the cells THE AGENT ITSELF wrote;
+   * a human-edited cell is never overwritten by any of them, which is why `"human"` is not one of
+   * the values (`core.user_tables.ai_enrich_human_authored` is the law).
+   *
+   * ⚠ THE BAG IS HERE WHILE `"ai_enrich"` IS NOT YET IN `CREATABLE_TYPES`, and the asymmetry is
+   * deliberate: the server stores this key today (`W34-T51`) and `verify_grid_ux::c_field_parity`
+   * tests server->client, so the interface has to mirror it now. The add-field MENU arrives with
+   * `W34-T53`. A kind the server accepts and the client does not offer is invisible; a kind the
+   * client offers and the server refuses deletes the user's column, which is the direction that
+   * shipped as a live defect for three waves (`image`, wave 19).
+   */
+  aiEnrich?: {
+    prompt: string;
+    model?: string;
+    maxTokens: number;
+    trigger: { mode: "manual" | "on_change" | "schedule"; cron?: string };
+    overwrite: "blank" | "stale" | "always";
+  };
   /**
    * ⭐ 2026-08-07 — a LINK to rows of another user database (Airtable's `multipleRecordLinks`).
    * The cell holds a COMMA-JOINED list of linked row ids, because a `Row` value is a scalar

web/src/filter-kit/FieldsHidePanel.tsx

@@ -200,7 +200,7 @@ export function FieldsHidePanel({
                   locked
                     ? `${fieldLabel(f)} is always first`
                     : canReorder
-                      ? `Reorder ${fieldLabel(f)} — drag, or use the arrow keys`
+                      ? `Reorder ${fieldLabel(f)}: drag, or use the arrow keys`
                       : `Reorder ${fieldLabel(f)} (clear the search first)`
                 }
                 title={

web/src/filter-kit/FilterBuilderPanel.tsx

@@ -1,988 +1,1003 @@
-// ---------------------------------------------------------------------------
-// filter-kit / FilterBuilderPanel.tsx
-// The Airtable-style RECURSIVE condition builder, as a MOUNTABLE PANEL.
-//
-// Extracted from customer-grid/Toolbar.tsx (wave 15, contract C-KIT) so the admin
-// permission editor and the grid toolbar build filters with the SAME control
-// rather than two that drift. Behaviour is identical to the toolbar's — this is a
-// move, not a rewrite.
-//
-// THE KIT FETCHES NOTHING. Every vocabulary it needs (fields, cohorts, measures,
-// the people a `user` field may name) arrives as a prop, which is what lets the
-// same panel serve a module whose rows this browser has never loaded.
-// ---------------------------------------------------------------------------
-
-import { useCallback, useMemo, useState } from "react";
-import type { ReactNode } from "react";
-import type {
-  Conjunction,
-  Field,
-  FilterGroup,
-  FilterNode,
-  FilterOp,
-  FilterRhs,
-  FilterRule,
-  FilterTree,
-  Measure,
-} from "../customer-grid/types";
-import {
-  COHORT_FIELD, MAX_COHORT_IDS, MAX_FILTER_DEPTH, RANK_OPS, STAT_KINDS, STAT_LABELS,
-  VALUE_FREE_OPS, choiceOptions, cohortIds, filterTreeConj, filterTreeNodes,
-  filterableFields, isFilterGroup, isMeasureRule, isRankOp, normalizeCohortOp, rhsColId,
-} from "../customer-grid/types";
-import type { CohortOp, StatKind } from "../customer-grid/types";
-import type { AnchorMode } from "../customer-grid/windows";
-import { ANCHOR_LABELS, ANCHOR_MODES, MAX_N } from "../customer-grid/windows";
-import { FieldSelectButton } from "../customer-grid/FieldSelect";
-import type { FieldSelectItem } from "../customer-grid/FieldSelect";
-import { WindowPicker } from "./WindowPicker";
-import {
-  COHORT_OP_LIST, DEFAULT_DATE_WINDOW, DEFAULT_WINDOW, MEASURE_MARK, MEASURE_OP_LIST,
-  MEASURE_PAIR_OP_LIST, WITHIN_KINDS, cohortOpLabel, groupSummary, hasRankCondition,
-  isDateFamily, isNumericType, newCondition, newRuleId, opLabel, opsForType, rankDefault,
-  withCurrent, withCurrentField,
-} from "./ops";
-import "../customer-grid/filters.css";
-
-/** The choice vocabulary of one field, resolved once and threaded down as a function so no
- *  level of the tree has to carry three separate maps to answer one question. */
-type ChoicesFor = (colId: string) => string[];
-
-/**
- * Owner item 3 — the DATE value: an anchor mode, then whatever that mode needs.
- *
- *   [is before] [one month ago]          <- mode only
- *   [is before] [N days ago] [30]        <- mode + a number
- *   [is before] [an exact date] [ 📅 ]   <- mode + a date
- *
- * The four value-free modes render NO second control, which is exactly why `isRuleActive` has
- * to know about them: an empty value would otherwise read as a half-typed condition and be
- * ignored, quietly widening the result.
- */
-function AnchorValue({
-  rule,
-  onPatch,
-}: {
-  rule: FilterRule;
-  onPatch: (p: Partial<FilterRule>) => void;
-}) {
-  const mode = rule.dateMode ?? "exact";
-  return (
-    <span className="cg-cond-anchor">
-      <select
-        className="cg-select cg-cond-anchor-mode"
-        value={mode}
-        aria-label="Date"
-        onChange={(e) => {
-          // Clear the value with the mode. A "30" left behind on `an exact date`, or a date
-          // left behind on `N days ago`, is state the user can neither see nor clear.
-          const next = e.target.value as AnchorMode;
-          onPatch({ dateMode: next, value: "" });
-        }}
-      >
-        {ANCHOR_MODES.map((m) => (
-          <option key={m} value={m}>
-            {m === "n_days_ago" ? ANCHOR_LABELS[m].replace("{n}", "N") : ANCHOR_LABELS[m]}
-          </option>
-        ))}
-      </select>
-      {mode === "n_days_ago" && (
-        <input
-          className="cg-input cg-cond-win-n"
-          type="number"
-          min={0}
-          max={MAX_N}
-          aria-label="Number of days ago"
-          value={rule.value}
-          onChange={(e) => onPatch({ value: e.target.value })}
-        />
-      )}
-      {mode === "exact" && (
-        <input
-          className="cg-input cg-cond-val"
-          type="date"
-          aria-label="Date"
-          value={rule.value}
-          onChange={(e) => onPatch({ value: e.target.value })}
-        />
-      )}
-    </span>
-  );
-}
-
-/**
- * CG-9 (owner item 4) — the comparand when it is ANOTHER ATTRIBUTE rather than a number.
- *
- * `Sales [this year] > Sales [year to date, last year]`. For a MEASURE the right side carries
- * its own window, which is the whole point: the two sides differ by period, not by name.
- */
-function RhsPicker({
-  rule,
-  options,
-  isMeasure,
-  onPatch,
-}: {
-  rule: FilterRule;
-  options: FieldSelectItem[];
-  isMeasure: boolean;
-  onPatch: (p: Partial<FilterRule>) => void;
-}) {
-  const rhs = rule.rhs;
-  const colId = rhsColId(rhs) ?? "";
-  return (
-    <span className="cg-cond-rhs">
-      {/* Item 20 — the empty comparand was an `<option value="">` that a select renders as
-          its first row; here it is the picker's PLACEHOLDER state, so "not chosen yet" is a
-          state of the control rather than an entry in the vocabulary. */}
-      <FieldSelectButton
-        className="cg-cond-field"
-        ariaLabel="Compare with field"
-        placeholder="Select a field…"
-        value={colId || undefined}
-        fields={options}
-        onChange={(key) => {
-          onPatch({
-            rhs: isMeasure
-              ? { kind: "measure", colId: key,
-                  window: (rhs?.kind === "measure" && rhs.window) || DEFAULT_WINDOW }
-              : { kind: "field", colId: key },
-          });
-        }}
-      />
-      {isMeasure && colId !== "" && (
-        <WindowPicker
-          window={(rhs?.kind === "measure" && rhs.window) || DEFAULT_WINDOW}
-          onWindow={(w) => onPatch({ rhs: { kind: "measure", colId, window: w } })}
-        />
-      )}
-    </span>
-  );
-}
-
-// --- the value control for one filter condition (type/op aware) ------------
-function ConditionValue({
-  rule,
-  type,
-  statusOptions,
-  onValue,
-  onValue2,
-}: {
-  rule: FilterRule;
-  type: Field["type"];
-  statusOptions: string[];
-  onValue: (v: string) => void;
-  onValue2: (v: string) => void;
-}) {
-  if (rule.op === "between") {
-    const inputType = type === "date" || type === "created_time" ? "date" : "number";
-    return (
-      <span className="cg-cond-between">
-        <input
-          className="cg-input cg-cond-val"
-          type={inputType}
-          value={rule.value}
-          onChange={(e) => onValue(e.target.value)}
-        />
-        <span className="cg-cond-and">and</span>
-        <input
-          className="cg-input cg-cond-val"
-          type={inputType}
-          value={rule.value2 ?? ""}
-          onChange={(e) => onValue2(e.target.value)}
-        />
-      </span>
-    );
-  }
-  if (
-    type === "status" || type === "select" || type === "user" || type === "multiselect"
-  ) {
-    return (
-      <select
-        className="cg-select cg-cond-val"
-        value={rule.value}
-        onChange={(e) => onValue(e.target.value)}
-      >
-        <option value="">Select…</option>
-        {statusOptions.map((v) => (
-          <option key={v} value={v}>
-            {v}
-          </option>
-        ))}
-      </select>
-    );
-  }
-  const inputType =
-    type === "date" || type === "created_time"
-      ? "date"
-      : isNumericType(type)
-        ? "number"
-        : "text";
-  return (
-    <input
-      className="cg-input cg-cond-val"
-      type={inputType}
-      placeholder="Value"
-      value={rule.value}
-      onChange={(e) => onValue(e.target.value)}
-    />
-  );
-}
-
-/**
- * C-OPS — the value control for a rank condition.
- *
- * Two shapes, because the two questions are different: a COUNT (or a percentage) is typed and
- * unbounded-ish, while a quantile is a choice from four or ten. Rendering the quantile as a
- * number box would let somebody type `inQuartile 7`, which the engine refuses outright — the
- * control that cannot express the invalid state is the better one.
- *
- * Bounds are on the input as `min`/`max` AND enforced in the engine, which is not redundancy:
- * a number input's bounds are advisory (typing past them is allowed and only surfaces on form
- * validation), so the box is a hint and `rankOps.bound` is the wall. A value outside the range
- * makes the condition UNANSWERABLE — it matches nothing and says so beside the count.
- */
-function RankValue({
-  rule,
-  onValue,
-}: {
-  rule: FilterRule;
-  onValue: (v: string) => void;
-}) {
-  const buckets = rule.op === "inQuartile" ? 4 : rule.op === "inDecile" ? 10 : 0;
-  if (buckets) {
-    return (
-      <select
-        className="cg-select cg-cond-val"
-        value={rule.value}
-        aria-label={rule.op === "inQuartile" ? "Quartile" : "Decile"}
-        onChange={(e) => onValue(e.target.value)}
-      >
-        {Array.from({ length: buckets }, (_, i) => String(i + 1)).map((n) => (
-          <option key={n} value={n}>
-            {/* The ends are the ones people mean, so they say so rather than making the
-                reader remember which end 1 is. */}
-            {n === "1"
-              ? `${n} (lowest)`
-              : n === String(buckets)
-                ? `${n} (highest)`
-                : n}
-          </option>
-        ))}
-      </select>
-    );
-  }
-  const pct = rule.op === "inTopPct" || rule.op === "inBottomPct";
-  return (
-    <input
-      className="cg-input cg-cond-val"
-      type="number"
-      min={1}
-      max={pct ? 100 : 10000}
-      step={1}
-      placeholder={pct ? "10" : "10"}
-      aria-label={pct ? "Percent" : "How many"}
-      value={rule.value}
-      onChange={(e) => onValue(e.target.value)}
-    />
-  );
-}
-
-/**
- * The cohorts a `Where [Cohort] [is any of] […]` condition names (owner, 2026-07-27).
- *
- * Chips plus an add-select, not a `<select multiple>`: a native multi-select needs ctrl-click to
- * build a set and shows what is chosen only by highlight, so the condition would stop reading as
- * a sentence — and the one thing this row has to do is say what it filters. The add-select also
- * keeps exactly one `.cg-cond-val` in the row, which is the control the shipped round-trip gate
- * drives; choosing a cohort there APPENDS rather than replaces.
- *
- * The select is rendered even when there is nothing left to add, disabled. A control that
- * vanishes at the cap would reflow the sentence mid-edit, and a gate that located it by class
- * would report a missing control rather than a full set.
- *
- * A cohort the view names but the user no longer has still renders, as `(deleted list)` — the
- * `withCurrent` rule applied to a set. The engine refuses such a condition outright (evalNode
- * returns false for the whole leaf, not for that member), so showing the stale chip is exactly
- * what lets somebody remove it.
- */
-function CohortPicker({
-  rule,
-  lists,
-  onPatch,
-}: {
-  rule: FilterRule;
-  lists: { id: string; name: string }[];
-  onPatch: (p: Partial<FilterRule>) => void;
-}) {
-  const chosen = cohortIds(rule.value);
-  const nameById = new Map(lists.map((l) => [l.id, l.name]));
-  const remaining = lists.filter((l) => !chosen.includes(l.id));
-  const canAdd = remaining.length > 0 && chosen.length < MAX_COHORT_IDS;
-  const setIds = (ids: string[]) => onPatch({ value: ids.join(",") });
-  return (
-    <span className="cg-cond-cohorts">
-      {chosen.map((id) => (
-        <span key={id} className={"cg-chip" + (nameById.has(id) ? "" : " cg-chip--gone")}>
-          <span className="cg-chip-text">{nameById.get(id) ?? "(deleted list)"}</span>
-          <button
-            type="button"
-            className="cg-chip-x"
-            aria-label={`Remove ${nameById.get(id) ?? id}`}
-            onClick={() => setIds(chosen.filter((c) => c !== id))}
-          >
-            ×
-          </button>
-        </span>
-      ))}
-      <select
-        className="cg-select cg-cond-val cg-cond-cohort-add"
-        value=""
-        aria-label="Cohort"
-        disabled={!canAdd}
-        onChange={(e) => e.target.value && setIds([...chosen, e.target.value])}
-      >
-        {/* "nothing left to add" rendered as "nothing left to ad…" at 136px — the fourth time a
-            closed vocabulary has outgrown its control here. Shortened, not widened: the control
-            is sized so a COHORT NAME stays readable, and that is the string that matters. */}
-        <option value="">
-          {!canAdd ? "all added" : chosen.length ? "Add a cohort…" : "Select a cohort…"}
-        </option>
-        {remaining.map((l) => (
-          <option key={l.id} value={l.id}>
-            {l.name}
-          </option>
-        ))}
-      </select>
-    </span>
-  );
-}
-
-// --- Filter: an Airtable-style RECURSIVE condition builder -----------------
-// Anatomy per Airtable (captured from the live product 2026-07-25):
-//   row 0    : static "Where"
-//   row 1    : the and/or DROPDOWN — one conjunction per LEVEL, not per condition
-//   row 2..n : static text mirroring that level's conjunction
-//   a group  : inset panel + summary line ("All/Any of the following are true…")
-//              carrying its OWN conjunction and its own Where/and-or rows
-// Nesting is capped at MAX_FILTER_DEPTH (3) — Airtable grays the group button out.
-
-/** The leading cell of a condition row: "Where", the conjunction picker, or the mirror. */
-function RowPrefix({
-  index,
-  conj,
-  onConj,
-}: {
-  index: number;
-  conj: Conjunction;
-  onConj: (c: Conjunction) => void;
-}) {
-  if (index === 0) return <span className="cg-cond-prefix">Where</span>;
-  if (index === 1)
-    return (
-      <select
-        className="cg-select cg-cond-conj"
-        value={conj}
-        aria-label="Combine conditions with"
-        onChange={(e) => onConj(e.target.value as Conjunction)}
-      >
-        <option value="and">and</option>
-        <option value="or">or</option>
-      </select>
-    );
-  return <span className="cg-cond-prefix cg-cond-conj-echo">{conj}</span>;
-}
-
-/** Everything a level of the tree needs that does not change as it recurses. One object rather
- *  than eight repeated props: the list grew past the point where each level restating it made
- *  the recursion easier to read. */
-interface LevelContext {
-  fields: Field[];
-  fieldByKey: Map<string, Field>;
-  measures: Measure[];
-  measureByKey: Map<string, Measure>;
-  /** Cohorts this user has — the vocabulary of `Where [Cohort] [is part of] […]`. */
-  lists: { id: string; name: string }[];
-  choicesFor: ChoicesFor;
-}
-
-/**
- * One nesting level: renders its nodes (leaves and nested groups) plus the
- * add-buttons. Recurses through GroupNode for children that are groups.
- */
-function ConditionLevel({
-  nodes,
-  conj,
-  depth,
-  ctx,
-  onNodes,
-  onConj,
-}: {
-  nodes: FilterNode[];
-  conj: Conjunction;
-  /** 1 = the root level. A new group's depth would be depth + 1. */
-  depth: number;
-  ctx: LevelContext;
-  onNodes: (nodes: FilterNode[]) => void;
-  onConj: (c: Conjunction) => void;
-}) {
-  /** Item 13 / R9 — which add-link was last used at THIS level. Per level, because the state
-   *  belongs to the row of buttons the user clicked, not to the builder as a whole. */
-  const [lastAdd, setLastAdd] = useState<"condition" | "group" | null>(null);
-  const setNode = (i: number, next: FilterNode) =>
-    onNodes(nodes.map((n, j) => (j === i ? next : n)));
-  const removeNode = (i: number) => onNodes(nodes.filter((_, j) => j !== i));
-
-  const addCondition = () => {
-    const c = newCondition(ctx.fields);
-    if (c) onNodes([...nodes, c]);
-  };
-  // New groups default to "or" — matching Airtable, and the useful case (the
-  // root ANDs a set of alternatives together).
-  const addGroup = () => {
-    const c = newCondition(ctx.fields);
-    if (c) onNodes([...nodes, { conj: "or", children: [c] }]);
-  };
-  const canNest = depth < MAX_FILTER_DEPTH;
-
-  return (
-    <>
-      {nodes.map((node, i) => (
-        <div className="cg-cond-line" key={i}>
-          <RowPrefix index={i} conj={conj} onConj={onConj} />
-          {isFilterGroup(node) ? (
-            <GroupNode
-              group={node}
-              depth={depth + 1}
-              ctx={ctx}
-              onGroup={(g) => setNode(i, g)}
-              onRemove={() => removeNode(i)}
-            />
-          ) : (
-            <LeafRow
-              rule={node}
-              ctx={ctx}
-              onRule={(r) => setNode(i, r)}
-              onRemove={() => removeNode(i)}
-            />
-          )}
-        </div>
-      ))}
-      {/* Item 13 (owner, 2026-08-02) — the two add-links are BOLD, and the one you just used
-          holds a dark-blue state.
-          ⚠ R9 says that state lasts while the popover is open and a fresh open starts
-          neutral — which is exactly what a `useState` HERE gives for free, because `Popover`
-          renders its children only while open (`{open && <AnchoredOverlay…>}`) and unmounts
-          them on close. Nothing persists it, nothing has to clear it, and there is no way for
-          it to survive a reopen. A `:active` pseudo-class would have been the wrong tool
-          twice over: it lasts for the duration of the mouse-down, and it says "you are
-          pressing this" rather than "this is the one you have been using". */}
-      <div className="cg-builder-add">
-        <button
-          type="button"
-          className={"cg-link-btn" + (lastAdd === "condition" ? " is-on" : "")}
-          onClick={() => {
-            setLastAdd("condition");
-            addCondition();
-          }}
-        >
-          + Add condition
-        </button>
-        <button
-          type="button"
-          className={"cg-link-btn" + (lastAdd === "group" ? " is-on" : "")}
-          onClick={() => {
-            setLastAdd("group");
-            addGroup();
-          }}
-          disabled={!canNest}
-          title={
-            canNest
-              ? "Group conditions so they evaluate together"
-              : `Condition groups can nest ${MAX_FILTER_DEPTH} levels deep`
-          }
-        >
-          + Add condition group
-        </button>
-      </div>
-    </>
-  );
-}
-
-/**
- * One leaf condition: field ▾ | (window ▾) | operator ▾ | value | remove.
- *
- * The window bracket appears only for a MEASURE (CG-8) — a column already has its window baked
- * in ("YTD $" IS year-to-date), and offering one there would imply it could be changed.
- */
-function LeafRow({
-  rule,
-  ctx,
-  onRule,
-  onRemove,
-}: {
-  rule: FilterRule;
-  ctx: LevelContext;
-  onRule: (r: FilterRule) => void;
-  onRemove: () => void;
-}) {
-  const { fields, fieldByKey, measures, measureByKey, lists, choicesFor } = ctx;
-  const isMeasure = isMeasureRule(rule);
-  const isCohort = rule.colId === COHORT_FIELD;
-  const hasCohorts = lists.length > 0;
-  const t = isMeasure
-    ? measureByKey.get(rule.colId)?.type ?? "currency"
-    : fieldByKey.get(rule.colId)?.type ?? "text";
-  const patch = (p: Partial<FilterRule>) => onRule({ ...rule, ...p });
-  // Switching field resets op to that type's default + clears the value(s), so a
-  // numeric op can never linger on a text column. Crossing the column/measure line also
-  // adds or removes the WINDOW and the rule ID, since those are what MAKE it a measure —
-  // leaving a window behind on a column condition would keep the server answering it. The
-  // rhs goes too: a comparand chosen for the old field is meaningless against the new one.
-  const onField = (key: string) => {
-    if (key === COHORT_FIELD) {
-      onRule({ colId: COHORT_FIELD, op: COHORT_OP_LIST[0], value: "" });
-      return;
-    }
-    const m = measureByKey.get(key);
-    if (m) {
-      onRule({
-        id: rule.id ?? newRuleId(),
-        colId: key,
-        op: MEASURE_OP_LIST[0],
-        value: "",
-        value2: undefined,
-        window: rule.window ?? DEFAULT_WINDOW,
-      });
-      return;
-    }
-    const nt = fieldByKey.get(key)?.type ?? "text";
-    onRule({ colId: key, op: opsForType(nt)[0], value: "", value2: undefined });
-  };
-  // Switching to/from a value-free op clears the stale value it can't show. `within` swaps the
-  // value for a RANGE and drops any field comparand, since a range has no other side.
-  const onOp = (op: FilterOp | CohortOp) => {
-    // A cohort keeps its SET when the set operator changes — "any of these three" and "none of
-    // these three" are the same three cohorts asked about differently, and clearing them would
-    // make the obvious edit destructive.
-    if (isCohort) return patch({ op });
-    // C-OPS: a rank op arrives with its N already chosen (see rankDefault) and drops every
-    // comparand — "the top 10 compared with another field" is not a question.
-    if (isRankOp(op as string))
-      return onRule({ ...rule, op: op as FilterOp, value: rankDefault(op as FilterOp),
-                      value2: undefined, rhs: undefined, dateWindow: undefined });
-    if (VALUE_FREE_OPS.has(op as FilterOp))
-      return onRule({ ...rule, op, value: "", value2: undefined, rhs: undefined });
-    if (op === "within")
-      return onRule({ ...rule, op, value: "", value2: undefined, rhs: undefined,
-                      dateWindow: rule.dateWindow ?? DEFAULT_DATE_WINDOW });
-    if (rule.op === "within")
-      return onRule({ ...rule, op, dateWindow: undefined, value: "" });
-    patch({ op });
-  };
-  // Owner item 4: the value box is REPLACEABLE by another attribute. Offered where a
-  // comparison between two of the same kind of thing means something — numbers against
-  // numbers, dates against dates, a measure against a measure over its own period.
-  const rhsOptions: FieldSelectItem[] = isMeasure
-    ? measures.map((m) => ({ key: m.key, label: m.label, type: MEASURE_MARK }))
-    : fields
-        .filter((f) => f.key !== rule.colId
-          && (isNumericType(t) ? isNumericType(f.type) : f.type === t))
-        .map((f) => ({ key: f.key, label: f.label, type: f.type }));
-  const canCompareField = !isCohort && rule.op !== "within"
-    && !VALUE_FREE_OPS.has(rule.op as FilterOp) && !isRankOp(rule.op)
-    && rhsOptions.length > 0 && (isMeasure || isNumericType(t) || isDateFamily(t));
-  const usingStat = rule.rhs?.kind === "stat";
-  const usingField = rule.rhs != null && !usingStat;
-  // Explicitly widened: the cohort branch contributes a DISJOINT vocabulary, and without the
-  // annotation `withCurrent`'s `T extends string` infers from the first branch alone.
-  const opList: (FilterOp | CohortOp)[] = isMeasure
-    ? (usingField || usingStat ? MEASURE_PAIR_OP_LIST : MEASURE_OP_LIST)
-    : isCohort ? COHORT_OP_LIST : opsForType(t);
-  const opValue: FilterOp | CohortOp = isCohort ? normalizeCohortOp(rule.op) : rule.op;
-  // C-OPS — the RANK family, offered under its own divider for the numeric family only.
-  //
-  // A COLUMN only: a measure leaf is answered by a server-side pid set over a window, so
-  // ranking one client-side would be a second answer to the same question (and the host's
-  // MEASURE_OPS deliberately does not carry these). A cohort leaf is set membership.
-  //
-  // Offered separately rather than appended to `opsForType` because these operators are a
-  // different KIND of question — every other one is about this row's value, these are about
-  // where the row sits among the others — and a divider is the cheapest way to say so.
-  const canRank = !isMeasure && !isCohort && isNumericType(t);
-  // `withCurrent` runs over the COMBINED offer so a rule already holding a rank op is not
-  // appended a second time; the split below then puts each op under the right heading. A
-  // rank op on a field that can no longer be ranked still renders — as itself, in the group,
-  // which is what lets somebody see it and change it.
-  const offeredOps = withCurrent(canRank ? [...opList, ...RANK_OPS] : opList, opValue);
-  const plainOps = offeredOps.filter((op) => !isRankOp(op));
-  const rankedOps = offeredOps.filter((op) => isRankOp(op));
-
-  return (
-    <span className={"cg-cond-row" + (isMeasure ? " is-measure" : "")
-                     + (isCohort ? " is-cohort" : "")
-                     + (rule.rhs != null ? " has-rhs" : "")}>
-      {/* ONE flat list (owner item 1). A measure used to sit under a "Measures (pick a
-          period)" optgroup; the owner's instruction was that it is all the same list —
-          you pick a thing to filter on, and a measure simply also asks for a period. Item 20
-          adds the type MARK to each row and takes NO grouping with it: the marks are what the
-          optgroup was reaching for, and they say it per row instead of splitting the list. */}
-      <FieldSelectButton
-        className="cg-cond-field"
-        ariaLabel="Field"
-        value={rule.colId}
-        onChange={onField}
-        fields={[
-          ...withCurrentField(fields, rule.colId, fieldByKey, measureByKey, hasCohorts),
-          ...measures.map((m) => ({ key: m.key, label: m.label, type: MEASURE_MARK })),
-          // A cohort leaf asks about membership of a SET, which is the multiselect mark's
-          // own meaning — the vocabulary already had the right glyph for it.
-          ...(hasCohorts
-            ? [{ key: COHORT_FIELD, label: "Cohort", type: "multiselect" as const }]
-            : []),
-        ]}
-      />
-      {isMeasure && (
-        <WindowPicker
-          window={rule.window ?? DEFAULT_WINDOW}
-          onWindow={(w) => patch({ window: w })}
-        />
-      )}
-      <select
-        className="cg-select cg-cond-op"
-        // A view saved before 2026-07-27 holds `eq`/`neq`. Normalising HERE, rather than letting
-        // `withCurrent` append it, is the difference between a legacy rule reading "is any of"
-        // once and the list carrying two options with the same label and different values. The
-        // display stays truthful either way — `eq` IS `anyOf` — and the first edit writes the
-        // new op, matching what the validator already does on the server.
-        value={opValue}
-        aria-label="Condition"
-        onChange={(e) => onOp(e.target.value as FilterOp | CohortOp)}
-      >
-        {plainOps.map((op) => (
-          <option key={op} value={op}>
-            {/* `op as FilterOp` is safe by construction, not by hope: `opList` is the cohort
-                vocabulary EXACTLY when `isCohort`, so the other branch only ever sees the
-                column/measure one. The two lists are disjoint, so a wrong cast would show as a
-                raw key ("anyOf") on screen rather than as a plausible label. */}
-            {isCohort ? cohortOpLabel(op) : opLabel(op as FilterOp, t)}
-          </option>
-        ))}
-        {rankedOps.length > 0 && (
-          <optgroup label="Ranked">
-            {rankedOps.map((op) => (
-              <option key={op} value={op}>
-                {opLabel(op as FilterOp, t)}
-              </option>
-            ))}
-          </optgroup>
-        )}
-      </select>
-      {canCompareField && (
-        // The switch between "a value I type" and "another attribute". Two options rather than
-        // a checkbox, because the row already reads as a sentence and this is the noun slot.
-        <select
-          className="cg-select cg-cond-mode"
-          value={usingStat ? "stat" : usingField ? "field" : "value"}
-          aria-label="Compare against"
-          onChange={(e) => {
-            const mode = e.target.value;
-            if (mode === "stat")
-              return patch({ rhs: { kind: "stat", stat: "median" },
-                             value: "", value2: undefined,
-                             // a statistic is a computed cut-off: the same four ops a
-                             // measure-vs-measure allows, for the same float reason
-                             // reachable only via `canCompareField`, which excludes a cohort
-                             op: MEASURE_PAIR_OP_LIST.includes(rule.op as FilterOp)
-                               ? rule.op : MEASURE_PAIR_OP_LIST[1] });
-            if (mode === "field") {
-              // An EMPTY comparand: incomplete, so the rule stays inactive until a field is
-              // picked. RhsPicker adds the window when the measure side gets one.
-              const empty: FilterRhs = isMeasure
-                ? { kind: "measure", colId: "", window: DEFAULT_WINDOW }
-                : { kind: "field", colId: "" };
-              return patch({ rhs: empty, value: "", value2: undefined });
-            }
-            patch({ rhs: undefined, value: "" });
-          }}
-        >
-          <option value="value">a value</option>
-          <option value="field">another field</option>
-          {/* Statistics are computed SERVER-SIDE over the caller's pool, so they are offered
-              for a MEASURE only. A column statistic would need a second percentile
-              implementation on the client and the lock-step gate that goes with it. */}
-          {isMeasure && <option value="stat">a statistic</option>}
-        </select>
-      )}
-      {/* value-free ops render NO value control (Airtable does the same) */}
-      {VALUE_FREE_OPS.has(rule.op as FilterOp) ? (
-        <span className="cg-cond-val cg-cond-noval" aria-hidden />
-      ) : usingStat ? (
-        <select
-          className="cg-select cg-cond-val cg-cond-stat"
-          value={rule.rhs?.kind === "stat" ? rule.rhs.stat : "median"}
-          aria-label="Statistic"
-          onChange={(e) => patch({ rhs: { kind: "stat", stat: e.target.value as StatKind } })}
-        >
-          {STAT_KINDS.map((k) => (
-            <option key={k} value={k}>
-              {STAT_LABELS[k]}
-            </option>
-          ))}
-        </select>
-      ) : usingField ? (
-        <RhsPicker rule={rule} options={rhsOptions} isMeasure={isMeasure} onPatch={patch} />
-      ) : isCohort ? (
-        <CohortPicker rule={rule} lists={lists} onPatch={patch} />
-      ) : isRankOp(rule.op) ? (
-        <RankValue rule={rule} onValue={(v) => patch({ value: v })} />
-      ) : rule.op === "within" ? (
-        <WindowPicker
-          window={rule.dateWindow ?? DEFAULT_DATE_WINDOW}
-          onWindow={(w) => patch({ dateWindow: w })}
-          kinds={WITHIN_KINDS}
-        />
-      ) : isDateFamily(t) ? (
-        <AnchorValue rule={rule} onPatch={patch} />
-      ) : (
-        <ConditionValue
-          rule={rule}
-          type={t}
-          statusOptions={choicesFor(rule.colId)}
-          onValue={(v) => patch({ value: v })}
-          onValue2={(v) => patch({ value2: v })}
-        />
-      )}
-      <button
-        type="button"
-        className="cg-cond-x"
-        aria-label="Remove condition"
-        onClick={onRemove}
-      >
-        ×
-      </button>
-    </span>
-  );
-}
-
-/** A nested condition group: summary line + its own recursive level. */
-function GroupNode({
-  group,
-  depth,
-  ctx,
-  onGroup,
-  onRemove,
-}: {
-  group: FilterGroup;
-  depth: number;
-  ctx: LevelContext;
-  onGroup: (g: FilterGroup) => void;
-  onRemove: () => void;
-}) {
-  return (
-    <span className="cg-cond-group" data-depth={depth}>
-      <span className="cg-cond-group-head">
-        <span className="cg-cond-group-sum">
-          {group.children.length
-            ? groupSummary(group.conj)
-            : "Add a condition to this group…"}
-        </span>
-        <button
-          type="button"
-          className="cg-cond-x"
-          aria-label="Remove condition group"
-          onClick={onRemove}
-        >
-          ×
-        </button>
-      </span>
-      <span className="cg-cond-group-body">
-        <ConditionLevel
-          nodes={group.children}
-          conj={group.conj}
-          depth={depth}
-          ctx={ctx}
-          onNodes={(children) => onGroup({ ...group, children })}
-          onConj={(conj) => onGroup({ ...group, conj })}
-        />
-      </span>
-    </span>
-  );
-}
-
-export interface FilterBuilderPanelProps {
-  /**
-   * The module's COMPLETE field list. The panel offers the FILTERABLE ones
-   * (`filterableFields`) and resolves labels from all of them — a condition saved against a
-   * column that has since stopped being filterable must still render its own name rather than
-   * turning into "?", so narrowing the picker may never orphan history.
-   */
-  fields: Field[];
-  /** The whole filter as ONE value — nodes plus the root conjunction. See types.FilterTree. */
-  filters: FilterTree;
-  onChange: (next: FilterTree) => void;
-  /** Cohorts the subject of this filter has, for `Where [Cohort] [is any of] […]`. */
-  cohorts?: { id: string; name: string }[];
-  /** CG-8 — measures the builder may offer alongside the columns. Absent = columns only. */
-  measures?: Measure[];
-  /** The people a `user` field may name. Never invented here — the host's real user list. */
-  userOptions?: string[];
-  /**
-   * The tenant's today, ISO. RESERVED: it is the anchor a relative window resolves against,
-   * and it is accepted so a caller that holds it (the grid, the admin editor) has one obvious
-   * place to put it. It renders NOTHING today — a "this resolves to <range>" hint under the
-   * date controls was considered for wave 15 and rejected as a visual delta C-KIT forbids.
-   * Kept in the signature rather than added later so no call site has to change to gain it.
-   */
-  today?: string;
-  /**
-   * The per-field CHOICE VOCABULARY, by field key. The one prop that is not cosmetic when it
-   * is absent: some columns take their values from the DATA (the grid discovers them from its
-   * rows — `customer-grid/types.ts::choiceVocabulary`), which a panel over a module whose rows
-   * it has never loaded cannot do. Absent, choices fall back to the field's own declared
-   * `options` and, for `user`, to `userOptions`.
-   *
-   * ⛔ **Which columns those are is NOT decided by the type, and the old wording here saying
-   * "only Odoo `status` columns come up empty" was wrong in a way that shipped a live defect**
-   * (owner item 24, 2026-08-06). `stock_bucket` on the Product grid is declared `select` and
-   * declares no `options` — its vocabulary is computed server-side and rides the rows, exactly
-   * like a `status` column's. **Any column with no declared `options` needs this prop**, whatever
-   * its type says. A host that cannot enumerate one renders an empty picker; see `choicesFor`.
-   */
-  statusValues?: Record<string, string[]>;
-  /**
-   * Item 12 (C-LOCK) — this view is LOCKED to a cohort. Present = say so, because the lock
-   * narrows the list and is not one of the conditions shown here: without the banner the count
-   * and the conditions disagree with no visible reason.
-   *
-   * `name`/`count` ABSENT means the reader cannot see the set — a shared view locked to
-   * somebody else's cohort. The engine matches nothing in that case (fail-closed, the
-   * cohort-leaf law), so the banner has to say which kind of nothing this is.
-   */
-  cohortLock?: { name?: string; count?: number };
-  /**
-   * Extra footer content, rendered beside "Clear all" — the grid puts its "Copy from another
-   * view" door here. A SLOT rather than props, exactly like the toolbar's `cohortAction`: the
-   * door needs the other views and the view-patch plumbing, none of which a panel that also
-   * serves an admin editor should know about.
-   */
-  footerExtra?: ReactNode;
-}
-
-export function FilterBuilderPanel({
-  fields,
-  filters,
-  onChange,
-  cohorts = [],
-  measures = [],
-  userOptions,
-  statusValues,
-  cohortLock,
-  footerExtra,
-}: FilterBuilderPanelProps) {
-  const nodes = filterTreeNodes(filters);
-  const conj = filterTreeConj(filters);
-  // The COMPLETE map on purpose (see `fields` above): the picker is narrowed, the label
-  // resolution is not.
-  const fieldByKey = useMemo(() => {
-    const m = new Map<string, Field>();
-    for (const f of fields) m.set(f.key, f);
-    return m;
-  }, [fields]);
-  const condFields = useMemo(() => filterableFields(fields), [fields]);
-  const measureByKey = useMemo(() => {
-    const m = new Map<string, Measure>();
-    for (const item of measures) m.set(item.key, item);
-    return m;
-  }, [measures]);
-  const choicesFor = useCallback<ChoicesFor>(
-    (colId) => {
-      // A supplied map WINS, including when it holds an empty list: "this status column has no
-      // values in the data" is an answer, not a missing one.
-      const declared = statusValues?.[colId];
-      if (declared) return declared;
-      const f = fieldByKey.get(colId);
-      if (!f) return [];
-      return f.type === "user" ? userOptions ?? [] : choiceOptions(f);
-    },
-    [statusValues, fieldByKey, userOptions]
-  );
-  const ctx = useMemo<LevelContext>(
-    () => ({ fields: condFields, fieldByKey, measures, measureByKey, lists: cohorts,
-             choicesFor }),
-    [condFields, fieldByKey, measures, measureByKey, cohorts, choicesFor]
-  );
-
-  return (
-    <div className="cg-pop-body cg-builder">
-      <div className="cg-pop-title">Filter</div>
-      {/* C-LOCK (item 12) — the lock is NOT a condition row: it cannot be written here and
-          cannot be removed here (the view menu owns it). So it has to be SAID here, above
-          the conditions it bounds — otherwise the count and the conditions disagree and the
-          builder shows nothing that explains the gap. A reader who cannot see the set gets a
-          different sentence, because the engine shows them nobody and "no records" alone does
-          not distinguish a permission wall from a filter that genuinely matches nobody. */}
-      {cohortLock && (
-        <div className="cg-flt-lockchip">
-          {cohortLock.name
-            ? `Customer list locked to ${cohortLock.name}` +
-              (typeof cohortLock.count === "number"
-                ? ` · ${cohortLock.count.toLocaleString()} ${
-                    cohortLock.count === 1 ? "customer" : "customers"
-                  }`
-                : "")
-            : "Customer list locked to a set you cannot see"}
-        </div>
-      )}
-      {nodes.length === 0 ? (
-        <div className="cg-builder-empty">
-          No conditions. Add one to narrow the list.
-        </div>
-      ) : (
-        <div className="cg-builder-caption">In this view, show records</div>
-      )}
-      <ConditionLevel
-        nodes={nodes}
-        conj={conj}
-        depth={1}
-        ctx={ctx}
-        onNodes={(next) => onChange({ conj, nodes: next })}
-        onConj={(next) => onChange({ conj: next, nodes })}
-      />
-      {/* C-OPS — a ranked condition answers a question about the OTHER records, and there is
-          no way to see from the row which others. Three sentences, shown only while one is in
-          the tree: the population, what is left out of it, and the one thing about quantiles
-          that is genuinely not guessable (equal-size by RANK, so two identical values can
-          land on opposite sides of a boundary). */}
-      {hasRankCondition(nodes) && (
-        <div className="cg-pop-note">
-          Ranked among the records your other conditions keep — so “top 10” inside a filtered
-          view means the top 10 of that view. Records with no value are not ranked at all.
-          Quartiles and deciles are equal-size slices BY RANK, not by value.
-        </div>
-      )}
-      {/* The footer carries "Clear all" (only when there is something to clear) and whatever
-          door the host mounts in `footerExtra`.
-          ⚠ The door is in the FOOTER rather than beside the add-links, where the reference
-          screenshot has it, for one structural reason: `.cg-builder-add` is emitted once per
-          NESTING LEVEL, so a link there would repeat inside every condition group and offer
-          to overwrite the whole view from inside one of its brackets. The footer is the one
-          place in this popover that means "the view", which is what the copy acts on. It is
-          also offered when there are NO conditions yet, which is when somebody most wants to
-          start from another view. */}
-      {(nodes.length > 0 || footerExtra) && (
-        <div className="cg-pop-footer cg-builder-footer">
-          {nodes.length > 0 && (
-            <button
-              type="button"
-              className="cg-link-btn"
-              onClick={() => onChange({ conj, nodes: [] })}
-            >
-              Clear all
-            </button>
-          )}
-          {footerExtra}
-        </div>
-      )}
-    </div>
-  );
-}
+// ---------------------------------------------------------------------------
+// filter-kit / FilterBuilderPanel.tsx
+// The Airtable-style RECURSIVE condition builder, as a MOUNTABLE PANEL.
+//
+// Extracted from customer-grid/Toolbar.tsx (wave 15, contract C-KIT) so the admin
+// permission editor and the grid toolbar build filters with the SAME control
+// rather than two that drift. Behaviour is identical to the toolbar's — this is a
+// move, not a rewrite.
+//
+// THE KIT FETCHES NOTHING. Every vocabulary it needs (fields, cohorts, measures,
+// the people a `user` field may name) arrives as a prop, which is what lets the
+// same panel serve a module whose rows this browser has never loaded.
+// ---------------------------------------------------------------------------
+
+import { useCallback, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import type {
+  Conjunction,
+  Field,
+  FilterGroup,
+  FilterNode,
+  FilterOp,
+  FilterRhs,
+  FilterRule,
+  FilterTree,
+  Measure,
+} from "../customer-grid/types";
+import {
+  COHORT_FIELD, MAX_COHORT_IDS, MAX_FILTER_DEPTH, RANK_OPS, STAT_KINDS, STAT_LABELS,
+  VALUE_FREE_OPS, choiceOptions, cohortIds, filterTreeConj, filterTreeNodes,
+  filterableFields, isFilterGroup, isMeasureRule, isRankOp, normalizeCohortOp, rhsColId,
+} from "../customer-grid/types";
+import type { CohortOp, StatKind } from "../customer-grid/types";
+import type { AnchorMode } from "../customer-grid/windows";
+import { ANCHOR_LABELS, ANCHOR_MODES, MAX_N } from "../customer-grid/windows";
+import { FieldSelectButton } from "../customer-grid/FieldSelect";
+import type { FieldSelectItem } from "../customer-grid/FieldSelect";
+import { WindowPicker } from "./WindowPicker";
+import {
+  COHORT_OP_LIST, DEFAULT_DATE_WINDOW, DEFAULT_WINDOW, MEASURE_MARK, MEASURE_OP_LIST,
+  MEASURE_PAIR_OP_LIST, WITHIN_KINDS, cohortOpLabel, groupSummary,
+  isDateFamily, isNumericType, newCondition, newRuleId, opLabel, opsForType, rankDefault,
+  withCurrent, withCurrentField,
+} from "./ops";
+import "../customer-grid/filters.css";
+
+/** The choice vocabulary of one field, resolved once and threaded down as a function so no
+ *  level of the tree has to carry three separate maps to answer one question. */
+type ChoicesFor = (colId: string) => string[];
+
+/**
+ * Owner item 3 — the DATE value: an anchor mode, then whatever that mode needs.
+ *
+ *   [is before] [one month ago]          <- mode only
+ *   [is before] [N days ago] [30]        <- mode + a number
+ *   [is before] [an exact date] [ 📅 ]   <- mode + a date
+ *
+ * The four value-free modes render NO second control, which is exactly why `isRuleActive` has
+ * to know about them: an empty value would otherwise read as a half-typed condition and be
+ * ignored, quietly widening the result.
+ */
+function AnchorValue({
+  rule,
+  onPatch,
+}: {
+  rule: FilterRule;
+  onPatch: (p: Partial<FilterRule>) => void;
+}) {
+  const mode = rule.dateMode ?? "exact";
+  return (
+    <span className="cg-cond-anchor">
+      <select
+        className="cg-select cg-cond-anchor-mode"
+        value={mode}
+        aria-label="Date"
+        onChange={(e) => {
+          // Clear the value with the mode. A "30" left behind on `an exact date`, or a date
+          // left behind on `N days ago`, is state the user can neither see nor clear.
+          const next = e.target.value as AnchorMode;
+          onPatch({ dateMode: next, value: "" });
+        }}
+      >
+        {ANCHOR_MODES.map((m) => (
+          <option key={m} value={m}>
+            {m === "n_days_ago" ? ANCHOR_LABELS[m].replace("{n}", "N") : ANCHOR_LABELS[m]}
+          </option>
+        ))}
+      </select>
+      {mode === "n_days_ago" && (
+        <input
+          className="cg-input cg-cond-win-n"
+          type="number"
+          min={0}
+          max={MAX_N}
+          aria-label="Number of days ago"
+          value={rule.value}
+          onChange={(e) => onPatch({ value: e.target.value })}
+        />
+      )}
+      {mode === "exact" && (
+        <input
+          className="cg-input cg-cond-val"
+          type="date"
+          aria-label="Date"
+          value={rule.value}
+          onChange={(e) => onPatch({ value: e.target.value })}
+        />
+      )}
+    </span>
+  );
+}
+
+/**
+ * CG-9 (owner item 4) — the comparand when it is ANOTHER ATTRIBUTE rather than a number.
+ *
+ * `Sales [this year] > Sales [year to date, last year]`. For a MEASURE the right side carries
+ * its own window, which is the whole point: the two sides differ by period, not by name.
+ */
+function RhsPicker({
+  rule,
+  options,
+  isMeasure,
+  onPatch,
+}: {
+  rule: FilterRule;
+  options: FieldSelectItem[];
+  isMeasure: boolean;
+  onPatch: (p: Partial<FilterRule>) => void;
+}) {
+  const rhs = rule.rhs;
+  const colId = rhsColId(rhs) ?? "";
+  return (
+    <span className="cg-cond-rhs">
+      {/* Item 20 — the empty comparand was an `<option value="">` that a select renders as
+          its first row; here it is the picker's PLACEHOLDER state, so "not chosen yet" is a
+          state of the control rather than an entry in the vocabulary. */}
+      <FieldSelectButton
+        className="cg-cond-field"
+        ariaLabel="Compare with field"
+        placeholder="Select a field…"
+        value={colId || undefined}
+        fields={options}
+        onChange={(key) => {
+          onPatch({
+            rhs: isMeasure
+              ? { kind: "measure", colId: key,
+                  window: (rhs?.kind === "measure" && rhs.window) || DEFAULT_WINDOW }
+              : { kind: "field", colId: key },
+          });
+        }}
+      />
+      {isMeasure && colId !== "" && (
+        <WindowPicker
+          window={(rhs?.kind === "measure" && rhs.window) || DEFAULT_WINDOW}
+          onWindow={(w) => onPatch({ rhs: { kind: "measure", colId, window: w } })}
+        />
+      )}
+    </span>
+  );
+}
+
+// --- the value control for one filter condition (type/op aware) ------------
+function ConditionValue({
+  rule,
+  type,
+  statusOptions,
+  onValue,
+  onValue2,
+}: {
+  rule: FilterRule;
+  type: Field["type"];
+  statusOptions: string[];
+  onValue: (v: string) => void;
+  onValue2: (v: string) => void;
+}) {
+  if (rule.op === "between") {
+    const inputType = type === "date" || type === "created_time" ? "date" : "number";
+    return (
+      <span className="cg-cond-between">
+        <input
+          className="cg-input cg-cond-val"
+          type={inputType}
+          value={rule.value}
+          onChange={(e) => onValue(e.target.value)}
+        />
+        <span className="cg-cond-and">and</span>
+        <input
+          className="cg-input cg-cond-val"
+          type={inputType}
+          value={rule.value2 ?? ""}
+          onChange={(e) => onValue2(e.target.value)}
+        />
+      </span>
+    );
+  }
+  if (
+    type === "status" || type === "select" || type === "user" || type === "multiselect"
+  ) {
+    return (
+      <select
+        className="cg-select cg-cond-val"
+        value={rule.value}
+        onChange={(e) => onValue(e.target.value)}
+      >
+        <option value="">Select…</option>
+        {statusOptions.map((v) => (
+          <option key={v} value={v}>
+            {v}
+          </option>
+        ))}
+      </select>
+    );
+  }
+  const inputType =
+    type === "date" || type === "created_time"
+      ? "date"
+      : isNumericType(type)
+        ? "number"
+        : "text";
+  return (
+    <input
+      className="cg-input cg-cond-val"
+      type={inputType}
+      placeholder="Value"
+      value={rule.value}
+      onChange={(e) => onValue(e.target.value)}
+    />
+  );
+}
+
+/**
+ * C-OPS — the value control for a rank condition.
+ *
+ * Two shapes, because the two questions are different: a COUNT (or a percentage) is typed and
+ * unbounded-ish, while a quantile is a choice from four or ten. Rendering the quantile as a
+ * number box would let somebody type `inQuartile 7`, which the engine refuses outright — the
+ * control that cannot express the invalid state is the better one.
+ *
+ * Bounds are on the input as `min`/`max` AND enforced in the engine, which is not redundancy:
+ * a number input's bounds are advisory (typing past them is allowed and only surfaces on form
+ * validation), so the box is a hint and `rankOps.bound` is the wall. A value outside the range
+ * makes the condition UNANSWERABLE — it matches nothing and says so beside the count.
+ */
+function RankValue({
+  rule,
+  onValue,
+}: {
+  rule: FilterRule;
+  onValue: (v: string) => void;
+}) {
+  const buckets = rule.op === "inQuartile" ? 4 : rule.op === "inDecile" ? 10 : 0;
+  if (buckets) {
+    return (
+      <select
+        className="cg-select cg-cond-val"
+        value={rule.value}
+        aria-label={rule.op === "inQuartile" ? "Quartile" : "Decile"}
+        onChange={(e) => onValue(e.target.value)}
+      >
+        {Array.from({ length: buckets }, (_, i) => String(i + 1)).map((n) => (
+          <option key={n} value={n}>
+            {/* The ends are the ones people mean, so they say so rather than making the
+                reader remember which end 1 is. */}
+            {n === "1"
+              ? `${n} (lowest)`
+              : n === String(buckets)
+                ? `${n} (highest)`
+                : n}
+          </option>
+        ))}
+      </select>
+    );
+  }
+  const pct = rule.op === "inTopPct" || rule.op === "inBottomPct";
+  return (
+    <input
+      className="cg-input cg-cond-val"
+      type="number"
+      min={1}
+      max={pct ? 100 : 10000}
+      step={1}
+      placeholder={pct ? "10" : "10"}
+      aria-label={pct ? "Percent" : "How many"}
+      value={rule.value}
+      onChange={(e) => onValue(e.target.value)}
+    />
+  );
+}
+
+/**
+ * The cohorts a `Where [Cohort] [is any of] […]` condition names (owner, 2026-07-27).
+ *
+ * Chips plus an add-select, not a `<select multiple>`: a native multi-select needs ctrl-click to
+ * build a set and shows what is chosen only by highlight, so the condition would stop reading as
+ * a sentence — and the one thing this row has to do is say what it filters. The add-select also
+ * keeps exactly one `.cg-cond-val` in the row, which is the control the shipped round-trip gate
+ * drives; choosing a cohort there APPENDS rather than replaces.
+ *
+ * The select is rendered even when there is nothing left to add, disabled. A control that
+ * vanishes at the cap would reflow the sentence mid-edit, and a gate that located it by class
+ * would report a missing control rather than a full set.
+ *
+ * A cohort the view names but the user no longer has still renders, as `(deleted list)` — the
+ * `withCurrent` rule applied to a set. The engine refuses such a condition outright (evalNode
+ * returns false for the whole leaf, not for that member), so showing the stale chip is exactly
+ * what lets somebody remove it.
+ */
+function CohortPicker({
+  rule,
+  lists,
+  onPatch,
+}: {
+  rule: FilterRule;
+  lists: { id: string; name: string }[];
+  onPatch: (p: Partial<FilterRule>) => void;
+}) {
+  const chosen = cohortIds(rule.value);
+  const nameById = new Map(lists.map((l) => [l.id, l.name]));
+  const remaining = lists.filter((l) => !chosen.includes(l.id));
+  const canAdd = remaining.length > 0 && chosen.length < MAX_COHORT_IDS;
+  const setIds = (ids: string[]) => onPatch({ value: ids.join(",") });
+  return (
+    <span className="cg-cond-cohorts">
+      {chosen.map((id) => (
+        <span key={id} className={"cg-chip" + (nameById.has(id) ? "" : " cg-chip--gone")}>
+          <span className="cg-chip-text">{nameById.get(id) ?? "(deleted list)"}</span>
+          <button
+            type="button"
+            className="cg-chip-x"
+            aria-label={`Remove ${nameById.get(id) ?? id}`}
+            onClick={() => setIds(chosen.filter((c) => c !== id))}
+          >
+            ×
+          </button>
+        </span>
+      ))}
+      <select
+        className="cg-select cg-cond-val cg-cond-cohort-add"
+        value=""
+        aria-label="Cohort"
+        disabled={!canAdd}
+        onChange={(e) => e.target.value && setIds([...chosen, e.target.value])}
+      >
+        {/* "nothing left to add" rendered as "nothing left to ad…" at 136px — the fourth time a
+            closed vocabulary has outgrown its control here. Shortened, not widened: the control
+            is sized so a COHORT NAME stays readable, and that is the string that matters. */}
+        <option value="">
+          {!canAdd ? "all added" : chosen.length ? "Add a cohort…" : "Select a cohort…"}
+        </option>
+        {remaining.map((l) => (
+          <option key={l.id} value={l.id}>
+            {l.name}
+          </option>
+        ))}
+      </select>
+    </span>
+  );
+}
+
+// --- Filter: an Airtable-style RECURSIVE condition builder -----------------
+// Anatomy per Airtable (captured from the live product 2026-07-25):
+//   row 0    : static "Where"
+//   row 1    : the and/or DROPDOWN — one conjunction per LEVEL, not per condition
+//   row 2..n : static text mirroring that level's conjunction
+//   a group  : inset panel + summary line ("All/Any of the following are true…")
+//              carrying its OWN conjunction and its own Where/and-or rows
+// Nesting is capped at MAX_FILTER_DEPTH (3) — Airtable grays the group button out.
+
+/** The leading cell of a condition row: "Where", the conjunction picker, or the mirror. */
+function RowPrefix({
+  index,
+  conj,
+  onConj,
+}: {
+  index: number;
+  conj: Conjunction;
+  onConj: (c: Conjunction) => void;
+}) {
+  if (index === 0) return <span className="cg-cond-prefix">Where</span>;
+  if (index === 1)
+    return (
+      <select
+        className="cg-select cg-cond-conj"
+        value={conj}
+        aria-label="Combine conditions with"
+        onChange={(e) => onConj(e.target.value as Conjunction)}
+      >
+        <option value="and">and</option>
+        <option value="or">or</option>
+      </select>
+    );
+  return <span className="cg-cond-prefix cg-cond-conj-echo">{conj}</span>;
+}
+
+/** Everything a level of the tree needs that does not change as it recurses. One object rather
+ *  than eight repeated props: the list grew past the point where each level restating it made
+ *  the recursion easier to read. */
+interface LevelContext {
+  fields: Field[];
+  fieldByKey: Map<string, Field>;
+  measures: Measure[];
+  measureByKey: Map<string, Measure>;
+  /** Cohorts this user has — the vocabulary of `Where [Cohort] [is part of] […]`. */
+  lists: { id: string; name: string }[];
+  choicesFor: ChoicesFor;
+}
+
+/**
+ * One nesting level: renders its nodes (leaves and nested groups) plus the
+ * add-buttons. Recurses through GroupNode for children that are groups.
+ */
+function ConditionLevel({
+  nodes,
+  conj,
+  depth,
+  ctx,
+  onNodes,
+  onConj,
+}: {
+  nodes: FilterNode[];
+  conj: Conjunction;
+  /** 1 = the root level. A new group's depth would be depth + 1. */
+  depth: number;
+  ctx: LevelContext;
+  onNodes: (nodes: FilterNode[]) => void;
+  onConj: (c: Conjunction) => void;
+}) {
+  /** Item 13 / R9 — which add-link was last used at THIS level. Per level, because the state
+   *  belongs to the row of buttons the user clicked, not to the builder as a whole. */
+  const [lastAdd, setLastAdd] = useState<"condition" | "group" | null>(null);
+  const setNode = (i: number, next: FilterNode) =>
+    onNodes(nodes.map((n, j) => (j === i ? next : n)));
+  const removeNode = (i: number) => onNodes(nodes.filter((_, j) => j !== i));
+
+  const addCondition = () => {
+    const c = newCondition(ctx.fields);
+    if (c) onNodes([...nodes, c]);
+  };
+  // New groups default to "or" — matching Airtable, and the useful case (the
+  // root ANDs a set of alternatives together).
+  const addGroup = () => {
+    const c = newCondition(ctx.fields);
+    if (c) onNodes([...nodes, { conj: "or", children: [c] }]);
+  };
+  const canNest = depth < MAX_FILTER_DEPTH;
+
+  return (
+    <>
+      {nodes.map((node, i) => (
+        <div className="cg-cond-line" key={i}>
+          <RowPrefix index={i} conj={conj} onConj={onConj} />
+          {isFilterGroup(node) ? (
+            <GroupNode
+              group={node}
+              depth={depth + 1}
+              ctx={ctx}
+              onGroup={(g) => setNode(i, g)}
+              onRemove={() => removeNode(i)}
+            />
+          ) : (
+            <LeafRow
+              rule={node}
+              ctx={ctx}
+              onRule={(r) => setNode(i, r)}
+              onRemove={() => removeNode(i)}
+            />
+          )}
+        </div>
+      ))}
+      {/* Item 13 (owner, 2026-08-02) — the two add-links are BOLD, and the one you just used
+          holds a dark-blue state.
+          ⚠ R9 says that state lasts while the popover is open and a fresh open starts
+          neutral — which is exactly what a `useState` HERE gives for free, because `Popover`
+          renders its children only while open (`{open && <AnchoredOverlay…>}`) and unmounts
+          them on close. Nothing persists it, nothing has to clear it, and there is no way for
+          it to survive a reopen. A `:active` pseudo-class would have been the wrong tool
+          twice over: it lasts for the duration of the mouse-down, and it says "you are
+          pressing this" rather than "this is the one you have been using". */}
+      <div className="cg-builder-add">
+        <button
+          type="button"
+          className={"cg-link-btn" + (lastAdd === "condition" ? " is-on" : "")}
+          onClick={() => {
+            setLastAdd("condition");
+            addCondition();
+          }}
+        >
+          + Add condition
+        </button>
+        <button
+          type="button"
+          className={"cg-link-btn" + (lastAdd === "group" ? " is-on" : "")}
+          onClick={() => {
+            setLastAdd("group");
+            addGroup();
+          }}
+          disabled={!canNest}
+          title={
+            canNest
+              ? "Group conditions so they evaluate together"
+              : `Condition groups can nest ${MAX_FILTER_DEPTH} levels deep`
+          }
+        >
+          + Add condition group
+        </button>
+      </div>
+    </>
+  );
+}
+
+/**
+ * One leaf condition: field ▾ | (window ▾) | operator ▾ | value | remove.
+ *
+ * The window bracket appears only for a MEASURE (CG-8) — a column already has its window baked
+ * in ("YTD $" IS year-to-date), and offering one there would imply it could be changed.
+ */
+function LeafRow({
+  rule,
+  ctx,
+  onRule,
+  onRemove,
+}: {
+  rule: FilterRule;
+  ctx: LevelContext;
+  onRule: (r: FilterRule) => void;
+  onRemove: () => void;
+}) {
+  const { fields, fieldByKey, measures, measureByKey, lists, choicesFor } = ctx;
+  const isMeasure = isMeasureRule(rule);
+  const isCohort = rule.colId === COHORT_FIELD;
+  const hasCohorts = lists.length > 0;
+  const t = isMeasure
+    ? measureByKey.get(rule.colId)?.type ?? "currency"
+    : fieldByKey.get(rule.colId)?.type ?? "text";
+  const patch = (p: Partial<FilterRule>) => onRule({ ...rule, ...p });
+  // Switching field resets op to that type's default + clears the value(s), so a
+  // numeric op can never linger on a text column. Crossing the column/measure line also
+  // adds or removes the WINDOW and the rule ID, since those are what MAKE it a measure —
+  // leaving a window behind on a column condition would keep the server answering it. The
+  // rhs goes too: a comparand chosen for the old field is meaningless against the new one.
+  const onField = (key: string) => {
+    if (key === COHORT_FIELD) {
+      onRule({ colId: COHORT_FIELD, op: COHORT_OP_LIST[0], value: "" });
+      return;
+    }
+    const m = measureByKey.get(key);
+    if (m) {
+      onRule({
+        id: rule.id ?? newRuleId(),
+        colId: key,
+        op: MEASURE_OP_LIST[0],
+        value: "",
+        value2: undefined,
+        window: rule.window ?? DEFAULT_WINDOW,
+      });
+      return;
+    }
+    const nt = fieldByKey.get(key)?.type ?? "text";
+    onRule({ colId: key, op: opsForType(nt)[0], value: "", value2: undefined });
+  };
+  // Switching to/from a value-free op clears the stale value it can't show. `within` swaps the
+  // value for a RANGE and drops any field comparand, since a range has no other side.
+  const onOp = (op: FilterOp | CohortOp) => {
+    // A cohort keeps its SET when the set operator changes — "any of these three" and "none of
+    // these three" are the same three cohorts asked about differently, and clearing them would
+    // make the obvious edit destructive.
+    if (isCohort) return patch({ op });
+    // C-OPS: a rank op arrives with its N already chosen (see rankDefault) and drops every
+    // comparand — "the top 10 compared with another field" is not a question.
+    if (isRankOp(op as string))
+      return onRule({ ...rule, op: op as FilterOp, value: rankDefault(op as FilterOp),
+                      value2: undefined, rhs: undefined, dateWindow: undefined });
+    if (VALUE_FREE_OPS.has(op as FilterOp))
+      return onRule({ ...rule, op, value: "", value2: undefined, rhs: undefined });
+    if (op === "within")
+      return onRule({ ...rule, op, value: "", value2: undefined, rhs: undefined,
+                      dateWindow: rule.dateWindow ?? DEFAULT_DATE_WINDOW });
+    if (rule.op === "within")
+      return onRule({ ...rule, op, dateWindow: undefined, value: "" });
+    patch({ op });
+  };
+  // Owner item 4: the value box is REPLACEABLE by another attribute. Offered where a
+  // comparison between two of the same kind of thing means something — numbers against
+  // numbers, dates against dates, a measure against a measure over its own period.
+  const rhsOptions: FieldSelectItem[] = isMeasure
+    ? measures.map((m) => ({ key: m.key, label: m.label, type: MEASURE_MARK }))
+    : fields
+        .filter((f) => f.key !== rule.colId
+          && (isNumericType(t) ? isNumericType(f.type) : f.type === t))
+        .map((f) => ({ key: f.key, label: f.label, type: f.type }));
+  const canCompareField = !isCohort && rule.op !== "within"
+    && !VALUE_FREE_OPS.has(rule.op as FilterOp) && !isRankOp(rule.op)
+    && rhsOptions.length > 0 && (isMeasure || isNumericType(t) || isDateFamily(t));
+  const usingStat = rule.rhs?.kind === "stat";
+  const usingField = rule.rhs != null && !usingStat;
+  // Explicitly widened: the cohort branch contributes a DISJOINT vocabulary, and without the
+  // annotation `withCurrent`'s `T extends string` infers from the first branch alone.
+  const opList: (FilterOp | CohortOp)[] = isMeasure
+    ? (usingField || usingStat ? MEASURE_PAIR_OP_LIST : MEASURE_OP_LIST)
+    : isCohort ? COHORT_OP_LIST : opsForType(t);
+  const opValue: FilterOp | CohortOp = isCohort ? normalizeCohortOp(rule.op) : rule.op;
+  // C-OPS — the RANK family, offered under its own divider for the numeric family only.
+  //
+  // A COLUMN only: a measure leaf is answered by a server-side pid set over a window, so
+  // ranking one client-side would be a second answer to the same question (and the host's
+  // MEASURE_OPS deliberately does not carry these). A cohort leaf is set membership.
+  //
+  // Offered separately rather than appended to `opsForType` because these operators are a
+  // different KIND of question — every other one is about this row's value, these are about
+  // where the row sits among the others — and a divider is the cheapest way to say so.
+  const canRank = !isMeasure && !isCohort && isNumericType(t);
+  // `withCurrent` runs over the COMBINED offer so a rule already holding a rank op is not
+  // appended a second time; the split below then puts each op under the right heading. A
+  // rank op on a field that can no longer be ranked still renders — as itself, in the group,
+  // which is what lets somebody see it and change it.
+  const offeredOps = withCurrent(canRank ? [...opList, ...RANK_OPS] : opList, opValue);
+  const plainOps = offeredOps.filter((op) => !isRankOp(op));
+  const rankedOps = offeredOps.filter((op) => isRankOp(op));
+
+  return (
+    <span className={"cg-cond-row" + (isMeasure ? " is-measure" : "")
+                     + (isCohort ? " is-cohort" : "")
+                     + (rule.rhs != null ? " has-rhs" : "")}>
+      {/* ONE flat list (owner item 1). A measure used to sit under a "Measures (pick a
+          period)" optgroup; the owner's instruction was that it is all the same list —
+          you pick a thing to filter on, and a measure simply also asks for a period. Item 20
+          adds the type MARK to each row and takes NO grouping with it: the marks are what the
+          optgroup was reaching for, and they say it per row instead of splitting the list. */}
+      <FieldSelectButton
+        className="cg-cond-field"
+        ariaLabel="Field"
+        value={rule.colId}
+        onChange={onField}
+        fields={[
+          ...withCurrentField(fields, rule.colId, fieldByKey, measureByKey, hasCohorts),
+          ...measures.map((m) => ({ key: m.key, label: m.label, type: MEASURE_MARK })),
+          // A cohort leaf asks about membership of a SET, which is the multiselect mark's
+          // own meaning — the vocabulary already had the right glyph for it.
+          ...(hasCohorts
+            ? [{ key: COHORT_FIELD, label: "Cohort", type: "multiselect" as const }]
+            : []),
+        ]}
+      />
+      {isMeasure && (
+        <WindowPicker
+          window={rule.window ?? DEFAULT_WINDOW}
+          onWindow={(w) => patch({ window: w })}
+        />
+      )}
+      <select
+        className="cg-select cg-cond-op"
+        // A view saved before 2026-07-27 holds `eq`/`neq`. Normalising HERE, rather than letting
+        // `withCurrent` append it, is the difference between a legacy rule reading "is any of"
+        // once and the list carrying two options with the same label and different values. The
+        // display stays truthful either way — `eq` IS `anyOf` — and the first edit writes the
+        // new op, matching what the validator already does on the server.
+        value={opValue}
+        aria-label="Condition"
+        onChange={(e) => onOp(e.target.value as FilterOp | CohortOp)}
+      >
+        {plainOps.map((op) => (
+          <option key={op} value={op}>
+            {/* `op as FilterOp` is safe by construction, not by hope: `opList` is the cohort
+                vocabulary EXACTLY when `isCohort`, so the other branch only ever sees the
+                column/measure one. The two lists are disjoint, so a wrong cast would show as a
+                raw key ("anyOf") on screen rather than as a plausible label. */}
+            {isCohort ? cohortOpLabel(op) : opLabel(op as FilterOp, t)}
+          </option>
+        ))}
+        {rankedOps.length > 0 && (
+          <optgroup label="Ranked">
+            {rankedOps.map((op) => (
+              <option key={op} value={op}>
+                {opLabel(op as FilterOp, t)}
+              </option>
+            ))}
+          </optgroup>
+        )}
+      </select>
+      {canCompareField && (
+        // The switch between "a value I type" and "another attribute". Two options rather than
+        // a checkbox, because the row already reads as a sentence and this is the noun slot.
+        <select
+          className="cg-select cg-cond-mode"
+          value={usingStat ? "stat" : usingField ? "field" : "value"}
+          aria-label="Compare against"
+          onChange={(e) => {
+            const mode = e.target.value;
+            if (mode === "stat")
+              return patch({ rhs: { kind: "stat", stat: "median" },
+                             value: "", value2: undefined,
+                             // a statistic is a computed cut-off: the same four ops a
+                             // measure-vs-measure allows, for the same float reason
+                             // reachable only via `canCompareField`, which excludes a cohort
+                             op: MEASURE_PAIR_OP_LIST.includes(rule.op as FilterOp)
+                               ? rule.op : MEASURE_PAIR_OP_LIST[1] });
+            if (mode === "field") {
+              // An EMPTY comparand: incomplete, so the rule stays inactive until a field is
+              // picked. RhsPicker adds the window when the measure side gets one.
+              const empty: FilterRhs = isMeasure
+                ? { kind: "measure", colId: "", window: DEFAULT_WINDOW }
+                : { kind: "field", colId: "" };
+              return patch({ rhs: empty, value: "", value2: undefined });
+            }
+            patch({ rhs: undefined, value: "" });
+          }}
+        >
+          <option value="value">a value</option>
+          <option value="field">another field</option>
+          {/* Statistics are computed SERVER-SIDE over the caller's pool, so they are offered
+              for a MEASURE only. A column statistic would need a second percentile
+              implementation on the client and the lock-step gate that goes with it. */}
+          {isMeasure && <option value="stat">a statistic</option>}
+        </select>
+      )}
+      {/* value-free ops render NO value control (Airtable does the same) */}
+      {VALUE_FREE_OPS.has(rule.op as FilterOp) ? (
+        <span className="cg-cond-val cg-cond-noval" aria-hidden />
+      ) : usingStat ? (
+        <select
+          className="cg-select cg-cond-val cg-cond-stat"
+          value={rule.rhs?.kind === "stat" ? rule.rhs.stat : "median"}
+          aria-label="Statistic"
+          onChange={(e) => patch({ rhs: { kind: "stat", stat: e.target.value as StatKind } })}
+        >
+          {STAT_KINDS.map((k) => (
+            <option key={k} value={k}>
+              {STAT_LABELS[k]}
+            </option>
+          ))}
+        </select>
+      ) : usingField ? (
+        <RhsPicker rule={rule} options={rhsOptions} isMeasure={isMeasure} onPatch={patch} />
+      ) : isCohort ? (
+        <CohortPicker rule={rule} lists={lists} onPatch={patch} />
+      ) : isRankOp(rule.op) ? (
+        <RankValue rule={rule} onValue={(v) => patch({ value: v })} />
+      ) : rule.op === "within" ? (
+        <WindowPicker
+          window={rule.dateWindow ?? DEFAULT_DATE_WINDOW}
+          onWindow={(w) => patch({ dateWindow: w })}
+          kinds={WITHIN_KINDS}
+        />
+      ) : isDateFamily(t) ? (
+        <AnchorValue rule={rule} onPatch={patch} />
+      ) : (
+        <ConditionValue
+          rule={rule}
+          type={t}
+          statusOptions={choicesFor(rule.colId)}
+          onValue={(v) => patch({ value: v })}
+          onValue2={(v) => patch({ value2: v })}
+        />
+      )}
+      <button
+        type="button"
+        className="cg-cond-x"
+        aria-label="Remove condition"
+        onClick={onRemove}
+      >
+        ×
+      </button>
+    </span>
+  );
+}
+
+/** A nested condition group: summary line + its own recursive level. */
+function GroupNode({
+  group,
+  depth,
+  ctx,
+  onGroup,
+  onRemove,
+}: {
+  group: FilterGroup;
+  depth: number;
+  ctx: LevelContext;
+  onGroup: (g: FilterGroup) => void;
+  onRemove: () => void;
+}) {
+  return (
+    <span className="cg-cond-group" data-depth={depth}>
+      <span className="cg-cond-group-head">
+        <span className="cg-cond-group-sum">
+          {group.children.length
+            ? groupSummary(group.conj)
+            : "Add a condition to this group…"}
+        </span>
+        <button
+          type="button"
+          className="cg-cond-x"
+          aria-label="Remove condition group"
+          onClick={onRemove}
+        >
+          ×
+        </button>
+      </span>
+      <span className="cg-cond-group-body">
+        <ConditionLevel
+          nodes={group.children}
+          conj={group.conj}
+          depth={depth}
+          ctx={ctx}
+          onNodes={(children) => onGroup({ ...group, children })}
+          onConj={(conj) => onGroup({ ...group, conj })}
+        />
+      </span>
+    </span>
+  );
+}
+
+export interface FilterBuilderPanelProps {
+  /**
+   * The module's COMPLETE field list. The panel offers the FILTERABLE ones
+   * (`filterableFields`) and resolves labels from all of them — a condition saved against a
+   * column that has since stopped being filterable must still render its own name rather than
+   * turning into "?", so narrowing the picker may never orphan history.
+   */
+  fields: Field[];
+  /** The whole filter as ONE value — nodes plus the root conjunction. See types.FilterTree. */
+  filters: FilterTree;
+  onChange: (next: FilterTree) => void;
+  /** Cohorts the subject of this filter has, for `Where [Cohort] [is any of] […]`. */
+  cohorts?: { id: string; name: string }[];
+  /** CG-8 — measures the builder may offer alongside the columns. Absent = columns only. */
+  measures?: Measure[];
+  /** The people a `user` field may name. Never invented here — the host's real user list. */
+  userOptions?: string[];
+  /**
+   * The tenant's today, ISO. RESERVED: it is the anchor a relative window resolves against,
+   * and it is accepted so a caller that holds it (the grid, the admin editor) has one obvious
+   * place to put it. It renders NOTHING today — a "this resolves to <range>" hint under the
+   * date controls was considered for wave 15 and rejected as a visual delta C-KIT forbids.
+   * Kept in the signature rather than added later so no call site has to change to gain it.
+   */
+  today?: string;
+  /**
+   * The per-field CHOICE VOCABULARY, by field key. The one prop that is not cosmetic when it
+   * is absent: some columns take their values from the DATA (the grid discovers them from its
+   * rows — `customer-grid/types.ts::choiceVocabulary`), which a panel over a module whose rows
+   * it has never loaded cannot do. Absent, choices fall back to the field's own declared
+   * `options` and, for `user`, to `userOptions`.
+   *
+   * ⛔ **Which columns those are is NOT decided by the type, and the old wording here saying
+   * "only Odoo `status` columns come up empty" was wrong in a way that shipped a live defect**
+   * (owner item 24, 2026-08-06). `stock_bucket` on the Product grid is declared `select` and
+   * declares no `options` — its vocabulary is computed server-side and rides the rows, exactly
+   * like a `status` column's. **Any column with no declared `options` needs this prop**, whatever
+   * its type says. A host that cannot enumerate one renders an empty picker; see `choicesFor`.
+   */
+  statusValues?: Record<string, string[]>;
+  /**
+   * Item 12 (C-LOCK) — this view is LOCKED to a cohort. Present = say so, because the lock
+   * narrows the list and is not one of the conditions shown here: without the banner the count
+   * and the conditions disagree with no visible reason.
+   *
+   * `name`/`count` ABSENT means the reader cannot see the set — a shared view locked to
+   * somebody else's cohort. The engine matches nothing in that case (fail-closed, the
+   * cohort-leaf law), so the banner has to say which kind of nothing this is.
+   */
+  cohortLock?: { name?: string; count?: number };
+  /**
+   * Extra footer content, rendered beside "Clear all" — the grid puts its "Copy from another
+   * view" door here. A SLOT rather than props, exactly like the toolbar's `cohortAction`: the
+   * door needs the other views and the view-patch plumbing, none of which a panel that also
+   * serves an admin editor should know about.
+   */
+  footerExtra?: ReactNode;
+}
+
+export function FilterBuilderPanel({
+  fields,
+  filters,
+  onChange,
+  cohorts = [],
+  measures = [],
+  userOptions,
+  statusValues,
+  cohortLock,
+  footerExtra,
+}: FilterBuilderPanelProps) {
+  const nodes = filterTreeNodes(filters);
+  const conj = filterTreeConj(filters);
+  // The COMPLETE map on purpose (see `fields` above): the picker is narrowed, the label
+  // resolution is not.
+  const fieldByKey = useMemo(() => {
+    const m = new Map<string, Field>();
+    for (const f of fields) m.set(f.key, f);
+    return m;
+  }, [fields]);
+  const condFields = useMemo(() => filterableFields(fields), [fields]);
+  const measureByKey = useMemo(() => {
+    const m = new Map<string, Measure>();
+    for (const item of measures) m.set(item.key, item);
+    return m;
+  }, [measures]);
+  const choicesFor = useCallback<ChoicesFor>(
+    (colId) => {
+      // A supplied map WINS, including when it holds an empty list: "this status column has no
+      // values in the data" is an answer, not a missing one.
+      const declared = statusValues?.[colId];
+      if (declared) return declared;
+      const f = fieldByKey.get(colId);
+      if (!f) return [];
+      return f.type === "user" ? userOptions ?? [] : choiceOptions(f);
+    },
+    [statusValues, fieldByKey, userOptions]
+  );
+  const ctx = useMemo<LevelContext>(
+    () => ({ fields: condFields, fieldByKey, measures, measureByKey, lists: cohorts,
+             choicesFor }),
+    [condFields, fieldByKey, measures, measureByKey, cohorts, choicesFor]
+  );
+
+  return (
+    <div className="cg-pop-body cg-builder">
+      <div className="cg-pop-title">Filter</div>
+      {/* C-LOCK (item 12) — the lock is NOT a condition row: it cannot be written here and
+          cannot be removed here (the view menu owns it). So it has to be SAID here, above
+          the conditions it bounds — otherwise the count and the conditions disagree and the
+          builder shows nothing that explains the gap. A reader who cannot see the set gets a
+          different sentence, because the engine shows them nobody and "no records" alone does
+          not distinguish a permission wall from a filter that genuinely matches nobody. */}
+      {cohortLock && (
+        <div className="cg-flt-lockchip">
+          {cohortLock.name
+            ? `Customer list locked to ${cohortLock.name}` +
+              (typeof cohortLock.count === "number"
+                ? ` · ${cohortLock.count.toLocaleString()} ${
+                    cohortLock.count === 1 ? "customer" : "customers"
+                  }`
+                : "")
+            : "Customer list locked to a set you cannot see"}
+        </div>
+      )}
+      {nodes.length === 0 ? (
+        <div className="cg-builder-empty">
+          No conditions. Add one to narrow the list.
+        </div>
+      ) : (
+        <div className="cg-builder-caption">In this view, show records</div>
+      )}
+      <ConditionLevel
+        nodes={nodes}
+        conj={conj}
+        depth={1}
+        ctx={ctx}
+        onNodes={(next) => onChange({ conj, nodes: next })}
+        onConj={(next) => onChange({ conj: next, nodes })}
+      />
+      {/* ⛔⛔ THE RANK EXPLAINER WAS HERE AND IS DELETED (WAVE 34, R5). Owner, 2026-08-16:
+          *"Remove this stupid fucking explainer in our filter function… for our view why does it
+          show in the filter??"*
+
+          It was three sentences shown whenever a rank/quartile/decile condition entered the tree,
+          and the argument for it was not silly: a ranked condition genuinely answers a question
+          about the OTHER records, and nothing in the row says which others. What that argument
+          missed is that `DESIGN.md` §4's "never over-explain" law is not a style preference — a
+          paragraph that appears inside a control, every time you use that control, is read once
+          and then becomes furniture you have to look past forever. The person configuring a top-10
+          filter is not reading a tutorial; they are three clicks into a task.
+
+          ⚠ NOTHING WAS REPLACED WITH A TOOLTIP, and that is deliberate rather than an omission.
+          A tooltip here would be the same prose behind one more interaction, which is how "we
+          removed it" turns into "we hid it" — and the owner would find it again.
+
+          ⭐ The facts it carried are still TRUE and still matter (ranking is over the records the
+          other conditions keep; blanks are not ranked; quantiles are equal-size BY RANK, so two
+          identical values can land on opposite sides of a boundary). They belong in the docs, not
+          in the panel.
+
+          ⚠ AND `hasRankCondition` WENT WITH IT, WHICH THIS COMMENT INITIALLY GOT WRONG. The first
+          draft of this note said the predicate "KEEPS its other callers in `ops.ts`". It had none:
+          `tsc` (TS6133) named the import unread the moment the paragraph went, and a grep then
+          showed the only remaining reference was its OWN recursion. Deleted in the same edit, as
+          this comment's own rule demanded. Second time in one session that a confident claim about
+          who calls a symbol was refuted by the compiler within a minute. */}
+      {/* The footer carries "Clear all" (only when there is something to clear) and whatever
+          door the host mounts in `footerExtra`.
+          ⚠ The door is in the FOOTER rather than beside the add-links, where the reference
+          screenshot has it, for one structural reason: `.cg-builder-add` is emitted once per
+          NESTING LEVEL, so a link there would repeat inside every condition group and offer
+          to overwrite the whole view from inside one of its brackets. The footer is the one
+          place in this popover that means "the view", which is what the copy acts on. It is
+          also offered when there are NO conditions yet, which is when somebody most wants to
+          start from another view. */}
+      {(nodes.length > 0 || footerExtra) && (
+        <div className="cg-pop-footer cg-builder-footer">
+          {nodes.length > 0 && (
+            <button
+              type="button"
+              className="cg-link-btn"
+              onClick={() => onChange({ conj, nodes: [] })}
+            >
+              Clear all
+            </button>
+          )}
+          {footerExtra}
+        </div>
+      )}
+    </div>
+  );
+}

web/src/filter-kit/ops.ts

@@ -1,400 +1,400 @@
-// ---------------------------------------------------------------------------
-// filter-kit / ops.ts
-// The filter/sort operator VOCABULARY — which operators each field type offers,
-// and how each one reads to a human.
-//
-// Extracted verbatim from customer-grid/Toolbar.tsx (wave 15, contract C-KIT) so
-// the permission editor and the grid toolbar offer ONE vocabulary rather than two
-// that drift. The matching engine (matchFilter/makeComparator in useVisibleRows)
-// and its Python mirrors (filter_sql.py, filter_eval.py) are the other halves of
-// the same contract; these are only the labels the popovers render.
-// ---------------------------------------------------------------------------
-
-import type {
-  Conjunction,
-  Field,
-  FieldType,
-  FilterNode,
-  FilterOp,
-  FilterRule,
-  Measure,
-} from "../customer-grid/types";
-import {
-  COHORT_FIELD, COHORT_OPS, MEASURE_OPS, MEASURE_PAIR_OPS, isFilterGroup,
-  isDateFamilyType, isMeasureRule, isNumericFieldType, isRankOp, normalizeCohortOp,
-} from "../customer-grid/types";
-import type { CohortOp } from "../customer-grid/types";
-import type { FieldSelectItem, FieldSelectType } from "../customer-grid/FieldSelect";
-import type { WindowKind, WindowSpec } from "../customer-grid/windows";
-
-// The type families live in types.ts (ONE definition for every UI surface); the engine keeps
-// its own deliberately self-contained copies — see isNumericFieldType's doc.
-export const isNumericType = isNumericFieldType;
-export const isDateFamily = isDateFamilyType;
-
-/**
- * Operators offered for a field type (first = the default for new conditions).
- * Mirrors Airtable's own per-type sets, verified against the live product
- * (2026-07-25): a text field offers exactly contains / does not contain / is /
- * is not / is empty / is not empty. Every type ends with the two value-free ops.
- *
- * NOTE on isEmpty over the Customer List contract: several Odoo-derived money
- * columns (revenue_ytd, revenue_ly, at_risk, ltm_rev, orders_24m, est_missed) are
- * built with 0.0/0 defaults in customer_list.pool(), so "is empty" correctly
- * matches NOTHING there — 0 is a real value, not a blank. The columns where it
- * genuinely bites are last_order (''), days_since, typical_gap_days, yoy_pct, and
- * every overlay field (notes / custom) — "customers with no notes yet" is the
- * common case. Offered on all types anyway, exactly as Airtable does.
- *
- * ⚠ AND the SENTINEL columns, which are a third case and the one that surprises:
- * agent · city · state · country · zip · payment_terms · pricelist · tags all
- * collapse a blank to the STRING '(none)' in `_partner_attrs`, so grouping has no
- * null bucket. `isEmpty` tests `value === ""`, so on these it matches nothing even
- * though 76 customers have no country and 79 no zip — the blanks are found with
- * `is` `(none)`, which is also what the cell visibly says. Each of those fields
- * carries that sentence as its column `note`, because a source comment is not
- * where the person filtering is looking. DATE attributes keep '' instead
- * (customer_since, last_order): '(none)' in a date column would sort and compare
- * as text against ISO dates.
- */
-export function opsForType(t: FieldType): FilterOp[] {
-  // Wave-5: a checkbox stores '1' or blank, so "is checked" IS `isNotEmpty` and "is
-  // unchecked" IS `isEmpty` — the honest mapping onto the existing vocabulary (no new
-  // FilterOp, the filter_sql lock-step untouched). Both are value-free, so no value control
-  // renders. First = the default: "is checked".
-  if (t === "checkbox") return ["isNotEmpty", "isEmpty"];
-  if (isNumericType(t))
-    return ["gte", "gt", "lte", "lt", "eq", "neq", "between", "isEmpty", "isNotEmpty"];
-  if (isDateFamily(t))
-    // Owner item 3, in the order they asked for it. `between` is GONE from the offer — "is
-    // within" plus a custom range says the same thing and reads better — but it stays in the
-    // ENGINE, because saved views hold it. `legacyOps` below is what keeps such a view
-    // rendering its own operator instead of silently showing the first one in this list.
-    return ["eq", "within", "lt", "gt", "lte", "gte", "neq", "isEmpty", "isNotEmpty"];
-  // `select` and `user` are picked from a fixed list, so they behave like `status`: is / is
-  // not / empty. `contains` on a chosen value is a substring test against a closed vocabulary —
-  // it would find "Done" inside "Not done" and read as a bug.
-  if (t === "status" || t === "select" || t === "user")
-    return ["eq", "neq", "isEmpty", "isNotEmpty"];
-  // A `multiselect` cell is a comma-joined SET, so the useful question is membership — "has" —
-  // which is the EXISTING `contains` op over the joined string (no new engine vocabulary; the
-  // ops are mirrored in filter_sql.py and inventing one here would break the lock-step). The
-  // value is still picked from the declared options, so the substring caveat above is bounded
-  // by the user's own choice list. `eq` reads "is exactly": the whole set is that one choice.
-  if (t === "multiselect")
-    return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"];
-  // ⭐ Wave-23 C7 — `json` gets EXACTLY the two value-free ops, and the omissions are the
-  // decision. `contains` over a serialized document is a substring test against punctuation and
-  // key names: `contains "12"` would match a key `id_12`, a value 12, a timestamp and a
-  // fragment of 5120, and every one of those reads as a working filter. `eq` is worse — two
-  // documents that mean the same thing differ by key order and whitespace, so "is" would answer
-  // false for a record that plainly matches. "Has anything been captured here yet" is the
-  // question a json column can answer soundly, and it is the one people actually ask.
-  //
-  // ⚠ NO NEW OPERATOR ENTERS EITHER ENGINE. `isEmpty`/`isNotEmpty` already exist in
-  // `filter_sql.py` (:76, and :112's VALUE_FREE_OPS) and `filter_eval.py` (:260-262), and both
-  // are TYPE-INDEPENDENT — they test blankness before any type dispatch — so the lock-step is
-  // untouched and nothing on the server had to move for this line. (The contract's prose spells
-  // them `is_empty`/`is_not_empty`; the runtimes do not. The names come from the code.)
-  if (t === "json") return ["isNotEmpty", "isEmpty"];
-  // Wave-18 C5-AUTOFIELD — `automation` lands HERE, on the text ops, and that is the whole
-  // v1 answer. Its cell is one machine-written line (`ok · 2026-08-03 14:10 · 12 posts`), so
-  // `contains ok` and `contains error` are the two questions anyone actually asks of the
-  // column, and both are already sound over a string. Nothing new enters the operator
-  // vocabulary, so the `filter_sql.py` lock-step is untouched — a new op for "state is" would
-  // have to be mirrored in the Python engine, and the substring answer is the same answer.
-  return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"]; // text
-}
-
-/**
- * C-OPS — the RANK operators, worded so the row still reads as a sentence.
- *
- * The unit lives in the OPERATOR, not beside the box: "top" followed by a bare 10 is ambiguous
- * between ten records and ten percent, so `top N` and `top N%` are two operators and the box
- * supplies N. The alternative — a "%" suffix element after the input — would put a second
- * thing in the value slot that every gate locating `.cg-cond-val` would have to know about.
- *
- * ⚠ AND THEY ARE SHORT ON PURPOSE. A 136px `.cg-select` has ~97.9px of readable width (see
- * `cohortOpLabel` below, and `withCurrentField` below) — about 15 characters of 12.5px Inter.
- * "is in the bottom N%" is 19 and would have shipped CLIPPED, which no assertion here can see
- * and no screenshot in this session could catch. Dropping the "is " costs nothing: the numeric
- * operators beside these are bare glyphs (`≥ > ≤ <`), so the row already reads without one,
- * and the `Ranked` divider carries the "these are a different kind of question" signal. Fifth
- * time this control has outgrown a label; the label gives way, never the control.
- */
-export const RANK_OP_LABELS: Record<string, string> = {
-  topN: "top N",
-  bottomN: "bottom N",
-  inTopPct: "top N%",
-  inBottomPct: "bottom N%",
-  aboveAvg: "above average",
-  belowAvg: "below average",
-  inQuartile: "in quartile",
-  inDecile: "in decile",
-};
-
-/**
- * The value a rank op starts at when it is chosen.
- *
- * Seeded rather than left blank, and this is a deliberate break from how the other operators
- * behave: a blank value makes a rule INACTIVE, so `is in the top N` with nothing typed would
- * sit in the builder narrowing nothing, and "the filter I just added does nothing" reads as a
- * broken control rather than as an unfinished sentence. Every rank op has an obvious default —
- * ten, or the top slice — so there is a right answer to seed. The two averages take none.
- */
-export function rankDefault(op: FilterOp): string {
-  switch (op) {
-    case "topN":
-    case "bottomN":
-    case "inTopPct":
-    case "inBottomPct":
-    case "inDecile":
-      return "10";
-    case "inQuartile":
-      return "4";
-    default:
-      return ""; // aboveAvg / belowAvg — value-free
-  }
-}
-
-/** Does this tree hold an ACTIVE-looking rank condition? Drives the builder's helper line —
- *  the semantics of a quantile are not guessable, so they are stated where they are chosen. */
-export function hasRankCondition(nodes: FilterNode[]): boolean {
-  for (const node of nodes ?? []) {
-    if (isFilterGroup(node)) {
-      if (hasRankCondition(node.children)) return true;
-      continue;
-    }
-    if (isRankOp(node.op) && !isMeasureRule(node)) return true;
-  }
-  return false;
-}
-
-/** Human label for an operator, read naturally per field type. */
-export function opLabel(op: FilterOp, t: FieldType): string {
-  // Rank first and type-independently: a rank op means the same thing on every numeric
-  // family, and a view whose column has since changed type must still SAY what it holds
-  // rather than falling through to a raw key.
-  if (isRankOp(op)) return RANK_OP_LABELS[op] ?? op;
-  // Checkbox first: its two value-free ops READ as states, not as blankness — the storage
-  // contract ('1' or blank) is an implementation detail the sentence must not leak.
-  if (t === "checkbox") {
-    if (op === "isNotEmpty") return "is checked";
-    if (op === "isEmpty") return "is unchecked";
-  }
-  // Type-independent: Airtable words these identically for every field type.
-  if (op === "isEmpty") return "is empty";
-  if (op === "isNotEmpty") return "is not empty";
-  if (isDateFamily(t)) {
-    switch (op) {
-      case "eq":
-        return "is";
-      case "neq":
-        return "is not";
-      case "within":
-        return "is within";
-      case "lt":
-        return "is before";
-      case "lte":
-        return "is on or before";
-      case "gt":
-        return "is after";
-      case "gte":
-        return "is on or after";
-      case "between":
-        return "is between";      // no longer offered; still rendered for a saved view
-    }
-  }
-  if (isNumericType(t)) {
-    switch (op) {
-      case "gte":
-        return "≥"; // ≥
-      case "gt":
-        return ">";
-      case "lte":
-        return "≤"; // ≤
-      case "lt":
-        return "<";
-      case "eq":
-        return "=";
-      case "neq":
-        return "≠"; // ≠
-      case "between":
-        return "is between";
-      default:
-        return op;
-    }
-  }
-  if (t === "multiselect") {
-    // Membership wording over the joined-set cell. "has" IS `contains` (see opsForType) — only
-    // the label changes, so the engine and its Python mirror stay untouched.
-    switch (op) {
-      case "contains":
-        return "has";
-      case "doesNotContain":
-        return "does not have";
-      case "eq":
-        return "is exactly";
-      case "neq":
-        return "is not exactly";
-      default:
-        return op;
-    }
-  }
-  // text / status. (Airtable suffixes value-taking ops with "…" in the OPEN
-  // dropdown only; a native <select> shows one string in both states, so we use
-  // the closed-state wording — which is what's on screen almost all the time.)
-  switch (op) {
-    case "contains":
-      return "contains";
-    case "doesNotContain":
-      return "does not contain";
-    case "eq":
-      return "is";
-    case "neq":
-      return "is not";
-    default:
-      return op;
-  }
-}
-
-/**
- * The offered list, PLUS whatever the rule is actually set to.
- *
- * A `<select>` whose `value` is not among its `<option>`s renders the FIRST option instead —
- * so a saved view holding a dropped operator (a date `between`) or a column that has since left
- * the filter list (`at_risk`, once its measure replacement shipped) would display something the
- * rule does not say, and the first edit would silently rewrite it to that. Painted, plausible,
- * and wrong: the class of failure a screenshot catches and an assertion does not.
- */
-export function withCurrent<T extends string>(offered: readonly T[], current: T | undefined): T[] {
-  return current && !offered.includes(current) ? [...offered, current] : [...offered];
-}
-
-/** A group's summary line, mirroring Airtable's wording. */
-export function groupSummary(conj: Conjunction): string {
-  return conj === "or"
-    ? "Any of the following are true…"
-    : "All of the following are true…";
-}
-
-/**
- * CG-8 — the operators a MEASURE condition may use, and why they are not `opsForType`.
- *
- * A measure is answered by a SQL `HAVING`, and `harness/measure_filter.OPS` has exactly six
- * comparisons. `between` would need two, and `isEmpty`/`isNotEmpty` have no meaning for a sum
- * that is defined to be 0 when there is nothing to add up — the resolver refuses all three by
- * name. Offering them here would produce a condition the server can only reject.
- *
- * The owner's "dates between X and Y" is the WINDOW's between, not the value's, and that is the
- * `custom` window kind — so nothing is lost.
- */
-export const MEASURE_OP_LIST: FilterOp[] = [...MEASURE_OPS];
-
-/** CG-9 — narrower still when the other side is a measure. `=` and `≠` between two sums of
- *  floats match nobody and everybody respectively; see types.ts MEASURE_PAIR_OPS. */
-export const MEASURE_PAIR_OP_LIST: FilterOp[] = [...MEASURE_PAIR_OPS];
-
-/**
- * A cohort condition names a SET of cohorts (owner, 2026-07-27), so its operators are set
- * operators. `eq`/`neq` are not offered — the validator rewrites them to `anyOf`/`noneOf`, and
- * `withCurrent` would otherwise show a legacy view an operator it can never choose again.
- */
-export const COHORT_OP_LIST: CohortOp[] = [...COHORT_OPS];
-
-/**
- * ⚠ "is part of any of" measures ~96px at 12.5px Inter against the 97.9px of readable width a
- * 136px select actually has (136 - 20.1 arrow - 16 padding - 2 border) — inside the box only
- * until a fallback font renders it. Airtable's own wording for a multi-select is shorter and
- * says the same thing, so the LABEL gives way, not the control. Third time this rule has been
- * applied; see the "(not filterable)" and "the 75th percentile" clippings before it.
- */
-export function cohortOpLabel(op: FilterOp | CohortOp): string {
-  switch (normalizeCohortOp(op)) {
-    case "allOf":
-      return "is all of";
-    case "noneOf":
-      return "is none of";
-    default:
-      return "is any of";
-  }
-}
-
-/** Item 20 — the mark a MEASURE row wears in every picker on this surface. Named once so the
- *  three lists that offer measures cannot drift into two different glyphs for one concept. */
-export const MEASURE_MARK: FieldSelectType = "measure";
-
-/** A measure condition is identified by its window, so a new one needs a default window. */
-export const DEFAULT_WINDOW: WindowSpec = { kind: "ltm" };
-
-/** The default RANGE for `is within` — the owner's first example ("the past month"). */
-export const DEFAULT_DATE_WINDOW: WindowSpec = { kind: "past_month" };
-
-/**
- * The ranges `is within` offers, in the owner's own order (item 3, 2026-07-26):
- * the past number of days · the past week · the past month · the past year · this calendar
- * week · this calendar month · this calendar year.
- *
- * Plus `custom`, which is not a nicety: dropping `between` from the date operators would
- * otherwise remove the ability to ask for two exact dates at all. The remaining kinds
- * (yesterday, last_quarter, ytd_last_year, the forward-looking ones…) stay available to a
- * MEASURE's window, where they make sense; "last order is within year to date, last year" is a
- * question nobody asks.
- */
-export const WITHIN_KINDS: WindowKind[] = [
-  "last_n_days", "past_week", "past_month", "past_year",
-  "this_week", "this_month", "this_year", "custom",
-];
-
-/**
- * The field dropdown's COLUMN half, plus the column the rule is actually set to if the picker
- * no longer offers it. See `withCurrent` — a select whose value is missing from its options
- * silently displays a different field than the rule holds. This is not hypothetical: the
- * shipped "Win-back" list filters `at_risk`, which left the filter list the day its measure
- * replacement arrived.
- */
-export function withCurrentField(
-  fields: Field[],
-  current: string,
-  fieldByKey: Map<string, Field>,
-  measureByKey: Map<string, Measure>,
-  hasCohorts: boolean
-): FieldSelectItem[] {
-  // Item 20: the rows carry their TYPE now, because the picker paints the type mark. Same
-  // list, same order, same `withCurrent` rule — only the shape of a row grew a field.
-  const out: FieldSelectItem[] = fields.map((f) => ({
-    key: f.key, label: f.label, type: f.type,
-  }));
-  const known = new Set(out.map((o) => o.key));
-  if (!current || known.has(current) || measureByKey.has(current)) return out;
-  if (current === COHORT_FIELD && hasCohorts) return out;
-  // The field's OWN label, with no "(not filterable)" annotation: the select is ~170px and the
-  // suffix CLIPPED to "At risk $ (not filter" — a truncated parenthetical reads as a rendering
-  // bug, and the property that matters is that the condition says what it says. Found by
-  // reading the screenshot; every assertion in the run was green.
-  const f = fieldByKey.get(current);
-  out.push({ key: current, label: f ? f.label : current, type: f?.type });
-  return out;
-}
-
-/** Ids only have to be unique within one view's tree; they never leave this browser's view. */
-let ruleSeq = 0;
-export function newRuleId(): string {
-  ruleSeq += 1;
-  return `r${Date.now().toString(36)}${ruleSeq.toString(36)}`;
-}
-
-/** A fresh leaf condition on the first available field. */
-export function newCondition(fields: Field[]): FilterRule | null {
-  const f0 = fields[0];
-  if (!f0) return null;
-  return { colId: f0.key, op: opsForType(f0.type)[0], value: "" };
-}
-
-/** Total LEAF conditions in a filter tree (groups contribute their contents). */
-export function countConditions(nodes: FilterNode[]): number {
-  let n = 0;
-  for (const node of nodes)
-    n += isFilterGroup(node) ? countConditions(node.children) : 1;
-  return n;
-}
+// ---------------------------------------------------------------------------
+// filter-kit / ops.ts
+// The filter/sort operator VOCABULARY — which operators each field type offers,
+// and how each one reads to a human.
+//
+// Extracted verbatim from customer-grid/Toolbar.tsx (wave 15, contract C-KIT) so
+// the permission editor and the grid toolbar offer ONE vocabulary rather than two
+// that drift. The matching engine (matchFilter/makeComparator in useVisibleRows)
+// and its Python mirrors (filter_sql.py, filter_eval.py) are the other halves of
+// the same contract; these are only the labels the popovers render.
+// ---------------------------------------------------------------------------
+
+import type {
+  Conjunction,
+  Field,
+  FieldType,
+  FilterNode,
+  FilterOp,
+  FilterRule,
+  Measure,
+} from "../customer-grid/types";
+import {
+  COHORT_FIELD, COHORT_OPS, MEASURE_OPS, MEASURE_PAIR_OPS, isFilterGroup,
+  isDateFamilyType, isNumericFieldType, isRankOp, normalizeCohortOp,
+} from "../customer-grid/types";
+import type { CohortOp } from "../customer-grid/types";
+import type { FieldSelectItem, FieldSelectType } from "../customer-grid/FieldSelect";
+import type { WindowKind, WindowSpec } from "../customer-grid/windows";
+
+// The type families live in types.ts (ONE definition for every UI surface); the engine keeps
+// its own deliberately self-contained copies — see isNumericFieldType's doc.
+export const isNumericType = isNumericFieldType;
+export const isDateFamily = isDateFamilyType;
+
+/**
+ * Operators offered for a field type (first = the default for new conditions).
+ * Mirrors Airtable's own per-type sets, verified against the live product
+ * (2026-07-25): a text field offers exactly contains / does not contain / is /
+ * is not / is empty / is not empty. Every type ends with the two value-free ops.
+ *
+ * NOTE on isEmpty over the Customer List contract: several Odoo-derived money
+ * columns (revenue_ytd, revenue_ly, at_risk, ltm_rev, orders_24m, est_missed) are
+ * built with 0.0/0 defaults in customer_list.pool(), so "is empty" correctly
+ * matches NOTHING there — 0 is a real value, not a blank. The columns where it
+ * genuinely bites are last_order (''), days_since, typical_gap_days, yoy_pct, and
+ * every overlay field (notes / custom) — "customers with no notes yet" is the
+ * common case. Offered on all types anyway, exactly as Airtable does.
+ *
+ * ⚠ AND the SENTINEL columns, which are a third case and the one that surprises:
+ * agent · city · state · country · zip · payment_terms · pricelist · tags all
+ * collapse a blank to the STRING '(none)' in `_partner_attrs`, so grouping has no
+ * null bucket. `isEmpty` tests `value === ""`, so on these it matches nothing even
+ * though 76 customers have no country and 79 no zip — the blanks are found with
+ * `is` `(none)`, which is also what the cell visibly says. Each of those fields
+ * carries that sentence as its column `note`, because a source comment is not
+ * where the person filtering is looking. DATE attributes keep '' instead
+ * (customer_since, last_order): '(none)' in a date column would sort and compare
+ * as text against ISO dates.
+ */
+export function opsForType(t: FieldType): FilterOp[] {
+  // Wave-5: a checkbox stores '1' or blank, so "is checked" IS `isNotEmpty` and "is
+  // unchecked" IS `isEmpty` — the honest mapping onto the existing vocabulary (no new
+  // FilterOp, the filter_sql lock-step untouched). Both are value-free, so no value control
+  // renders. First = the default: "is checked".
+  if (t === "checkbox") return ["isNotEmpty", "isEmpty"];
+  if (isNumericType(t))
+    return ["gte", "gt", "lte", "lt", "eq", "neq", "between", "isEmpty", "isNotEmpty"];
+  if (isDateFamily(t))
+    // Owner item 3, in the order they asked for it. `between` is GONE from the offer — "is
+    // within" plus a custom range says the same thing and reads better — but it stays in the
+    // ENGINE, because saved views hold it. `legacyOps` below is what keeps such a view
+    // rendering its own operator instead of silently showing the first one in this list.
+    return ["eq", "within", "lt", "gt", "lte", "gte", "neq", "isEmpty", "isNotEmpty"];
+  // `select` and `user` are picked from a fixed list, so they behave like `status`: is / is
+  // not / empty. `contains` on a chosen value is a substring test against a closed vocabulary —
+  // it would find "Done" inside "Not done" and read as a bug.
+  if (t === "status" || t === "select" || t === "user")
+    return ["eq", "neq", "isEmpty", "isNotEmpty"];
+  // A `multiselect` cell is a comma-joined SET, so the useful question is membership — "has" —
+  // which is the EXISTING `contains` op over the joined string (no new engine vocabulary; the
+  // ops are mirrored in filter_sql.py and inventing one here would break the lock-step). The
+  // value is still picked from the declared options, so the substring caveat above is bounded
+  // by the user's own choice list. `eq` reads "is exactly": the whole set is that one choice.
+  if (t === "multiselect")
+    return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"];
+  // ⭐ Wave-23 C7 — `json` gets EXACTLY the two value-free ops, and the omissions are the
+  // decision. `contains` over a serialized document is a substring test against punctuation and
+  // key names: `contains "12"` would match a key `id_12`, a value 12, a timestamp and a
+  // fragment of 5120, and every one of those reads as a working filter. `eq` is worse — two
+  // documents that mean the same thing differ by key order and whitespace, so "is" would answer
+  // false for a record that plainly matches. "Has anything been captured here yet" is the
+  // question a json column can answer soundly, and it is the one people actually ask.
+  //
+  // ⚠ NO NEW OPERATOR ENTERS EITHER ENGINE. `isEmpty`/`isNotEmpty` already exist in
+  // `filter_sql.py` (:76, and :112's VALUE_FREE_OPS) and `filter_eval.py` (:260-262), and both
+  // are TYPE-INDEPENDENT �� they test blankness before any type dispatch — so the lock-step is
+  // untouched and nothing on the server had to move for this line. (The contract's prose spells
+  // them `is_empty`/`is_not_empty`; the runtimes do not. The names come from the code.)
+  if (t === "json") return ["isNotEmpty", "isEmpty"];
+  // Wave-18 C5-AUTOFIELD — `automation` lands HERE, on the text ops, and that is the whole
+  // v1 answer. Its cell is one machine-written line (`ok · 2026-08-03 14:10 · 12 posts`), so
+  // `contains ok` and `contains error` are the two questions anyone actually asks of the
+  // column, and both are already sound over a string. Nothing new enters the operator
+  // vocabulary, so the `filter_sql.py` lock-step is untouched — a new op for "state is" would
+  // have to be mirrored in the Python engine, and the substring answer is the same answer.
+  return ["contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty"]; // text
+}
+
+/**
+ * C-OPS — the RANK operators, worded so the row still reads as a sentence.
+ *
+ * The unit lives in the OPERATOR, not beside the box: "top" followed by a bare 10 is ambiguous
+ * between ten records and ten percent, so `top N` and `top N%` are two operators and the box
+ * supplies N. The alternative — a "%" suffix element after the input — would put a second
+ * thing in the value slot that every gate locating `.cg-cond-val` would have to know about.
+ *
+ * ⚠ AND THEY ARE SHORT ON PURPOSE. A 136px `.cg-select` has ~97.9px of readable width (see
+ * `cohortOpLabel` below, and `withCurrentField` below) — about 15 characters of 12.5px Inter.
+ * "is in the bottom N%" is 19 and would have shipped CLIPPED, which no assertion here can see
+ * and no screenshot in this session could catch. Dropping the "is " costs nothing: the numeric
+ * operators beside these are bare glyphs (`≥ > ≤ <`), so the row already reads without one,
+ * and the `Ranked` divider carries the "these are a different kind of question" signal. Fifth
+ * time this control has outgrown a label; the label gives way, never the control.
+ */
+export const RANK_OP_LABELS: Record<string, string> = {
+  topN: "top N",
+  bottomN: "bottom N",
+  inTopPct: "top N%",
+  inBottomPct: "bottom N%",
+  aboveAvg: "above average",
+  belowAvg: "below average",
+  inQuartile: "in quartile",
+  inDecile: "in decile",
+};
+
+/**
+ * The value a rank op starts at when it is chosen.
+ *
+ * Seeded rather than left blank, and this is a deliberate break from how the other operators
+ * behave: a blank value makes a rule INACTIVE, so `is in the top N` with nothing typed would
+ * sit in the builder narrowing nothing, and "the filter I just added does nothing" reads as a
+ * broken control rather than as an unfinished sentence. Every rank op has an obvious default —
+ * ten, or the top slice — so there is a right answer to seed. The two averages take none.
+ */
+export function rankDefault(op: FilterOp): string {
+  switch (op) {
+    case "topN":
+    case "bottomN":
+    case "inTopPct":
+    case "inBottomPct":
+    case "inDecile":
+      return "10";
+    case "inQuartile":
+      return "4";
+    default:
+      return ""; // aboveAvg / belowAvg — value-free
+  }
+}
+
+/* ⛔ `hasRankCondition` LIVED HERE AND IS DELETED WITH THE PARAGRAPH IT GATED (wave 34, R5).
+   Its whole job was to decide whether to draw the builder's rank explainer; the owner has
+   removed that paragraph, and the predicate had exactly one caller besides its own recursion.
+   ⚠ `isRankOp` stays: `opLabel` below still calls it. `isMeasureRule` was `hasRankCondition`'s
+   ONLY use in this module, so THIS FILE'S IMPORT of it went too — the symbol itself lives on in
+   `types.ts` with plenty of callers, including `FilterBuilderPanel` two files over. The
+   distinction matters: an unused IMPORT is dead weight here, an unused EXPORT would be dead code
+   there, and only one of those was true.
+   ⚠⚠ THIS COMMENT'S FIRST DRAFT SAID BOTH SYMBOLS "STAY, they have many callers" — and `tsc`
+   refuted it in the next run. That is the THIRD time in one session a confident claim about who
+   calls a symbol was wrong within a minute of writing it. The habit worth keeping is not "be more
+   careful"; it is that the compiler answers this question for free, so ask it before asserting. */
+
+/** Human label for an operator, read naturally per field type. */
+export function opLabel(op: FilterOp, t: FieldType): string {
+  // Rank first and type-independently: a rank op means the same thing on every numeric
+  // family, and a view whose column has since changed type must still SAY what it holds
+  // rather than falling through to a raw key.
+  if (isRankOp(op)) return RANK_OP_LABELS[op] ?? op;
+  // Checkbox first: its two value-free ops READ as states, not as blankness — the storage
+  // contract ('1' or blank) is an implementation detail the sentence must not leak.
+  if (t === "checkbox") {
+    if (op === "isNotEmpty") return "is checked";
+    if (op === "isEmpty") return "is unchecked";
+  }
+  // Type-independent: Airtable words these identically for every field type.
+  if (op === "isEmpty") return "is empty";
+  if (op === "isNotEmpty") return "is not empty";
+  if (isDateFamily(t)) {
+    switch (op) {
+      case "eq":
+        return "is";
+      case "neq":
+        return "is not";
+      case "within":
+        return "is within";
+      case "lt":
+        return "is before";
+      case "lte":
+        return "is on or before";
+      case "gt":
+        return "is after";
+      case "gte":
+        return "is on or after";
+      case "between":
+        return "is between";      // no longer offered; still rendered for a saved view
+    }
+  }
+  if (isNumericType(t)) {
+    switch (op) {
+      case "gte":
+        return "≥"; // ≥
+      case "gt":
+        return ">";
+      case "lte":
+        return "≤"; // ≤
+      case "lt":
+        return "<";
+      case "eq":
+        return "=";
+      case "neq":
+        return "≠"; // ≠
+      case "between":
+        return "is between";
+      default:
+        return op;
+    }
+  }
+  if (t === "multiselect") {
+    // Membership wording over the joined-set cell. "has" IS `contains` (see opsForType) — only
+    // the label changes, so the engine and its Python mirror stay untouched.
+    switch (op) {
+      case "contains":
+        return "has";
+      case "doesNotContain":
+        return "does not have";
+      case "eq":
+        return "is exactly";
+      case "neq":
+        return "is not exactly";
+      default:
+        return op;
+    }
+  }
+  // text / status. (Airtable suffixes value-taking ops with "…" in the OPEN
+  // dropdown only; a native <select> shows one string in both states, so we use
+  // the closed-state wording — which is what's on screen almost all the time.)
+  switch (op) {
+    case "contains":
+      return "contains";
+    case "doesNotContain":
+      return "does not contain";
+    case "eq":
+      return "is";
+    case "neq":
+      return "is not";
+    default:
+      return op;
+  }
+}
+
+/**
+ * The offered list, PLUS whatever the rule is actually set to.
+ *
+ * A `<select>` whose `value` is not among its `<option>`s renders the FIRST option instead —
+ * so a saved view holding a dropped operator (a date `between`) or a column that has since left
+ * the filter list (`at_risk`, once its measure replacement shipped) would display something the
+ * rule does not say, and the first edit would silently rewrite it to that. Painted, plausible,
+ * and wrong: the class of failure a screenshot catches and an assertion does not.
+ */
+export function withCurrent<T extends string>(offered: readonly T[], current: T | undefined): T[] {
+  return current && !offered.includes(current) ? [...offered, current] : [...offered];
+}
+
+/** A group's summary line, mirroring Airtable's wording. */
+export function groupSummary(conj: Conjunction): string {
+  return conj === "or"
+    ? "Any of the following are true…"
+    : "All of the following are true…";
+}
+
+/**
+ * CG-8 — the operators a MEASURE condition may use, and why they are not `opsForType`.
+ *
+ * A measure is answered by a SQL `HAVING`, and `harness/measure_filter.OPS` has exactly six
+ * comparisons. `between` would need two, and `isEmpty`/`isNotEmpty` have no meaning for a sum
+ * that is defined to be 0 when there is nothing to add up — the resolver refuses all three by
+ * name. Offering them here would produce a condition the server can only reject.
+ *
+ * The owner's "dates between X and Y" is the WINDOW's between, not the value's, and that is the
+ * `custom` window kind — so nothing is lost.
+ */
+export const MEASURE_OP_LIST: FilterOp[] = [...MEASURE_OPS];
+
+/** CG-9 — narrower still when the other side is a measure. `=` and `≠` between two sums of
+ *  floats match nobody and everybody respectively; see types.ts MEASURE_PAIR_OPS. */
+export const MEASURE_PAIR_OP_LIST: FilterOp[] = [...MEASURE_PAIR_OPS];
+
+/**
+ * A cohort condition names a SET of cohorts (owner, 2026-07-27), so its operators are set
+ * operators. `eq`/`neq` are not offered — the validator rewrites them to `anyOf`/`noneOf`, and
+ * `withCurrent` would otherwise show a legacy view an operator it can never choose again.
+ */
+export const COHORT_OP_LIST: CohortOp[] = [...COHORT_OPS];
+
+/**
+ * ⚠ "is part of any of" measures ~96px at 12.5px Inter against the 97.9px of readable width a
+ * 136px select actually has (136 - 20.1 arrow - 16 padding - 2 border) — inside the box only
+ * until a fallback font renders it. Airtable's own wording for a multi-select is shorter and
+ * says the same thing, so the LABEL gives way, not the control. Third time this rule has been
+ * applied; see the "(not filterable)" and "the 75th percentile" clippings before it.
+ */
+export function cohortOpLabel(op: FilterOp | CohortOp): string {
+  switch (normalizeCohortOp(op)) {
+    case "allOf":
+      return "is all of";
+    case "noneOf":
+      return "is none of";
+    default:
+      return "is any of";
+  }
+}
+
+/** Item 20 — the mark a MEASURE row wears in every picker on this surface. Named once so the
+ *  three lists that offer measures cannot drift into two different glyphs for one concept. */
+export const MEASURE_MARK: FieldSelectType = "measure";
+
+/** A measure condition is identified by its window, so a new one needs a default window. */
+export const DEFAULT_WINDOW: WindowSpec = { kind: "ltm" };
+
+/** The default RANGE for `is within` — the owner's first example ("the past month"). */
+export const DEFAULT_DATE_WINDOW: WindowSpec = { kind: "past_month" };
+
+/**
+ * The ranges `is within` offers, in the owner's own order (item 3, 2026-07-26):
+ * the past number of days · the past week · the past month · the past year · this calendar
+ * week · this calendar month · this calendar year.
+ *
+ * Plus `custom`, which is not a nicety: dropping `between` from the date operators would
+ * otherwise remove the ability to ask for two exact dates at all. The remaining kinds
+ * (yesterday, last_quarter, ytd_last_year, the forward-looking ones…) stay available to a
+ * MEASURE's window, where they make sense; "last order is within year to date, last year" is a
+ * question nobody asks.
+ */
+export const WITHIN_KINDS: WindowKind[] = [
+  "last_n_days", "past_week", "past_month", "past_year",
+  "this_week", "this_month", "this_year", "custom",
+];
+
+/**
+ * The field dropdown's COLUMN half, plus the column the rule is actually set to if the picker
+ * no longer offers it. See `withCurrent` — a select whose value is missing from its options
+ * silently displays a different field than the rule holds. This is not hypothetical: the
+ * shipped "Win-back" list filters `at_risk`, which left the filter list the day its measure
+ * replacement arrived.
+ */
+export function withCurrentField(
+  fields: Field[],
+  current: string,
+  fieldByKey: Map<string, Field>,
+  measureByKey: Map<string, Measure>,
+  hasCohorts: boolean
+): FieldSelectItem[] {
+  // Item 20: the rows carry their TYPE now, because the picker paints the type mark. Same
+  // list, same order, same `withCurrent` rule — only the shape of a row grew a field.
+  const out: FieldSelectItem[] = fields.map((f) => ({
+    key: f.key, label: f.label, type: f.type,
+  }));
+  const known = new Set(out.map((o) => o.key));
+  if (!current || known.has(current) || measureByKey.has(current)) return out;
+  if (current === COHORT_FIELD && hasCohorts) return out;
+  // The field's OWN label, with no "(not filterable)" annotation: the select is ~170px and the
+  // suffix CLIPPED to "At risk $ (not filter" — a truncated parenthetical reads as a rendering
+  // bug, and the property that matters is that the condition says what it says. Found by
+  // reading the screenshot; every assertion in the run was green.
+  const f = fieldByKey.get(current);
+  out.push({ key: current, label: f ? f.label : current, type: f?.type });
+  return out;
+}
+
+/** Ids only have to be unique within one view's tree; they never leave this browser's view. */
+let ruleSeq = 0;
+export function newRuleId(): string {
+  ruleSeq += 1;
+  return `r${Date.now().toString(36)}${ruleSeq.toString(36)}`;
+}
+
+/** A fresh leaf condition on the first available field. */
+export function newCondition(fields: Field[]): FilterRule | null {
+  const f0 = fields[0];
+  if (!f0) return null;
+  return { colId: f0.key, op: opsForType(f0.type)[0], value: "" };
+}
+
+/** Total LEAF conditions in a filter tree (groups contribute their contents). */
+export function countConditions(nodes: FilterNode[]): number {
+  let n = 0;
+  for (const node of nodes)
+    n += isFilterGroup(node) ? countConditions(node.children) : 1;
+  return n;
+}

web/src/inbox/InboxPage.tsx

@@ -46,7 +46,6 @@ import {
   UNOPENABLE_NOTE,
   canOpen,
   inboxSections,
-  kindLabel,
   previewOf,
   senderOf,
   subjectOf,
@@ -538,9 +537,15 @@ export function InboxSurface({
                   onClick={() => onOpen(selected)}
                 >
                   {/* Item 19 (T29): the verb names the DESTINATION rather than promising
-                      "open" generically — two kinds go two places. */}
-                  {kindLabel(selected.kind) === "Automation"
-                    ? "Open the automation"
+                      "open" generically — two kinds go two places.
+                      ⛔ WAVE 34 · R12 — THIS COMPARED A DISPLAY STRING, AND THAT IS WHY IT IS
+                      WRITTEN THIS WAY NOW. It read `kindLabel(selected.kind) === "Automation"`:
+                      a second copy of a caption, in a file the rename had no reason to open. The
+                      moment `kindLabel` returned "Agents" the test went false in silence and
+                      every automation notification offered to open a DATABASE. Compare the KIND,
+                      which is a stored wire value nobody renames for a caption. */}
+                  {selected.kind === NOTIF_KIND_AUTOMATION
+                    ? "Open the agent"
                     : "Open the database"}
                 </button>
               ) : (

web/src/inbox/inboxModel.ts

@@ -115,10 +115,21 @@ export function previewOf(n: Notification): string {
   return label && label !== subjectOf(n) ? label : "";
 }
 
+/**
+ * ⭐ WAVE 34 · R12 — THE MODULE'S NAME, IN ONE PLACE ON THE CLIENT.
+ *
+ * The owner renamed the Automation module to **Agents**. The WIRE kind stays `automation`
+ * ({@link NOTIF_KIND_AUTOMATION}) because it is a stored value on every queued notification;
+ * only what a reader sees moved. Both display sites below take it from here rather than
+ * repeating the word, because the last rename left the literal in three files and a fourth
+ * comparing against it.
+ */
+export const AGENTS_MODULE_LABEL = "Agents";
+
 /** The kind, in the reader's words. Unknown kinds fall to the alert wording rather than to a raw
  *  server token — a row is never allowed to print a vocabulary word at somebody. */
 export function kindLabel(kind: string | undefined): string {
-  if (kind === NOTIF_KIND_AUTOMATION) return "Automation";
+  if (kind === NOTIF_KIND_AUTOMATION) return AGENTS_MODULE_LABEL;
   if (kind === NOTIF_KIND_SHARE) return "Shared with you";
   return "Alert";
 }
@@ -138,7 +149,7 @@ export function kindLabel(kind: string | undefined): string {
 export function senderOf(n: Notification): string {
   const sent = String(n.sender || "").trim();
   if (sent) return sent;
-  if (n.kind === NOTIF_KIND_AUTOMATION) return "Automation";
+  if (n.kind === NOTIF_KIND_AUTOMATION) return AGENTS_MODULE_LABEL;
   if (n.kind === NOTIF_KIND_SHARE) return "A teammate";
   return "Alerts";
 }

web/src/index.css

@@ -171,6 +171,23 @@
   --lp-purple-tint: #f1eefb;  /*  the GROUP chip wash + its column header   */
   --lp-purple-deep: #6b57a8;  /*  5.17:1 on its tint — group chip text      */
 
+  /* --- WAVE 34 R2 — THE BRAND MARK'S PURPLE, NOW A TOKEN --------------------
+     Owner, 2026-08-16: *"The loading screen loop, the color should be purple as
+     well."* "As well" is the operative phrase: the loop mark in the logo is this
+     purple, and the spinner is the same loop, so it should be the same colour.
+
+     ⛔ THIS IS THE THIRD PURPLE AND IT IS NOT INTERCHANGEABLE WITH THE OTHER TWO.
+     `--lp-purple` (#c3b3ee) is a 1.91:1 FILL and would be invisible as a 2px arc;
+     `--lp-purple-deep` (#6b57a8) is the GROUP control's hue, and a spinner painted
+     from it would say "this wait is about grouping". This one is the mark's own
+     colour, previously a literal in `favicon.svg` and `_brandmark.LP_PURPLE` with
+     no CSS token at all — which is exactly why the comment three lines up had to
+     spell the hex out in prose to warn people off it.
+     ⚠ The comment above still stands and is not contradicted: the brand purple is
+     deliberately OUTSIDE the UI palette. This token does not admit it to the
+     palette; it names it so the ONE surface that is the brand mark can use it. */
+  --lp-brand: #6e56cf;        /*  the loop mark (favicon.svg, _brandmark)     */
+
   /* --- Wave-15 C-BOLD (owner ruling R7) — THE PRIMARY ACTION -----------------
      "Key buttons bold (dark purple)". A THIRD role in the palette, and it is
      worth naming why it is not one of the five hues above: `--lp-purple` is the
@@ -2639,12 +2656,29 @@ body {
    a nav that came back empty said the same thing. A mark that spins says only
    "still working", which is the one true statement available.
 
-   TWO COLOURS, ZERO LITERALS. The leading arc is `currentColor`, so the mark
-   inherits the ink of whatever it sits in and no caller has to pick a colour;
-   the track is that same ink at 22%, which reads as the muted grey the contract
-   asks for WITHOUT hard-coding a grey that would disappear on a tinted panel.
-   A literal here would be exactly the mid-render one-off the palette block at
-   the top of this file spent 55 call sites removing.
+   TWO COLOURS, ZERO LITERALS. The TRACK is `currentColor` at 22%, so it reads as
+   the muted grey the contract asks for WITHOUT hard-coding a grey that would
+   disappear on a tinted panel.
+
+   ⭐ WAVE 34 R2 — THE LEADING ARC IS THE BRAND PURPLE NOW, not `currentColor`.
+   Owner: *"The loading screen loop, the color should be purple as well."* The
+   spinner IS the logo's loop, so it wears the logo's colour.
+   ⚠ WHAT THAT COSTS, stated rather than discovered later: the arc no longer
+   adapts to its container's ink. That adaptation was the original design and it
+   was a good one — it is why no caller has ever had to pick a colour. Pinning it
+   is safe TODAY because it was MEASURED, not assumed. All 27 `.lp-spin` call sites
+   sit on light panels, and #6e56cf against each of them is:
+        white 5.39:1 · --lp-surface-2 #f7f7f6 5.03:1 · --lp-purple-tint 4.71:1
+        --lp-wash #fafbfc 5.20:1
+   NONE of them sits inside a filled or dark button, which is the case that breaks.
+   (These are the same numbers the palette block above quotes for its own hues, by
+   the same formula — a contrast claim written as "clears 4.5:1" would have been a
+   threshold restated as a fact [[no-unverifiable-aggregates]].)
+   ⛔ SO THE RULE FOR THE NEXT PERSON: if you mount `.lp-spin` on a dark or
+   saturated surface, it will be nearly invisible and the fix is a modifier class
+   that restores `currentColor` for that surface, NOT reverting this line.
+   The TRACK deliberately stays `currentColor` so the ring still seats itself on
+   whatever it sits on.
 
    Markup contract (C-SPIN): <span class="lp-spin" role="status" aria-label="Loading" />
    — an empty element, sized by CSS. `aria-label` carries the word so the screen
@@ -2655,7 +2689,7 @@ body {
   width: 14px;
   height: 14px;
   border: 2px solid color-mix(in srgb, currentColor 22%, transparent);
-  border-top-color: currentColor;
+  border-top-color: var(--lp-brand);
   border-radius: 50%;
   animation: lp-spin-rot 0.7s linear infinite;
 }
@@ -2744,7 +2778,7 @@ body {
   padding: 26px 28px 18px;
   box-shadow: var(--shell-shadow-overlay);
 }
-.login-brand { display: flex; align-items: center; gap: 12px; margin-bottom: 12px; }
+.login-brand { display: flex; align-items: center; gap: 12px; margin-bottom: 6px; }
 .login-brand .lp-wordmark {
   font-size: var(--lp-fs-lg);
   font-weight: 600;
@@ -2752,6 +2786,27 @@ body {
   line-height: 1.15;
 }
 
+/* ⭐ WAVE 34 R9 — the sign-in card's one line of sell.
+   ⚠ IT MUST NOT COMPETE WITH THE WORDMARK. `--lp-fs-sm` and the muted ink put it a clear step
+   below the brand line, which is what keeps the card reading as a door rather than a landing
+   page. The 18px bottom margin replaces `.login-brand`'s 12px as the gap before the form, so the
+   form does not move when this line is present: measured from the same total, not added to it.
+   ⛔ NO gold accent line and no rule above the form. The owner rejected exactly that once already
+   ("there's an orange line at the top, it's ugly"), and a slogan is the most tempting place to
+   reach for one. */
+/* ⚠ `--lp-muted`, NOT `--lp-ink-muted`. The first draft of this rule used the second name, which
+   does not exist -- and a ghost token does not fail loudly, it paints the INHERITED colour, so the
+   tagline would have rendered at full `--lp-ink` weight and competed with the wordmark. The token
+   block above carries a scar from the same class (`--lp-wash: var(--lp-wash)`, a self-reference
+   that silently painted nothing everywhere it was consumed) and notes that the ghost-token gate
+   only checks a consumed name is DECLARED. Measured: `--lp-muted` #6b7280 is 4.83:1 on white. */
+.login-tagline {
+  margin: 0 0 18px;
+  font-size: var(--lp-fs-sm);
+  color: var(--lp-muted);
+  letter-spacing: -0.005em;
+}
+
 /* ---- the 8-STATE INPUT DISCIPLINE ----------------------------------------
    rest · placeholder · hover · focus · filled · error · disabled · autofill.
    border-WIDTH is 1px in EVERY state — state is carried by colour, background
@@ -4673,6 +4728,26 @@ a.cg-map-ctl-b { text-decoration: none; }
 /* Wave-8 I11c (C4) — folders in the Views rail. */
 .cg-fold-new { padding: 2px 8px 4px; }
 .cg-fold, .cg-fold-root { border-radius: 6px; }
+/* ⭐⭐ WAVE 34 · T22 (ruling R4) — WHILE A VIEW IS BEING DRAGGED, THE ROOT SECTION HAS A BODY.
+   Off-drag this rule does not apply at all, so the rail keeps the exact layout it has today; the
+   class is only on the root group and only while `viewDrag !== null` (ViewSidebar).
+   · `min-height` is the EMPTY case: a user who filed every view into folders had a zero-pixel
+     drop target and no way to unfile anything.
+   · `padding-bottom` is the POPULATED case, which is the one nobody had noticed. This element has
+     no padding of its own, so its box is exactly the union of its rows, and every row claims the
+     drag for reordering via `stopPropagation`. Without a strip BELOW the last row there is no
+     pixel anywhere that means "file this at the top level".
+   ⚠ IT SETS NO PAINT, DELIBERATELY. `.cg-fold-root.is-drop` immediately below is the hover state
+   and must keep winning; declaring a background or outline here would fight it at equal
+   specificity and the "you are about to drop here" tint would depend on rule order. The area is
+   this rule's job, the picture is that one's.
+   ⚠ COST, STATED: the "Shared with me" group (the only thing rendered after root) shifts down by
+   this padding for the duration of a drag. That is the price of not reserving the space
+   permanently, and a transient shift under the cursor reads as the target opening up. */
+.cg-fold-root.is-viewdrop {
+  min-height: 30px;
+  padding-bottom: 20px;
+}
 .cg-fold.is-drop, .cg-fold-root.is-drop {
   background: var(--lp-blue-tint);
   outline: 1px dashed var(--lp-blue-deep);
@@ -12194,16 +12269,33 @@ textarea.cg-json-raw:focus {
    auto` pushes it to the right edge so the badge lines up with the per-view badges directly
    below it — the total and its parts read as one column, which is the whole point of putting it
    here rather than in the shell's database header. */
+/* ⭐⭐ WAVE 34 · T20 (R1, contract C1) — THE WORD IS GONE, SO ITS TYPOGRAPHY GOES WITH IT.
+   `gap`, `font-size`, `font-weight` and `color` here only ever painted the literal "Important";
+   with the label removed they style nothing (the badge sets its own), and left in place they are
+   the kind of inert rule a later reader restores a label to fit. What survives is the LAYOUT this
+   wrapper is actually for: `margin-left: auto` pushes it to the right edge so the total lines up
+   with the per-view badges directly below it, and the class name itself is contract C1's hook
+   (`.cg-views-important.is-partial` hangs the dashed-purple partial mark off it, and B's flyout
+   row is named against it). */
 .cg-views-important {
   margin-left: auto;
   display: inline-flex;
   align-items: center;
-  gap: 6px;
-  font-size: var(--lp-fs-2xs);
-  font-weight: 600;
-  color: var(--lp-muted);
   white-space: nowrap;
 }
+/* R1's "SMALLER", as a box rather than as type. ⛔ THE FONT CANNOT SHRINK AND THAT IS A REAL
+   CONSTRAINT, NOT AN OMISSION: `--lp-fs-3xs` (11px) is the smallest size the scale declares, and
+   `verify_ui`'s R5 leg reds ANY literal `font-size` in `web/src` CSS, so the only way to go below
+   it is to add a fourth micro size to the type scale for one badge. 20x20 -> 16x16 is a 36% cut
+   in area on top of losing the label, which is what the ruling asked for; inventing a 10px step
+   under the scale's own floor is not. ⚠ SCOPED BY PARENT on purpose: `.cg-view-count` is shared
+   with the per-view badges (and with `.is-unknown`), and shrinking it unscoped would resize every
+   count in the rail from a ruling about the header. */
+.cg-views-important .cg-view-count {
+  min-width: 16px;
+  height: 16px;
+  padding: 0 2px;
+}
 /* A PARTIAL total wears the same purple as a whole one — the number it shows IS real, it is just
    not all of them — and says so with a `+` and its title. Muting it would read as "less
    important" rather than "less complete". */

web/src/query/QueryPage.tsx

@@ -1,24 +1,41 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 
 import type { QueryOpenDetail } from "../apiContract";
 import { QUERY_OPEN_EVENT } from "../apiContract";
 import CustomerGrid from "../customer-grid/CustomerGrid";
 import { OverlayProvider } from "../customer-grid/OverlaySurface";
 import { queryCitationLabel } from "../customer-grid/queryPreview";
-import { retryEmit } from "../inbox/inboxModel";
 import { DbHead, gridScopeFor } from "../shell/dbFrame";
 import { databaseEntries } from "../shell/nav";
 import type { NavEntry } from "../shell/nav";
 import { bindingFor, deleteQuery, fetchQueries, QUERY_BINDING_EVENT } from "./queryApi";
 import type { QueryCitation, SavedQuery } from "./queryApi";
-import { QueryEmpty, QueryProvenance, QueryRail } from "./queryParts";
+import { QueryEmpty, queryGroups, QueryProvenance, QueryRail } from "./queryParts";
 import type { QueryGroup } from "./queryParts";
 import "./query.css";
 
-export interface QueryPageProps { granted: NavEntry[]; }
-
-/** Long enough for a cold grid, without giving the Assistant a native-view event path. */
-export const VIEW_SELECT_RETRY_MS = [0, 250, 700, 1500, 2600, 5000, 9000, 14000, 21000] as const;
+export interface QueryPageProps {
+  granted: NavEntry[];
+  /**
+   * ⭐ R14 — the merged Assistant surface hosts the view list in its OWN left panel, so Query
+   * renders no rail here. It is a flag rather than a second component because the SELECTION
+   * contract does not change: the host emits `QUERY_OPEN_EVENT` through `openBuiltView`, which is
+   * the same public qid hand-off an external link uses, and the listener below answers both.
+   */
+  hostedRail?: boolean;
+  /** Bumped by the host after it deletes a view, so the two lists cannot drift apart. */
+  refreshToken?: number;
+  /**
+   * ⛔ THE HOST'S SELECTION, AND IT IS A GUARANTEE THE EVENT CANNOT GIVE. `QUERY_OPEN_EVENT` stays
+   * the published qid contract and still answers external callers, but it is a RACE: `retryEmit`'s
+   * default ladder tops out at 2,600 ms, tuned for a click into a grid that is usually warm, while
+   * the hosted workspace is a LAZY chunk over a cold grid that CLAUDE.md measures painting at
+   * ~12 s. Every dispatch lands before the listener exists, none is acked, and the rail then
+   * highlights a view the main column is not showing, 200 OK and silent. A prop arrives in the
+   * same commit as the mount.
+   */
+  selectedId?: string;
+}
 
 /**
  * Query is a database frame over a virtual artefact.  Its public contract for B is the
@@ -28,43 +45,17 @@ export const VIEW_SELECT_RETRY_MS = [0, 250, 700, 1500, 2600, 5000, 9000, 14000,
  * ⭐⭐ OWNER ITEM 3 (2026-08-15) — THE RAIL IS THE NAVIGATION. See `queryParts.QueryRail`: the
  * top-right dropdown is gone AND replaced, rather than gone and left as an implicit `views[0]`.
  */
-export default function QueryPage({ granted }: QueryPageProps) {
+export default function QueryPage({ granted, hostedRail, refreshToken, selectedId }: QueryPageProps) {
   const [views, setViews] = useState<SavedQuery[]>([]);
   const [citations, setCitations] = useState<QueryCitation[]>([]);
   const [activeId, setActiveId] = useState("");
   const [loaded, setLoaded] = useState(false);
-  const emitCancel = useRef<(() => void) | null>(null);
   const entries = databaseEntries(granted);
   const entryOf = (key: string) => entries.find((entry) => entry.key === key);
   const known = views.filter((view) => entryOf(view.source.database));
   const active = known.find((view) => view.id === activeId) ?? known[0] ?? null;
 
-  /**
-   * ⚠ GROUPED IN THE ORDER THE DATABASES ARE GRANTED, not by artefact age. The rail is a list of
-   * DATABASES first (owner: "each View correspond to the relevant database"), so a new answer
-   * about Customers must not move the Customers heading — it appears under it. Within a database
-   * the newest is first, which is the order the server already sends.
-   */
-  const groups = useMemo<QueryGroup[]>(() => {
-    const byDatabase = new Map<string, SavedQuery[]>();
-    for (const view of known) {
-      const list = byDatabase.get(view.source.database);
-      if (list) list.push(view);
-      else byDatabase.set(view.source.database, [view]);
-    }
-    const out: QueryGroup[] = [];
-    for (const entry of entries) {
-      const list = byDatabase.get(entry.key);
-      if (!list || entry.kind === "group") continue;
-      out.push({
-        database: entry.key,
-        label: list[0].source.label || entry.label,
-        ...(entry.icon ? { icon: entry.icon } : {}),
-        views: list,
-      });
-    }
-    return out;
-  }, [known, entries]);
+  const groups = useMemo<QueryGroup[]>(() => queryGroups(views, entries), [views, entries]);
 
   const reload = useCallback(async () => {
     const result = await fetchQueries();
@@ -77,18 +68,42 @@ export default function QueryPage({ granted }: QueryPageProps) {
 
   useEffect(() => { void reload(); }, [reload]);
 
+  /** The host owns the rail in the merged surface; a delete there must not leave this list stale. */
+  useEffect(() => { if (refreshToken) void reload(); }, [refreshToken, reload]);
+
+  /**
+   * Set BEFORE the fetch lands, deliberately: `known` is empty until then, so the fallback below
+   * does not fire, and by the time it can the id it would replace is already the right one.
+   */
+  useEffect(() => { if (selectedId) setActiveId(selectedId); }, [selectedId]);
+
   useEffect(() => {
     if (known.length && !known.some((view) => view.id === activeId)) setActiveId(known[0].id);
   }, [known, activeId]);
 
+  /**
+   * ⛔⛔ THE BINDING GOES DOWN AS A PROP, AND THAT IS NOT A TIDY-UP.
+   * `CustomerGrid` registers its `QUERY_BINDING_EVENT` listener only when `isQueryPreviewRoute()`
+   * is true, i.e. only while the hash starts `#/query`. R14 moves this surface INSIDE
+   * `#/assistant`, where that predicate is false — so on the event path alone the grid would
+   * receive no binding, `isQueryPreview` would be false, `previewReadOnly` with it, and the
+   * merged surface would render a fully EDITABLE database grid over an immutable AI artefact,
+   * 200 OK, with the immutability contract intact on paper. Every WRITE guard in the grid keys on
+   * `queryBinding`; only the listener keys on the route. A prop is gated on neither.
+   *
+   * ⚠ Memoised because `CustomerGrid`'s preview effect lists `queryBinding` in its deps: a fresh
+   * object per render re-enters it on every unrelated state change on this page.
+   */
+  const binding = useMemo(
+    () => (active ? bindingFor(active, citations) : undefined), [active, citations]);
+
   useEffect(() => {
-    if (!active) return;
-    emitCancel.current?.();
-    emitCancel.current = retryEmit(() => {
-      window.dispatchEvent(new CustomEvent(QUERY_BINDING_EVENT, { detail: bindingFor(active, citations) }));
-    }, undefined, VIEW_SELECT_RETRY_MS);
-    return () => emitCancel.current?.();
-  }, [active, citations]);
+    if (!binding) return;
+    // Still published for B, which is what `QUERY_BINDING_EVENT` is: one dispatch, not a ladder.
+    // The 21 s retry ladder that used to be here existed for ONE failure — the grid mounting
+    // after the event was fired — and a prop delivered in the same commit cannot have it.
+    window.dispatchEvent(new CustomEvent(QUERY_BINDING_EVENT, { detail: binding }));
+  }, [binding]);
 
   useEffect(() => {
     const onOpen = (event: Event) => {
@@ -105,6 +120,11 @@ export default function QueryPage({ granted }: QueryPageProps) {
     return () => window.removeEventListener(QUERY_OPEN_EVENT, onOpen);
   }, [views, reload]);
 
+  /** A renamed or duplicated artefact, merged in place: the rail owns the call, the page the list. */
+  const upsert = useCallback((view: SavedQuery) => {
+    setViews((current) => [view, ...current.filter((row) => row.id !== view.id)]);
+  }, []);
+
   const remove = useCallback(async (qid: string) => {
     const result = await deleteQuery(qid);
     if (!result.ok) return;
@@ -122,12 +142,16 @@ export default function QueryPage({ granted }: QueryPageProps) {
       <DbHead label={active.source.label} {...(entry?.icon ? { icon: entry.icon } : {})} />
       <div className="shell-grid-host">
         <div className="qy-workspace">
-          <QueryRail groups={groups} activeId={active.id} onSelect={setActiveId} onDelete={(id) => void remove(id)} />
+          {hostedRail ? null : (
+            <QueryRail groups={groups} activeId={active.id} onSelect={setActiveId}
+              onDelete={(id) => void remove(id)} onChanged={upsert} />
+          )}
           <div className="qy-surface">
             <QueryProvenance view={active} detail={provenance} />
             <div className="qy-grid-host">
               <OverlayProvider>
-                <CustomerGrid key={gridScopeFor(active.source.database)} scope={gridScopeFor(active.source.database)} />
+                <CustomerGrid key={gridScopeFor(active.source.database)}
+                  scope={gridScopeFor(active.source.database)} queryBinding={binding} />
               </OverlayProvider>
             </div>
           </div>

web/src/query/query.css

@@ -64,6 +64,114 @@
 
 .qy-rail-group { margin-bottom: 10px; }
 
+/* ── R20: the per-view menu, the same vocabulary a database view offers ───── */
+
+.qy-rail-more {
+  flex: 0 0 auto;
+  width: 24px;
+  height: 24px;
+  margin-right: 4px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--lp-muted);
+  opacity: 0;
+  cursor: pointer;
+}
+
+.qy-rail-more svg { fill: currentColor; stroke: none; }
+
+.qy-rail-row:hover .qy-rail-more,
+.qy-rail-row.is-active .qy-rail-more,
+.qy-rail-more:focus-visible,
+.qy-rail-more[aria-expanded="true"] { opacity: 1; }
+
+/* Sits above the rows, under the menu, so a click anywhere else closes it without every row
+   needing its own outside-click listener. */
+.qy-rail-scrim {
+  position: fixed;
+  inset: 0;
+  z-index: 20;
+  border: 0;
+  padding: 0;
+  background: transparent;
+  cursor: default;
+}
+
+/* FIXED, not absolute: its natural parent `.qy-rail-scroll` is `overflow-y: auto`, which clips
+   both axes, so a menu opened on a row near the bottom of the list would render cut off or
+   invisible. `top`/`right` are supplied inline from the button's own rect. */
+.qy-rail-menu {
+  position: fixed;
+  z-index: 21;
+  min-width: 168px;
+  margin-top: 2px;
+  padding: 4px;
+  display: flex;
+  flex-direction: column;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-r-md);
+  background: var(--lp-surface);
+  box-shadow: 0 6px 18px rgba(20, 24, 40, 0.12);
+}
+
+.qy-rail-item {
+  display: block;
+  padding: 6px 10px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--lp-ink);
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+  text-align: left;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.qy-rail-item:hover { background: var(--lp-surface-2); }
+.qy-rail-item.is-danger { color: var(--lp-red-deep); }
+
+.qy-rail-edit { flex: 1 1 auto; min-width: 0; padding: 2px 4px; }
+
+.qy-rail-input {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 5px 8px;
+  border: 1px solid var(--lp-blue-solid);
+  border-radius: 6px;
+  background: var(--lp-surface);
+  color: var(--lp-ink);
+  font: inherit;
+  font-size: var(--lp-fs-2xs);
+}
+
+.qy-rail-note {
+  flex: 1 0 100%;
+  margin: 0 0 4px;
+  padding: 0 10px;
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-2xs);
+  line-height: var(--lp-lh);
+}
+
+.qy-rail-problem {
+  margin: 0 6px 6px;
+  color: var(--lp-red-deep);
+  font-size: var(--lp-fs-2xs);
+}
+
+/* A confirmation, not a refusal. Same slot, different voice. */
+.qy-rail-notice {
+  margin: 0 6px 6px;
+  color: var(--lp-muted);
+  font-size: var(--lp-fs-2xs);
+  line-height: var(--lp-lh);
+}
+
 .qy-rail-db {
   display: flex;
   align-items: center;
@@ -103,6 +211,9 @@
 .qy-rail-row {
   position: relative;
   display: flex;
+  /* R20's description sits on its own line under the name, so the row wraps. `position: relative`
+     was already here and is what the menu anchors to. */
+  flex-wrap: wrap;
   align-items: center;
   min-width: 0;
   border-radius: var(--lp-r-md);

web/src/query/queryApi.ts

@@ -35,6 +35,8 @@ export interface SavedQuery {
   viewId: string;
   scope: string;
   name: string;
+  /** R20: a label the reader owns. The SPEC beside it stays immutable, which is the whole split. */
+  description: string;
   kind: string;
   question: string;
   explain: string;
@@ -71,6 +73,9 @@ export interface QueryMessage {
   viewId?: string | null;
   citationIds?: string[];
   numeric?: SavedQuery["numeric"] | null;
+  /** R20's thumbs. Read by the server's own replay, not only written. */
+  rating?: "up" | "down" | null;
+  ratingReason?: string;
 }
 
 /**
@@ -88,12 +93,26 @@ export interface QuerySourceStatus {
   reason: string;
 }
 
+/**
+ * A model this deployment OFFERS, and whether it can actually be called.
+ *
+ * ⭐ The same shape `QuerySourceStatus` uses, for the same reason one control to the left: a
+ * picker that lists a model whose key is not set spends a click and a turn to be told
+ * "unavailable" by a server that knew before the click.
+ */
+export interface QueryModelStatus {
+  model: string;
+  available: boolean;
+  reason: string;
+}
+
 export interface QueryIndex {
   threads: QueryThread[];
   messages: QueryMessage[];
   views: SavedQuery[];
   citations: QueryCitation[];
   models: string[];
+  modelStatus: QueryModelStatus[];
   sources: QuerySourceStatus[];
 }
 
@@ -229,9 +248,10 @@ async function call<T>(path: string, init: RequestInit, read: (body: unknown) =>
   return { ok: true, value: read(body) };
 }
 
-const json = (data: unknown): RequestInit => ({
-  method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(data),
+const sends = (method: string, data: unknown): RequestInit => ({
+  method, headers: { "Content-Type": "application/json" }, body: JSON.stringify(data),
 });
+const json = (data: unknown): RequestInit => sends("POST", data);
 const str = (value: unknown): string => (typeof value === "string" ? value : "");
 const rows = (value: unknown): Record<string, unknown>[] =>
   Array.isArray(value) ? value.filter((row): row is Record<string, unknown> => !!row && typeof row === "object") : [];
@@ -255,7 +275,7 @@ function saved(value: unknown): SavedQuery | null {
   if (!row || !src || !str(row.id) || !str(row.viewId) || !str(row.threadId) || row.virtual !== true) return null;
   return {
     id: str(row.id), viewId: str(row.viewId), scope: str(row.scope) || src.database,
-    name: str(row.name) || "Query", kind: str(row.kind) || "grid",
+    name: str(row.name) || "Query", description: str(row.description), kind: str(row.kind) || "grid",
     question: str(row.question), explain: str(row.explain), threadId: str(row.threadId),
     createdAt: str(row.createdAt), virtual: true, source: src,
     view: (row.view && typeof row.view === "object" ? row.view : {}) as Record<string, unknown>,
@@ -276,6 +296,8 @@ function message(value: unknown): QueryMessage | null {
     reason: str(row.reason) || null, viewId: str(row.viewId) || null,
     citationIds: (row.citationIds as unknown[] || []).filter((v): v is string => typeof v === "string"),
     numeric: (row.numeric && typeof row.numeric === "object" ? row.numeric : null) as QueryMessage["numeric"],
+    rating: row.rating === "up" || row.rating === "down" ? row.rating : null,
+    ratingReason: str(row.ratingReason),
   };
 }
 
@@ -307,6 +329,13 @@ export function parseIndex(body: unknown): QueryIndex {
     views: rows(row?.views).map(saved).filter((v): v is SavedQuery => !!v),
     citations: rows(row?.citations).map(citation).filter((v): v is QueryCitation => !!v),
     models: (row?.models as unknown[] || []).filter((v): v is string => typeof v === "string"),
+    // ⚠ ABSENT ⇒ TREATED AS AVAILABLE, the same way an absent source row is treated as answerable:
+    // the server is the authority and its refusal is still the wall. A client that greyed out
+    // every model it had not heard about would disable the whole picker the moment this field
+    // failed to arrive.
+    modelStatus: rows(row?.modelStatus).filter((item) => !!str(item.model)).map((item) => ({
+      model: str(item.model), available: item.available !== false, reason: str(item.reason),
+    })),
     sources: rows(row?.sources).filter((item) => !!str(item.database)).map((item) => ({
       database: str(item.database), answerable: item.answerable === true, reason: str(item.reason),
     })),
@@ -341,6 +370,70 @@ export function deleteThread(id: string): Promise<Result<true>> {
   return call(`/query/threads/${encodeURIComponent(id)}`, { method: "DELETE" }, () => true as const);
 }
 
+/**
+ * ⭐⭐ R20 — THE THREE DOORS THAT ARE **NOT** `mutateQueryWorkspace`, and the distinction is the
+ * whole design rather than a routing detail.
+ *
+ * `QUERY_MUTATION_POLICY` above is unchanged and still refuses create and update: the generated
+ * SPEC and its provenance are immutable, because a cited number is only worth citing if the thing
+ * it was computed from cannot be edited underneath it. What R20 opens is the LABELS beside it,
+ * and a copy, and a read. Each gets its own named endpoint with a server-side allow-list, because
+ * `routeQueryViewMutation` refuses `view_upsert` on a query binding LOCALLY, before any request
+ * leaves the browser: opening that transport would give one question two answers.
+ */
+export function renameQuery(id: string, patch: { name?: string; description?: string }): Promise<Result<SavedQuery>> {
+  return call(`/query/${encodeURIComponent(id)}`, sends("PATCH", patch),
+    (raw) => saved(raw) as SavedQuery);
+}
+
+export function duplicateQuery(id: string): Promise<Result<SavedQuery>> {
+  return call(`/query/${encodeURIComponent(id)}/duplicate`, json({}), (raw) => saved(raw) as SavedQuery);
+}
+
+/**
+ * A DOWNLOAD, not a fetch: an ordinary same-origin link carries the session cookie, and the server
+ * names the file through `Content-Disposition`. Building a Blob here would mean holding the whole
+ * export in memory to hand it straight back to the browser.
+ */
+export function exportQueryHref(id: string): string {
+  return `${API_V1}/query/${encodeURIComponent(id)}/export`;
+}
+
+/**
+ * ⭐ R20's thumbs. `null` CLEARS the rating: a mis-click that cannot be taken back is worse than
+ * no control, and the server reads a thumbs-down back into the next turn of the same thread, so
+ * an uncorrected one keeps steering.
+ */
+/** What the database's own validator would not take, named rather than quietly missing. */
+export interface QuerySaveResult {
+  scope: string;
+  viewId: string;
+  name: string;
+  dropped: string[];
+}
+
+/**
+ * ⭐ R20: the answer becomes an ordinary view of its own database.
+ *
+ * ⛔ The server does NOT trust the write's own 200: `view_upsert` returns the same shape when it
+ * saved and when it silently refused, so it reads the store back and refuses out loud instead.
+ * There is nothing for this client to retry, which is the point.
+ */
+export function saveQueryToDatabase(id: string): Promise<Result<QuerySaveResult>> {
+  return call(`/query/${encodeURIComponent(id)}/save-to-database`, json({}), (raw) => {
+    const row = raw as Record<string, unknown> | null;
+    return {
+      scope: str(row?.scope), viewId: str(row?.viewId), name: str(row?.name),
+      dropped: (row?.dropped as unknown[] || []).filter((v): v is string => typeof v === "string"),
+    };
+  });
+}
+
+export function rateMessage(id: string, rating: "up" | "down" | null, reason?: string): Promise<Result<QueryMessage>> {
+  return call(`/query/messages/${encodeURIComponent(id)}/rating`,
+    json({ rating, ...(reason ? { reason } : {}) }), (raw) => message(raw) as QueryMessage);
+}
+
 /**
  * The sole mutation path for a virtual Query workspace.  This intentionally never falls through
  * to the native grid event transport and never sends `dataScope`: the opaque Query key is the authority.

web/src/query/queryParts.tsx

@@ -4,8 +4,33 @@ import { FolderMark } from "../customer-grid/icons";
 import { DbIcon } from "../shell/dbFrame";
 import { ASSISTANT_ROUTE } from "../shell/nav";
 import type { NavEntry } from "../shell/nav";
+import { duplicateQuery, exportQueryHref, renameQuery, saveQueryToDatabase } from "./queryApi";
 import type { SavedQuery } from "./queryApi";
 
+/** Which label of which row is being typed into. One at a time, by construction. */
+interface Editing { id: string; field: "name" | "description"; value: string; }
+
+/**
+ * ⛔ THE MENU IS `position: fixed`, AND THAT IS NOT A STYLE PREFERENCE. Its natural home,
+ * `.qy-rail-scroll`, is `overflow-y: auto`, which clips BOTH axes: an absolutely positioned menu
+ * on a row near the bottom of the list renders cut off or not at all, so the reader clicks and
+ * nothing appears. It fails worst on the rows most likely to be used, the ones you scrolled to.
+ * Fixed positioning takes it out of the scroll box entirely, which costs one measurement.
+ *
+ * ⚠ `MENU_H` is an estimate used ONLY to decide whether to flip upward near the viewport floor. It
+ * does not size anything, so being a little wrong shifts the menu rather than breaking it.
+ */
+const MENU_H = 190;
+
+function menuAnchor(button: HTMLElement): { top: number; right: number } {
+  const rect = button.getBoundingClientRect();
+  const below = rect.bottom + 4;
+  return {
+    top: below + MENU_H > window.innerHeight ? Math.max(8, rect.top - MENU_H - 4) : below,
+    right: Math.max(8, window.innerWidth - rect.right),
+  };
+}
+
 /** Query has no top-right view dropdown: the rail below IS the navigation (owner item 3). */
 export function QueryEmpty({ loaded, unnamed = 0 }: { loaded: boolean; unnamed?: number }) {
   return (
@@ -39,6 +64,43 @@ export interface QueryGroup {
   views: SavedQuery[];
 }
 
+/**
+ * ⚠ GROUPED IN THE ORDER THE DATABASES ARE GRANTED, not by artefact age. The rail is a list of
+ * DATABASES first (owner: "each View correspond to the relevant database"), so a new answer about
+ * Customers must not move the Customers heading — it appears under it. Within a database the
+ * newest is first, which is the order the server already sends.
+ *
+ * ⭐ R14 GAVE THIS LIST A SECOND HOST, which is why the loop is a function and lives HERE rather
+ * than inside `QueryPage`. The merged Assistant surface renders the same rail in its own left
+ * panel; two hosts computing "which views belong to which database" from two copies of one loop
+ * is one question with two normalizers, and the copy that drifts is the one nobody is looking at.
+ * It sits beside `QueryGroup`, the type it builds, and in a module that does NOT import the grid
+ * — a static import from `QueryPage.tsx` would pull `CustomerGrid` into the chat bundle and undo
+ * the lazy boundary the Assistant keeps around it.
+ *
+ * A view whose source database is not in `entries` is dropped: the caller's grant is the wall.
+ */
+export function queryGroups(views: SavedQuery[], entries: NavEntry[]): QueryGroup[] {
+  const byDatabase = new Map<string, SavedQuery[]>();
+  for (const view of views) {
+    const list = byDatabase.get(view.source.database);
+    if (list) list.push(view);
+    else byDatabase.set(view.source.database, [view]);
+  }
+  const out: QueryGroup[] = [];
+  for (const entry of entries) {
+    const list = byDatabase.get(entry.key);
+    if (!list || entry.kind === "group") continue;
+    out.push({
+      database: entry.key,
+      label: list[0].source.label || entry.label,
+      ...(entry.icon ? { icon: entry.icon } : {}),
+      views: list,
+    });
+  }
+  return out;
+}
+
 /**
  * ⭐⭐ OWNER ITEM 3 (2026-08-15) — GROUPED BY SOURCE DATABASE, WHICH IS THE WHOLE INSTRUCTION.
  * Verbatim: *"these AI generated query should live under the query module. And that each View
@@ -59,18 +121,75 @@ export interface QueryGroup {
  * because THIS list spans several databases and the grid's rail, by construction, cannot: the
  * grid is mounted at one scope.
  */
-export function QueryRail({ groups, activeId, onSelect, onDelete }: {
+export function QueryRail({ groups, activeId, onSelect, onDelete, onChanged }: {
   groups: QueryGroup[];
   activeId: string;
   onSelect: (id: string) => void;
   onDelete: (id: string) => void;
+  /**
+   * ⭐ The rail OWNS the rename/duplicate calls and hands the host the resulting artefact to
+   * upsert. Two hosts render this list (the standalone page and the merged Assistant surface), so
+   * putting the calls in the hosts would be one question with two implementations, and the copy
+   * that drifts is the one nobody is looking at.
+   */
+  onChanged?: (view: SavedQuery) => void;
 }) {
   // Two-click delete, in the row. A modal for "remove one of my own saved answers" is heavier
   // than the act; a single click with no confirm loses work to a mis-click on a hover control.
   const [confirming, setConfirming] = useState("");
+  const [menuFor, setMenuFor] = useState("");
+  const [anchor, setAnchor] = useState<{ top: number; right: number } | null>(null);
+  const [editing, setEditing] = useState<Editing | null>(null);
+  // ⚠ TWO STATES, NOT ONE. A refusal and a confirmation read differently and are coloured
+  // differently; sharing one slot painted "Saved as ..." in the refusal red.
+  const [problem, setProblem] = useState("");
+  const [notice, setNotice] = useState("");
+  const said = (message: string) => { setNotice(message); setProblem(""); };
+  const failed = (message: string) => { setProblem(message); setNotice(""); };
+
+  const commit = async () => {
+    if (!editing) return;
+    const current = editing;
+    setEditing(null);
+    const result = await renameQuery(current.id, current.field === "name"
+      ? { name: current.value } : { description: current.value });
+    if (!result.ok) { failed(result.message); return; }
+    said("");
+    onChanged?.(result.value);
+  };
+
+  /**
+   * ⚠ THE REPLY IS SHOWN WHETHER OR NOT ANYTHING WAS DROPPED, and the dropped half is the useful
+   * one: a database view carries no aggregation, so "sum of deal value" lands as the rows and not
+   * the sum. Saying so beats a view that looks complete and answers a different question.
+   */
+  const saveToDatabase = async (view: SavedQuery) => {
+    const result = await saveQueryToDatabase(view.id);
+    if (!result.ok) { failed(result.message); return; }
+    said(result.value.dropped.length
+      ? `Saved as "${result.value.name}". Not carried over: ${result.value.dropped.join(", ")}.`
+      : `Saved as "${result.value.name}" in this database's own views.`);
+  };
+
+  const duplicate = async (id: string) => {
+    const result = await duplicateQuery(id);
+    // ⚠ The refusal is the useful half: MAX_ARTIFACTS names its cause and the remedy, and a copy
+    // that silently did not happen is the failure mode this whole module is written against.
+    if (!result.ok) { failed(result.message); return; }
+    said("");
+    onChanged?.(result.value);
+    onSelect(result.value.id);
+  };
+
   return (
     <aside className="qy-rail" aria-label="Query views">
       <p className="qy-rail-head">Views</p>
+      {menuFor ? (
+        <button type="button" className="qy-rail-scrim" aria-label="Close menu"
+          onClick={() => setMenuFor("")} />
+      ) : null}
+      {problem ? <p className="qy-rail-problem" role="status">{problem}</p> : null}
+      {notice ? <p className="qy-rail-notice" role="status">{notice}</p> : null}
       <div className="qy-rail-scroll">
         {groups.map((group) => (
           <section className="qy-rail-group" key={group.database}>
@@ -82,29 +201,83 @@ export function QueryRail({ groups, activeId, onSelect, onDelete }: {
             </p>
             {group.views.map((view) => (
               <div className={"qy-rail-row" + (view.id === activeId ? " is-active" : "")} key={view.id}>
-                <button
-                  type="button"
-                  className="qy-rail-view"
-                  aria-current={view.id === activeId ? "true" : undefined}
-                  onClick={() => { setConfirming(""); onSelect(view.id); }}
-                  title={view.question}
-                >
-                  <span className="qy-rail-name">{view.name}</span>
-                  <span className="qy-rail-kind">{KIND_MARK[view.kind] ?? view.kind}</span>
-                </button>
+                {editing && editing.id === view.id ? (
+                  /* Inline, like the database sidebar's own rename. A window.prompt would block
+                     every other event on the page and cannot carry a placeholder or a cancel. */
+                  <form className="qy-rail-edit" onSubmit={(event) => { event.preventDefault(); void commit(); }}>
+                    <input className="qy-rail-input" autoFocus value={editing.value}
+                      aria-label={editing.field === "name" ? "View name" : "View description"}
+                      placeholder={editing.field === "name" ? "Name" : "Description"}
+                      onChange={(event) => setEditing({ ...editing, value: event.currentTarget.value })}
+                      onBlur={() => void commit()}
+                      onKeyDown={(event) => { if (event.key === "Escape") setEditing(null); }} />
+                  </form>
+                ) : (
+                  <button
+                    type="button"
+                    className="qy-rail-view"
+                    aria-current={view.id === activeId ? "true" : undefined}
+                    onClick={() => { setConfirming(""); onSelect(view.id); }}
+                    title={view.description || view.question}
+                  >
+                    <span className="qy-rail-name">{view.name}</span>
+                    <span className="qy-rail-kind">{KIND_MARK[view.kind] ?? view.kind}</span>
+                  </button>
+                )}
                 {confirming === view.id ? (
                   <button type="button" className="qy-rail-confirm"
                     onClick={() => { setConfirming(""); onDelete(view.id); }}>
                     Delete
                   </button>
                 ) : (
-                  <button type="button" className="qy-rail-del" aria-label={`Delete ${view.name}`}
-                    onClick={() => setConfirming(view.id)}>
+                  <button type="button" className="qy-rail-more" aria-haspopup="menu"
+                    aria-expanded={menuFor === view.id}
+                    aria-label={`Actions for ${view.name}`}
+                    onClick={(event) => {
+                      if (menuFor === view.id) { setMenuFor(""); return; }
+                      setAnchor(menuAnchor(event.currentTarget));
+                      setMenuFor(view.id);
+                    }}>
                     <svg viewBox="0 0 16 16" aria-hidden="true" width="13" height="13">
-                      <path d="M3.5 4.5h9M6.5 4.5V3.2h3v1.3M5 4.5l.6 8h4.8l.6-8" />
+                      <circle cx="3.2" cy="8" r="1.1" /><circle cx="8" cy="8" r="1.1" />
+                      <circle cx="12.8" cy="8" r="1.1" />
                     </svg>
                   </button>
                 )}
+                {menuFor === view.id ? (
+                  /* R20: the same vocabulary a database view offers, minus the ones that mean
+                     nothing here. Import writes rows; Share and Mark important belong to a view a
+                     team navigates; the lock family describes a cohort. What is left is what a
+                     person actually does with an answer they kept. */
+                  <div className="qy-rail-menu" role="menu"
+                    style={anchor ? { top: anchor.top, right: anchor.right } : undefined}>
+                    {/* "Export", the database sidebar's own word. Theirs then opens a format
+                        submenu; a submenu holding one row would be chrome for its own sake, so
+                        this downloads the CSV the server names. */}
+                    <a className="qy-rail-item" role="menuitem" href={exportQueryHref(view.id)}
+                      download onClick={() => setMenuFor("")}>Export</a>
+                    <button type="button" className="qy-rail-item" role="menuitem"
+                      onClick={() => { setMenuFor(""); setEditing({ id: view.id, field: "name", value: view.name }); }}>
+                      Rename
+                    </button>
+                    <button type="button" className="qy-rail-item" role="menuitem"
+                      onClick={() => { setMenuFor(""); setEditing({ id: view.id, field: "description", value: view.description }); }}>
+                      {view.description ? "Edit description" : "Add description"}
+                    </button>
+                    <button type="button" className="qy-rail-item" role="menuitem"
+                      onClick={() => { setMenuFor(""); void duplicate(view.id); }}>Duplicate</button>
+                    {/* R20's one difference from a database view's menu: this one can BECOME one. */}
+                    <button type="button" className="qy-rail-item" role="menuitem"
+                      onClick={() => { setMenuFor(""); void saveToDatabase(view); }}>
+                      Save into the database
+                    </button>
+                    <button type="button" className="qy-rail-item is-danger" role="menuitem"
+                      onClick={() => { setMenuFor(""); setConfirming(view.id); }}>Delete</button>
+                  </div>
+                ) : null}
+                {view.description && !(editing && editing.id === view.id) ? (
+                  <p className="qy-rail-note">{view.description}</p>
+                ) : null}
               </div>
             ))}
           </section>

web/src/settings/permsModel.ts

@@ -211,6 +211,14 @@ const FIELD_TYPE_TABLE: Record<FieldType, true> = {
   // and this listing cannot land in two changes. Nothing about the permissions wall treats a
   // code column specially — it is granted and hidden like any other column.
   code: true,
+  // ⭐⭐ Wave-34 (owner ruling R13) — `ai_enrich`, the same one-key edit for the same reason the
+  // four notes above give: the exhaustiveness alarm is a COMPILE error, so the union and this
+  // listing cannot land in two changes. `settings/**` is in NO lane's fence this wave, which
+  // makes it less of an exception than `json` and `code` were, not more.
+  // ⚠ Nothing about the permissions wall treats an enrichment column specially: it is granted
+  // and hidden like any other column. The thing that IS special about it (a human-edited cell is
+  // never overwritten by the agent) is a WRITE law in `core.user_tables`, not a grant.
+  ai_enrich: true,
 };
 
 export const KNOWN_FIELD_TYPES: ReadonlySet<string> = new Set(Object.keys(FIELD_TYPE_TABLE));

web/src/shell/LoginPage.tsx

@@ -1,145 +1,161 @@
-// ---------------------------------------------------------------------------
-// shell/LoginPage.tsx — X5: the branded door.
-//
-// THE CARD LANGUAGE IS `gate()`'s, DELIBERATELY (app.py:1228). Same lockup
-// (mark + "Loopable" wordmark, side by side — wave-9 I5), same 410px card with
-// ONE hairline closing all four sides (wave-10 I25a removed the gold top-rule:
-// "there is an orange line at the top of the sign-in place… it's ugly" — do not
-// reintroduce an accent edge here), same two fields and one primary button.
-// Two doors into one product must not look like two products, and this is the
-// door that outlives the other: `gate()` dies with app.py at EXIT-6.
-//
-// WHAT IT DOES NOT INHERIT: `gate()`'s `st.empty()` slot dance is a workaround
-// for Streamlit replacing elements POSITIONALLY, labelled in its own docstring
-// as something "the successor shell deletes". This is that successor. React
-// unmounts what it unmounts; there is no ghost card to chase.
-//
-// NO CLIENT-SIDE BACKOFF (X5: the server owns it). The only local rule is
-// single-flight — a second submit while one is in the air is dropped, which is
-// double-click protection, not rate limiting.
-// ---------------------------------------------------------------------------
-
-import { useState } from "react";
-import type { FormEvent } from "react";
-import { Brand } from "./Brand";
-import { login } from "./session";
-import type { SessionUser } from "./session";
-
-/** The reveal toggle the host's password field ships natively (BaseWeb's eye).
- *  Two doors, one affordance. */
-function EyeIcon({ off }: { off: boolean }) {
-  return (
-    <svg viewBox="0 0 20 20" aria-hidden="true">
-      <path d="M2.2 10s2.8-4.6 7.8-4.6S17.8 10 17.8 10 15 14.6 10 14.6 2.2 10 2.2 10z" />
-      <circle cx="10" cy="10" r="2.3" />
-      {off ? <path d="M4 16 16 4" /> : null}
-    </svg>
-  );
-}
-
-export default function LoginPage({ onSignedIn }: { onSignedIn: (user: SessionUser) => void }) {
-  const [username, setUsername] = useState("");
-  const [password, setPassword] = useState("");
-  const [error, setError] = useState("");
-  const [busy, setBusy] = useState(false);
-  const [reveal, setReveal] = useState(false);
-
-  async function submit(e: FormEvent) {
-    e.preventDefault();
-    if (busy) return;
-    setBusy(true);
-    setError("");
-    const result = await login(username, password);
-    if (result.ok) {
-      // No setBusy(false): the parent unmounts this tree on success, and
-      // flipping state on the way out is how "update on an unmounted
-      // component" warnings are born.
-      onSignedIn(result.user);
-      return;
-    }
-    setBusy(false);
-    setError(result.message);
-    setPassword("");
-  }
-
-  // An error that survives the correction is an error that reads as sticky.
-  function edit(set: (v: string) => void) {
-    return (e: { target: { value: string } }) => {
-      if (error) setError("");
-      set(e.target.value);
-    };
-  }
-
-  return (
-    <div className="login-root">
-      <div className="login-card">
-        <Brand size={44} className="login-brand" />
-
-        <form className="login-form" onSubmit={submit} noValidate>
-          {/* Labels are present and hidden, not absent. `gate()` collapses them
-              because Streamlit gives no other way to get a placeholder-only
-              field; here the label exists for assistive tech and the visual is
-              identical. */}
-          {/* No autoFocus: the other door cannot autofocus (Streamlit), and the
-              focus ring it would paint on load reads as a highlighted error on
-              an untouched form. */}
-          <label className="lp-sr-only" htmlFor="login-username">Username</label>
-          <input
-            id="login-username"
-            className="login-input"
-            name="username"
-            type="text"
-            autoComplete="username"
-            placeholder="Username"
-            value={username}
-            onChange={edit(setUsername)}
-            disabled={busy}
-            aria-invalid={error ? true : undefined}
-          />
-
-          <label className="lp-sr-only" htmlFor="login-password">Password</label>
-          <div className="login-field">
-            <input
-              id="login-password"
-              className="login-input"
-              name="password"
-              type={reveal ? "text" : "password"}
-              autoComplete="current-password"
-              placeholder="Password"
-              value={password}
-              onChange={edit(setPassword)}
-              disabled={busy}
-              aria-invalid={error ? true : undefined}
-            />
-            {/* tabIndex −1: Tab goes Username → Password → Log in; the reveal is
-                a mouse affordance, same as the host's. */}
-            <button
-              type="button"
-              className="login-eye"
-              aria-label={reveal ? "Hide password" : "Show password"}
-              onClick={() => setReveal((v) => !v)}
-              disabled={busy}
-              tabIndex={-1}
-            >
-              <EyeIcon off={reveal} />
-            </button>
-          </div>
-
-          {/* Disabled through THREE channels (the real attribute, the cursor and
-              the opacity), never opacity alone — a control that only looks dead
-              is a control that still takes the click. */}
-          <button className="login-submit" type="submit" disabled={busy}>
-            {busy ? "Signing in…" : "Log in"}
-          </button>
-        </form>
-
-        {/* The message line is ALWAYS in the layout (min-height: 1lh) so an
-            arriving error does not shove the card. `role="status"` rather than
-            "alert": polite announcement, no interruption. */}
-        <p className="login-msg" role="status" aria-live="polite">
-          {error}
-        </p>
-      </div>
-    </div>
-  );
-}
+// ---------------------------------------------------------------------------
+// shell/LoginPage.tsx — X5: the branded door.
+//
+// THE CARD LANGUAGE IS `gate()`'s, DELIBERATELY (app.py:1228). Same lockup
+// (mark + "Loopable" wordmark, side by side — wave-9 I5), same 410px card with
+// ONE hairline closing all four sides (wave-10 I25a removed the gold top-rule:
+// "there is an orange line at the top of the sign-in place… it's ugly" — do not
+// reintroduce an accent edge here), same two fields and one primary button.
+// Two doors into one product must not look like two products, and this is the
+// door that outlives the other: `gate()` dies with app.py at EXIT-6.
+//
+// WHAT IT DOES NOT INHERIT: `gate()`'s `st.empty()` slot dance is a workaround
+// for Streamlit replacing elements POSITIONALLY, labelled in its own docstring
+// as something "the successor shell deletes". This is that successor. React
+// unmounts what it unmounts; there is no ghost card to chase.
+//
+// NO CLIENT-SIDE BACKOFF (X5: the server owns it). The only local rule is
+// single-flight — a second submit while one is in the air is dropped, which is
+// double-click protection, not rate limiting.
+// ---------------------------------------------------------------------------
+
+import { useState } from "react";
+import type { FormEvent } from "react";
+import { Brand } from "./Brand";
+import { login } from "./session";
+import type { SessionUser } from "./session";
+
+/** The reveal toggle the host's password field ships natively (BaseWeb's eye).
+ *  Two doors, one affordance. */
+function EyeIcon({ off }: { off: boolean }) {
+  return (
+    <svg viewBox="0 0 20 20" aria-hidden="true">
+      <path d="M2.2 10s2.8-4.6 7.8-4.6S17.8 10 17.8 10 15 14.6 10 14.6 2.2 10 2.2 10z" />
+      <circle cx="10" cy="10" r="2.3" />
+      {off ? <path d="M4 16 16 4" /> : null}
+    </svg>
+  );
+}
+
+export default function LoginPage({ onSignedIn }: { onSignedIn: (user: SessionUser) => void }) {
+  const [username, setUsername] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [reveal, setReveal] = useState(false);
+
+  async function submit(e: FormEvent) {
+    e.preventDefault();
+    if (busy) return;
+    setBusy(true);
+    setError("");
+    const result = await login(username, password);
+    if (result.ok) {
+      // No setBusy(false): the parent unmounts this tree on success, and
+      // flipping state on the way out is how "update on an unmounted
+      // component" warnings are born.
+      onSignedIn(result.user);
+      return;
+    }
+    setBusy(false);
+    setError(result.message);
+    setPassword("");
+  }
+
+  // An error that survives the correction is an error that reads as sticky.
+  function edit(set: (v: string) => void) {
+    return (e: { target: { value: string } }) => {
+      if (error) setError("");
+      set(e.target.value);
+    };
+  }
+
+  return (
+    <div className="login-root">
+      <div className="login-card">
+        <Brand size={44} className="login-brand" />
+
+        {/* ⭐ WAVE 34 R9 — THE ONE LINE OF SELL ON THIS SCREEN. Owner, 2026-08-16:
+            *"Come up with selling points: Automate all business workflows, add it to the login
+            page. Don't make Royal Imports think im selling to other businesses though, so just
+            add a catchy slogan."*
+
+            ⛔ THE SECOND SENTENCE IS THE HARD CONSTRAINT AND IT IS EASY TO MISS. Royal Imports is
+            tenant #0 and their team signs in here every day; a line that reads like marketing
+            copy aimed at OTHER companies tells them, correctly, that they are looking at a demo
+            of a product being sold elsewhere. So this is a PROMISE ABOUT THEIR OWN TOOL, phrased
+            with no audience in it: no "for teams", no "businesses", no "your company", no plan
+            names, no call to action. "Every workflow, automated." is a claim the app makes about
+            itself, which happens to also be the selling point.
+
+            ⚠ No dash of any kind (R6). A slogan is exactly where an em dash wants to appear. */}
+        <p className="login-tagline">Every workflow, automated.</p>
+
+        <form className="login-form" onSubmit={submit} noValidate>
+          {/* Labels are present and hidden, not absent. `gate()` collapses them
+              because Streamlit gives no other way to get a placeholder-only
+              field; here the label exists for assistive tech and the visual is
+              identical. */}
+          {/* No autoFocus: the other door cannot autofocus (Streamlit), and the
+              focus ring it would paint on load reads as a highlighted error on
+              an untouched form. */}
+          <label className="lp-sr-only" htmlFor="login-username">Username</label>
+          <input
+            id="login-username"
+            className="login-input"
+            name="username"
+            type="text"
+            autoComplete="username"
+            placeholder="Username"
+            value={username}
+            onChange={edit(setUsername)}
+            disabled={busy}
+            aria-invalid={error ? true : undefined}
+          />
+
+          <label className="lp-sr-only" htmlFor="login-password">Password</label>
+          <div className="login-field">
+            <input
+              id="login-password"
+              className="login-input"
+              name="password"
+              type={reveal ? "text" : "password"}
+              autoComplete="current-password"
+              placeholder="Password"
+              value={password}
+              onChange={edit(setPassword)}
+              disabled={busy}
+              aria-invalid={error ? true : undefined}
+            />
+            {/* tabIndex −1: Tab goes Username → Password → Log in; the reveal is
+                a mouse affordance, same as the host's. */}
+            <button
+              type="button"
+              className="login-eye"
+              aria-label={reveal ? "Hide password" : "Show password"}
+              onClick={() => setReveal((v) => !v)}
+              disabled={busy}
+              tabIndex={-1}
+            >
+              <EyeIcon off={reveal} />
+            </button>
+          </div>
+
+          {/* Disabled through THREE channels (the real attribute, the cursor and
+              the opacity), never opacity alone — a control that only looks dead
+              is a control that still takes the click. */}
+          <button className="login-submit" type="submit" disabled={busy}>
+            {busy ? "Signing in…" : "Log in"}
+          </button>
+        </form>
+
+        {/* The message line is ALWAYS in the layout (min-height: 1lh) so an
+            arriving error does not shove the card. `role="status"` rather than
+            "alert": polite announcement, no interruption. */}
+        <p className="login-msg" role="status" aria-live="polite">
+          {error}
+        </p>
+      </div>
+    </div>
+  );
+}

web/src/shell/NavExtras.tsx

@@ -12,8 +12,8 @@
 
 import { useEffect, useRef, useState } from "react";
 import type { ReactNode } from "react";
-import { fetchSchema } from "./nav";
-import type { NavFolder, SchemaPayload, TableFootprint } from "./nav";
+import { fetchSchema, importantBadge } from "./nav";
+import type { NavFolder, NavImportant, SchemaPayload, TableFootprint } from "./nav";
 // ⚠ WAVE 19 R8 / C1 — IMPORTED, NEVER REDEFINED, and the contract says so in as
 // many words ("Shapes/tones = the grid's existing vocabulary verbatim (12
 // shapes, 5 tones); B imports, never redefines"). A second copy of this
@@ -735,6 +735,7 @@ export function CreateNewRow({
 export function FolderHead({
   folder,
   count,
+  important,
   open,
   collapsed,
   onToggle,
@@ -745,6 +746,10 @@ export function FolderHead({
 }: {
   folder: NavFolder;
   count: number;
+  /** ⭐⭐ WAVE 34 R1 / C1 — the SUM of this folder's members' mark-important numbers, set by
+   *  `foldNav` for a CLOSED folder only. Absent ⇒ draw nothing, which is both the open case and
+   *  the far more common "nobody marked anything in here" case. */
+  important?: NavImportant;
   open: boolean;
   collapsed: boolean;
   onToggle: () => void;
@@ -785,6 +790,22 @@ export function FolderHead({
         <FolderIcon />
         <span className="shell-nav-label">{folder.name}</span>
         <span className="shell-nav-foldercount">{count}</span>
+        {/* ⭐⭐ WAVE 34 R1 / C1 — *"a minimized folder should show the SUM of the numbers"*.
+            ⛔ BESIDE `count`, NEVER INSTEAD OF IT. `count` is how many BLOCKS the folder holds and
+            has meant that since wave 14; this is a sum of RECORDS. Collapsing them into one slot
+            would make the same numeral mean two things depending on whether anything inside had
+            ever been marked, which is worse than two numbers.
+            ⚠ The `title` is what tells them apart for a reader who sees two numerals; the glyph
+            cannot, and DESIGN.md's "never over-explain" law is about copy on screen, not about a
+            tooltip that only appears on hover. */}
+        {importantBadge(important) ? (
+          <span
+            className="shell-nav-count"
+            title={`${importantBadge(important)} in the important views inside this folder`}
+          >
+            {importantBadge(important)}
+          </span>
+        ) : null}
       </button>
       <button
         type="button"

web/src/shell/nav.ts

@@ -113,6 +113,80 @@ export interface NavPage {
    * never a control that silently disappears.
    */
   locked?: boolean;
+  /**
+   * ⭐⭐ WAVE 34 (ruling R1, contract C1) — HOW MANY RECORDS THIS DATABASE'S **IMPORTANT** VIEWS
+   * RESOLVE TO.
+   *
+   * R1 moves the mark-important number OFF the view sidebar's header and INTO the database
+   * navigation, and that move is what forces this onto the wire: the flyout has no grid, so the
+   * client cannot compute it the way `CustomerGrid::importantTotal` does.
+   *
+   * ⛔ THE THREE FIELDS ARE NOT REDUNDANT AND `partial` IS THE LOAD-BEARING ONE. `marked` counts
+   * VIEWS, `counted` counts RECORDS, and `partial` says at least one marked view could not be
+   * counted at all. `/nav` holds a rows-free projection, so a FILTERED view is uncountable there
+   * by construction; a sum that silently skipped those would be short by an unknown amount, which
+   * is exactly the silent absence `D-205` exists to end, one level up.
+   *
+   * ⚠ PER USER, never tenant-wide. Views live in a per-database bucket split by username, so the
+   * same database answers `{marked: 1, counted: 13}` for one account and `{marked: 0}` for
+   * another. Measured on tenant #0: `leadership` vs `admin` on `customer_data`.
+   *
+   * ⚠ ABSENT means "not a database, or the server could not read its views" — the second case is
+   * named in `degraded`, exactly like the `ut_*` merge. It does NOT mean zero: a database with
+   * nothing marked ships `{marked: 0, counted: 0, partial: false}`, because a key a consumer has
+   * to test for is a key a consumer forgets to test for.
+   */
+  important?: NavImportant;
+}
+
+/** C1's per-database important payload. See `NavPage.important` for why all three fields exist. */
+export interface NavImportant {
+  marked: number;
+  counted: number;
+  partial: boolean;
+}
+
+/**
+ * The wire's important block, validated like every other flag on this payload: prune, never
+ * invent. A malformed one reads as ABSENT, which renders no badge — the safe direction, because
+ * the alternative is a confident number derived from junk.
+ */
+export function parseNavImportant(raw: unknown): NavImportant | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const r = raw as { marked?: unknown; counted?: unknown; partial?: unknown };
+  const int = (v: unknown): number | null =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : null;
+  const marked = int(r.marked);
+  const counted = int(r.counted);
+  if (marked === null || counted === null) return undefined;
+  // `=== true`, the same strictness `manage`/`canDelete`/`locked` use: a drifted server sending a
+  // truthy string must not turn a real count into a `+`.
+  return { marked, counted, partial: r.partial === true };
+}
+
+/**
+ * ⭐⭐ THE BADGE TEXT, AND IT IS ONE FUNCTION BECAUSE THERE ARE TWO CALLERS.
+ *
+ * A database row and a COLLAPSED FOLDER both draw this number, from different inputs (one entry's
+ * block, a sum over a folder's members). Two renderers deciding "is there a number here" by their
+ * own rules is [[one-question-two-normalizers]] with the answer on screen, so the rule lives here
+ * and both call it.
+ *
+ * The four cases, and the third is the one the ticket calls out by name:
+ *   · nothing marked        -> `null`. R1's own clause: NOT a zero. Most databases are this.
+ *   · a real count          -> the number, plus `+` when at least one view could not be counted.
+ *   · nothing countable     -> `"+"` ALONE. ⛔ NEVER `"0+"`: that string is `D-205` itself, the
+ *                              thing the owner photographed, and rendering it here would be the
+ *                              same defect moved into the nav. A bare `+` says "there is something
+ *                              here we could not count" without claiming the something is zero.
+ *   · a genuine zero        -> `"0"`. A marked view that matches no records is a fact worth
+ *                              seeing, and it is distinguishable from the case above because
+ *                              nothing was skipped.
+ */
+export function importantBadge(imp?: NavImportant): string | null {
+  if (!imp || imp.marked <= 0) return null;
+  if (imp.counted > 0) return `${imp.counted}${imp.partial ? "+" : ""}`;
+  return imp.partial ? "+" : "0";
 }
 
 /**
@@ -190,6 +264,8 @@ export function parsePages(body: unknown): NavPage[] {
       // ⭐ WAVE 27 item 3 / C9 — same `=== true` strictness. A locked database is a padlock
       // beside a name, so a drifted server sending a truthy string must not paint one.
       ...(p.locked === true ? { locked: true } : {}),
+      // ⭐⭐ WAVE 34 R1 / C1 — the important block, validated on the way in like the icon.
+      ...(parseNavImportant(p.important) ? { important: parseNavImportant(p.important)! } : {}),
     });
   }
   return out;
@@ -583,9 +659,22 @@ export async function deleteTable(key: string): Promise<{ ok: boolean; error?: s
   }
 }
 
-/** One rendered row of the folded nav: a folder head, or an entry (optionally inside one). */
+/** One rendered row of the folded nav: a folder head, or an entry (optionally inside one).
+ *
+ *  ⚠ `count` and `important` are DIFFERENT NUMBERS and neither is a version of the other.
+ *  `count` is how many BLOCKS the folder holds (a top-level entry plus its depth-1 children counts
+ *  as one), which is the number that has been drawn beside a folder name since wave 14.
+ *  `important` is R1's aggregate over its members' record counts. Putting them in one slot would
+ *  make a folder head say "3" and mean two different things depending on whether anything inside
+ *  it was ever marked. */
 export type NavRow =
-  | { kind: "folder"; folder: NavFolder; count: number; open: boolean }
+  | {
+      kind: "folder";
+      folder: NavFolder;
+      count: number;
+      open: boolean;
+      important?: NavImportant;
+    }
   | { kind: "entry"; entry: NavEntry; folderId?: string };
 
 /**
@@ -628,10 +717,40 @@ export function foldNav(
     for (const c of b.children)
       out.push({ kind: "entry", entry: c, ...(folderId ? { folderId } : {}) });
   };
+  // ⭐⭐ WAVE 34 R1 / C1 — a COLLAPSED folder carries the SUM of its members' numbers.
+  //
+  // ⛔ SUMMED FROM THE SAME `members` ARRAY THAT PRODUCES `count`, in the same pass, and that is
+  // the whole correctness of it. The alternative — a second lookup in `Shell.tsx` keyed off
+  // `dbEntries` — would derive the number from one list while the rows came from another, which is
+  // the defect `shell.test.ts` already pins for `count` ("a folder whose only member was filtered
+  // out counts 0, not 1"). It bites hardest during SEARCH, when the caller passes
+  // `EMPTY_NAV_PREFS` and no folder renders at all.
+  //
+  // ⚠ CHILDREN CONTRIBUTE. A block is a head plus its depth-1 children, and a child is its own
+  // database with its own marked views, so the head's number would be short without them.
+  const aggregate = (blocks: Block[]): NavImportant | undefined => {
+    let marked = 0;
+    let counted = 0;
+    let partial = false;
+    for (const b of blocks) {
+      for (const e of [b.head, ...b.children]) {
+        if (!e.important) continue;
+        marked += e.important.marked;
+        counted += e.important.counted;
+        partial = partial || e.important.partial;
+      }
+    }
+    return marked > 0 ? { marked, counted, partial } : undefined;
+  };
   for (const f of prefs.folders) {
     const members = byFolder.get(f.id) ?? [];
     const open = !closed.has(f.id);
-    out.push({ kind: "folder", folder: f, count: members.length, open });
+    // ⛔ ONLY WHEN CLOSED. An open folder shows its members' own numbers directly underneath, so a
+    // head number there would be the same records counted twice on one screen — the ticket's
+    // "an expanded one does not double-count", enforced at the source rather than in the renderer.
+    const imp = open ? undefined : aggregate(members);
+    out.push({ kind: "folder", folder: f, count: members.length, open,
+               ...(imp ? { important: imp } : {}) });
     if (open) for (const b of members) emit(b, f.id);
   }
   for (const b of loose) emit(b);
@@ -738,6 +857,11 @@ export interface NavEntry {
   /** ⭐ WAVE 27 item 3 / C9 — a LOCKED database: no new records, fields still fine (see the
    *  long note on `NavPage.locked`). Absent ⇒ unlocked. */
   locked?: boolean;
+  /** ⭐⭐ WAVE 34 R1 / C1 — the mark-important counts (see the long note on `NavPage.important`).
+   *  THE SECOND HALF of that flag, and it is here for the reason `canDelete` and `locked` are:
+   *  a value parsed onto the payload and dropped in `shapeNav` reaches no row anybody renders,
+   *  which is precisely how wave 20 shipped four wirings that went nowhere. */
+  important?: NavImportant;
   /**
    * ⭐ WAVE 25 (D-54) — THIS ROW IS A SURFACE, NOT A DATABASE.
    *
@@ -897,6 +1021,13 @@ export function shapeNav(pages: NavPage[], appBase: string): NavEntry[] {
       // ⭐ WAVE 27 item 3 / C9 — THE SECOND HALF, for the reason stated directly above: a flag
       // parsed onto the payload and dropped here reaches no row anybody renders.
       ...(p.locked ? { locked: true } : {}),
+      // ⭐⭐ WAVE 34 R1 / C1 — THE SECOND HALF AGAIN, AND IT WAS MISSED ON THE FIRST TRY.
+      // `parsePages` validated `important` onto the payload and this function dropped it, so the
+      // number reached the wire, survived validation, and never reached a row. The `shapeNav`
+      // leg in `shell.test.ts` is what found it, minutes after being written; the two comments
+      // above say this exact thing about two earlier flags and it happened anyway, which is the
+      // argument for the leg rather than for the comment.
+      ...(p.important ? { important: p.important } : {}),
       // ⭐ D-54 — the databases/surfaces split, stamped at the ONE place rows are built.
       // Not `kind`: a surface is `native` (this tree renders it) and so are the grids, so the
       // existing discriminator cannot answer this question and widening it would have made
@@ -1057,8 +1188,59 @@ export const LEGACY_ROUTES: Readonly<Record<string, string>> = {
    * Home — a worse answer to the same question.
    */
   "ai-agent": ASSISTANT_ROUTE,
+  /**
+   * ⭐⭐ WAVE 34 (ruling R14, contract C2) — QUERY IS MERGED INTO THE ASSISTANT.
+   *
+   * Owner: *"Combine the AI assistant module AND the Query module. In the secondary navigation at
+   * the top, just above '+ New chat', an easily accessible toggle between Chat / Query."* So there
+   * is ONE route and one rail row, and `#/query` is a hash people hold: bookmarked, pasted, and
+   * left in an open tab since wave 32.
+   *
+   * ⚠ THIS ENTRY IS THE INSTANT-RESOLVE HALF ONLY. It stops the frame rendering Home for the one
+   * paint before the URL is rewritten; `REWRITTEN_ROUTES` below is what actually puts
+   * `?mode=query` on the address bar, and the Query LIST only opens because of that.
+   */
+  [QUERY_ROUTE]: ASSISTANT_ROUTE,
+};
+
+/**
+ * ⭐⭐ WAVE 34 R14 / C2 — retired hashes the shell REWRITES rather than merely resolves.
+ *
+ * ⛔ WHY THIS IS NOT JUST ANOTHER `LEGACY_ROUTES` ROW. A legacy row is an internal translation:
+ * the address bar keeps saying `#/ai-agent` and nothing downstream cares. Query cannot work that
+ * way, because the merged surface decides WHICH LIST to show from `?mode=` on the hash — so a
+ * resolve that never touched the URL would land the reader on the Chat list, which is the opposite
+ * of what their bookmark asked for.
+ */
+export const REWRITTEN_ROUTES: Readonly<Record<string, string>> = {
+  [QUERY_ROUTE]: `${ASSISTANT_ROUTE}?mode=query`,
 };
 
+/**
+ * The ROUTE KEY in a hash, with any query string or nested fragment stripped.
+ *
+ * ⛔ THE BUG THIS EXISTS TO PREVENT WAS REPORTED BY LANE D BEFORE IT COULD HAPPEN (post D-1), and
+ * it is invisible until you try it: the shell read the WHOLE remainder of the hash as the key, so
+ * `#/assistant?mode=query` resolved to the key `assistant?mode=query`, matched no route, and fell
+ * through to Home. The redirect below would have "worked" — right URL, wrong screen — and every
+ * gate keyed on the redirect's target string would have been green.
+ */
+export function routeKeyOf(hash: string): string {
+  return hash.replace(/^#\/?/, "").split("?")[0].split("#")[0];
+}
+
+/**
+ * The hash this one must BECOME, or null when it is already right.
+ *
+ * ⚠ RETURNS NULL FOR AN ALREADY-REWRITTEN HASH, which is the whole loop-safety argument: writing
+ * `location.hash` fires `hashchange`, the caller asks again, the key is now `assistant`, and this
+ * answers null. One rewrite, never a cycle.
+ */
+export function rewrittenHash(hash: string): string | null {
+  const target = REWRITTEN_ROUTES[routeKeyOf(hash)];
+  return target ? `#/${target}` : null;
+}
+
 /** The current key for a hash that may name a retired one. Identity for everything else. */
 export function canonicalRoute(route: string): string {
   return LEGACY_ROUTES[route] ?? route;

web/src/shell/navExtras.css

@@ -61,6 +61,19 @@
   display: none;
 }
 
+/* ⭐ WAVE 34 R15 — "then a subtle line separation". SUBTLE is the whole specification, so this
+   is a hairline at the rail's own border token and nothing else: no margin collapse games, no
+   inset, no second colour. It groups Home+Inbox / Assistant+Agents / Database+Connectors.
+   ⚠ It is a direct child of `.shell-nav`, which is what makes the `is-rail-loading` rule above
+   hide it with the rows. Do not wrap the groups in `<div>`s to get the same look: that would put
+   the rows one level deeper and the `> *` in that selector would stop reaching them, silently
+   bringing back the two-row-states defect the whole rule exists to prevent. */
+.shell-nav-sep {
+  height: 1px;
+  margin: 6px 8px;
+  background: var(--lp-line);
+}
+
 .shell-rail-skeleton {
   display: flex;
   flex-direction: column;
@@ -193,6 +206,43 @@
   font-variant-numeric: tabular-nums;
 }
 
+/* ── ⭐⭐ WAVE 34 R1 / contract C1: the mark-important number, in the database list ──────────
+   Owner, 2026-08-16: *"the mark important number should be moved into the database navigation,
+   so when we click database, it shows the list of the databases, each showing their number"* and
+   *"we don't need the important word, just show the number, make it smaller"*.
+
+   Drawn by TWO callers: a database row (`Shell.tsx`'s flyout) and a COLLAPSED folder head
+   (`FolderHead` above), both through `nav.ts::importantBadge` so the "is there a number here"
+   rule is written once.
+
+   ⚠ `--lp-fs-4xs` (0.625rem = 10px against the 17px root), NOT `--lp-fs-3xs` (11.69px) which the
+   sibling `.shell-nav-foldercount` uses. Two reasons and the first is the ruling: R1 says SMALLER,
+   and a badge at the same size as the count already beside it is not smaller, it is a second copy.
+   The second is arithmetic: C1 asks for <=11px and `--lp-fs-3xs` computes to 11.69px, which is
+   over. The font gate enforces token-or-nothing, never a computed ceiling, so nothing in code
+   catches picking the wrong token; it is checked here instead.
+
+   ⚠ `margin-left: auto` ON THE ROW, RESET INSIDE A FOLDER HEAD. A database row needs the number
+   at the right edge so a list of them reads as a column; a folder head already gives `auto` to
+   `.shell-nav-foldercount`, and a SECOND `auto` there splits the free space between the two
+   numbers and pushes them apart with a gap in the middle. Hence the adjacency rule below. */
+.shell-nav-count {
+  flex: none;
+  margin-left: auto;
+  padding-left: 6px;
+  font-size: var(--lp-fs-4xs);
+  font-weight: 400;
+  color: var(--lp-muted);
+  font-variant-numeric: tabular-nums;
+  /* A row is a flex line with an ellipsised label; the number must never be the thing that
+     shrinks, or a "13" becomes a "1" with no way to tell. */
+  white-space: nowrap;
+}
+/* Inside a folder head the number follows the member count, which already holds the right edge. */
+.shell-nav-foldercount + .shell-nav-count {
+  margin-left: 0;
+}
+
 /* ── wave 14 C-NAVFOLD: drag placement (items 4/6) ───────────────────────── */
 
 .shell-nav-row.is-dragging {