brainpalace-cli 26.7.1__tar.gz → 26.7.2__tar.gz

{brainpalace_cli-26.7.1 → brainpalace_cli-26.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainpalace-cli
-Version: 26.7.1
+Version: 26.7.2
 Summary: BrainPalace CLI - Command-line interface for managing AI agent memory and knowledge retrieval
 License: MIT
 Keywords: brainpalace,rag,cli,ai-memory,llm-memory,semantic-search,ai-agent,claude-code,agent-memory

{brainpalace_cli-26.7.1 → brainpalace_cli-26.7.2}/brainpalace_cli/ai_guidance.py

@@ -43,9 +43,11 @@ _SKILL_FRONTMATTER = """\
 name: using-brainpalace
 description: |
   Expert BrainPalace skill for document search with BM25 keyword, semantic
-  vector, hybrid, graph, and multi retrieval modes.
+  vector, hybrid, graph, multi, compute, scan, absence, and timeline
+  retrieval modes.
   Use when asked to "search documentation", "query domain", "find in docs",
   "bm25 search", "hybrid search", "semantic search", "graph search", "multi search",
+  "compute query", "scan sessions", "absence query", "timeline query",
   "find dependencies", "code relationships", "searching knowledge base",
   "querying indexed documents", "finding code references", "exploring codebase",
   "what calls this function", "find imports", "trace dependencies",

{brainpalace_cli-26.7.1 → brainpalace_cli-26.7.2}/brainpalace_cli/client/api_client.py

@@ -100,6 +100,31 @@ class ScanRow:
     score: float = 0.0
 
 
+@dataclass
+class AbsenceRow:
+    """One absence-mode row (subject present under one partition, absent under
+    another)."""
+
+    label: str
+    present_in: str
+    absent_from: str
+    partition: str
+    score: float = 0.0
+
+
+@dataclass
+class TimelineRow:
+    """One timeline-mode row (an entity's edge at a point in its history)."""
+
+    subject: str
+    predicate: str
+    object: str
+    valid_from: str | None = None
+    valid_until: str | None = None
+    valid: bool = True
+    score: float = 0.0
+
+
 @dataclass
 class QueryResponse:
     """Query response with results."""
@@ -109,6 +134,8 @@ class QueryResponse:
     total_results: int
     compute: list[ComputeRow] | None = None
     scan: list[ScanRow] | None = None
+    absence: list[AbsenceRow] | None = None
+    timeline: list[TimelineRow] | None = None
     index_blocked: dict[str, Any] | None = None
 
 
@@ -360,12 +387,44 @@ class DocServeClient:
                 for r in raw_scan
             ]
 
+        raw_absence = data.get("absence")
+        absence_rows: list[AbsenceRow] | None = None
+        if raw_absence is not None:
+            absence_rows = [
+                AbsenceRow(
+                    label=str(r.get("label", "")),
+                    present_in=str(r.get("present_in", "")),
+                    absent_from=str(r.get("absent_from", "")),
+                    partition=str(r.get("partition", "")),
+                    score=float(r.get("score", 0.0)),
+                )
+                for r in raw_absence
+            ]
+
+        raw_timeline = data.get("timeline")
+        timeline_rows: list[TimelineRow] | None = None
+        if raw_timeline is not None:
+            timeline_rows = [
+                TimelineRow(
+                    subject=str(r.get("subject", "")),
+                    predicate=str(r.get("predicate", "")),
+                    object=str(r.get("object", "")),
+                    valid_from=r.get("valid_from"),
+                    valid_until=r.get("valid_until"),
+                    valid=bool(r.get("valid", r.get("valid_until") is None)),
+                    score=float(r.get("score", 0.0)),
+                )
+                for r in raw_timeline
+            ]
+
         return QueryResponse(
             results=results,
             query_time_ms=data.get("query_time_ms", 0.0),
             total_results=data.get("total_results", len(results)),
             compute=compute_rows,
             scan=scan_rows,
+            absence=absence_rows,
+            timeline=timeline_rows,
             index_blocked=data.get("index_blocked"),
         )
 

{brainpalace_cli-26.7.1 → brainpalace_cli-26.7.2}/brainpalace_cli/commands/hook.py

@@ -171,7 +171,21 @@ def hook_userpromptsubmit() -> None:
 # Query modes a guarded subagent prompt must reference to prove it will search
 # via BrainPalace. Mirrors the modes accepted by `brainpalace query --mode` and
 # the MCP/skill `query` tool's `mode` argument.
-_GUARD_QUERY_MODES = ("hybrid", "bm25", "vector", "graph", "multi")
+# The 9 query modes. Kept a CLI-local literal (NOT imported from the server enum)
+# because hook.py is a fast, server-import-free shim loaded on every CLI call; the
+# contract_parity gate (tests/doc_sync/test_mode_parity.py + lint:doc-sync) holds
+# this tuple equal to brainpalace_server.models.query.QueryMode.
+_GUARD_QUERY_MODES = (
+    "hybrid",
+    "bm25",
+    "vector",
+    "graph",
+    "multi",
+    "compute",
+    "scan",
+    "absence",
+    "timeline",
+)
 _GUARD_MODES_ALT = "|".join(_GUARD_QUERY_MODES)
 # A prompt proves BrainPalace search two equivalent ways:
 #   CLI form — `brainpalace query ... --mode <mode>`
@@ -217,7 +231,7 @@ _GUARD_SEARCH_INTENT_RE = re.compile(
 )
 _GUARD_DENY_REASON = (
     "Subagent prompt must instruct BrainPalace search: include "
-    "`brainpalace query ... --mode <hybrid|bm25|vector|graph|multi>`. "
+    f"`brainpalace query ... --mode <{_GUARD_MODES_ALT}>`. "
     "If genuinely exempt, open the prompt with a line "
     "`# BRAINPALACE_EXEMPT: <reason of 20+ chars>`."
 )

{brainpalace_cli-26.7.1 → brainpalace_cli-26.7.2}/brainpalace_cli/commands/query.py

@@ -86,7 +86,17 @@ def _maybe_print_ai_hint() -> None:
     "--mode",
     default="hybrid",
     type=click.Choice(
-        ["vector", "bm25", "hybrid", "graph", "multi", "compute", "scan"],
+        [
+            "vector",
+            "bm25",
+            "hybrid",
+            "graph",
+            "multi",
+            "compute",
+            "scan",
+            "absence",
+            "timeline",
+        ],
         case_sensitive=False,
     ),
     help=(
@@ -98,7 +108,14 @@ def _maybe_print_ai_hint() -> None:
         "unless record extraction has populated them), "
         "'scan' (deterministic term counts over the archived session "
         "transcripts; 'which week did I mention X most'; empty when the "
-        "session archive is off). Default: hybrid."
+        "session archive is off), "
+        "'absence' (anti-join over typed records: subjects present under one "
+        "partition value but absent under another, e.g. 'distance but not "
+        "duration'; empty when no two stored values resolve), "
+        "'timeline' (walk an entity's edge-validity/supersession history: "
+        "how a belief/fact evolved, e.g. 'how did the auth decision evolve'; "
+        "empty when the named entity resolves to no graph node), "
+        "Default: hybrid."
     ),
 )
 @click.option(
@@ -237,6 +254,18 @@ def query_command(
                     import dataclasses
 
                     output["scan"] = [dataclasses.asdict(s) for s in response.scan]
+                if response.absence is not None:
+                    import dataclasses
+
+                    output["absence"] = [
+                        dataclasses.asdict(a) for a in response.absence
+                    ]
+                if response.timeline is not None:
+                    import dataclasses
+
+                    output["timeline"] = [
+                        dataclasses.asdict(t) for t in response.timeline
+                    ]
                 blocked = getattr(response, "index_blocked", None)
                 if blocked is not None:
                     output["index_blocked"] = blocked
@@ -290,6 +319,46 @@ def query_command(
                 _maybe_print_ai_hint()
                 return
 
+            # Absence mode: print "in X, not Y" lines
+            if response.absence is not None:
+                console.print(
+                    f"\n[bold]Query:[/] {query_text}\n"
+                    f"[dim]Absence results in {response.query_time_ms:.1f}ms[/]\n"
+                )
+                if not response.absence:
+                    console.print(
+                        "[yellow]No gaps found (no two stored values resolved, "
+                        "or nothing is absent).[/]"
+                    )
+                else:
+                    for absence_row in response.absence:
+                        console.print(
+                            f"{absence_row.label}  (in {absence_row.present_in}, "
+                            f"not {absence_row.absent_from})"
+                        )
+                _maybe_print_ai_hint()
+                return
+
+            # Timeline mode: print entity edge-validity history lines
+            if response.timeline is not None:
+                if not response.timeline:
+                    # M3: empty has two causes — no entity parsed from the query,
+                    # or the entity resolved to no node / no edges. Cover both.
+                    console.print(
+                        "[yellow]No history found — the query named no "
+                        "recognizable entity, or the entity resolved to no graph "
+                        "node / has no edges. Try 'history of <name>'.[/]"
+                    )
+                else:
+                    for tl_row in response.timeline:
+                        mark = "[green]✓[/]" if tl_row.valid else "[dim]✗[/]"
+                        until = tl_row.valid_until or "now"
+                        console.print(
+                            f"{mark} {tl_row.subject} —{tl_row.predicate}→ "
+                            f"{tl_row.object}  [{tl_row.valid_from or '?'} … {until}]"
+                        )
+                return
+
             # Display header
             console.print(
                 f"\n[bold]Query:[/] {query_text}\n"

{brainpalace_cli-26.7.1 → brainpalace_cli-26.7.2}/brainpalace_cli/commands/sync_docs.py

@@ -19,6 +19,7 @@ from brainpalace_cli.doc_sync.checkers.provider_tables import ProviderTablesChec
 from brainpalace_cli.doc_sync.checkers.skills import SkillsChecker
 from brainpalace_cli.doc_sync.generator import (
     regenerate_mcp_tools,
+    regenerate_modes_block,
     regenerate_provider_tables,
     regenerate_query_modes,
 )
@@ -43,6 +44,14 @@ _PLUGIN = _REPO_ROOT / "brainpalace-plugin"
 # Roots scanned for provider/install GENERATED blocks (whole plugin tree + docs +
 # both READMEs). Recursive — a new doc that adds a block is covered automatically.
 _PROVIDER_DOC_ROOTS = [_PLUGIN, _DOCS, _REPO_ROOT / "README.md"]
+# Doc -> mode-table style, for the additional (non-canonical) GENERATED:modes
+# blocks: each doc keeps its own richer column shape, all rendered from the same
+# MODE_META single source (see doc_sync/mode_meta.py).
+_MODES_DOC_STYLES: dict[Path, str] = {
+    _REPO_ROOT / "README.md": "grid",
+    _DOCS / "API_REFERENCE.md": "table",
+    _DOCS / "USER_GUIDE.md": "commands",
+}
 
 
 def _require_repo() -> None:
@@ -77,7 +86,7 @@ def _provider_doc_files() -> list[Path]:
 def _checkers() -> list[Any]:
     return [
         CliCommandsChecker(docs_dir=_DOCS_DIR),
-        ModesChecker(docs_dir=_DOCS_DIR),
+        ModesChecker(docs_dir=_DOCS_DIR, targets=_MODES_DOC_STYLES),
         SkillsChecker(
             skills_dir=_SKILLS_DIR,
             docs_dir=_DOCS_DIR,
@@ -131,6 +140,9 @@ def sync_docs_command(mode_check: bool, mode_fix: bool) -> None:
         regenerate_mcp_tools(_DOCS_DIR / MCP_CANONICAL, snap.mcp_tools)
         for doc in _provider_doc_files():
             regenerate_provider_tables(doc, snap)
+        for doc, style in _MODES_DOC_STYLES.items():
+            if doc.exists():
+                regenerate_modes_block(doc, snap.modes, style)
         prose_needed = run_fix(checkers, snap)
         for item in prose_needed:
             click.echo(

{brainpalace_cli-26.7.1 → brainpalace_cli-26.7.2}/brainpalace_cli/data/ai_guidance.md

@@ -53,6 +53,8 @@ Pick `--mode` for any inline search. Default to `hybrid` when unsure.
 | Maximum recall (ALL usages / references) | `--mode multi` |
 | Aggregation ("how many", "total", "which week had most") | `--mode compute` |
 | Own-utterance history ("which week did I mention X") | `--mode scan` |
+| Anti-join over typed records ("X but not Y") | `--mode absence` |
+| Belief/fact evolution ("how did X evolve", "history of X") | `--mode timeline` |
 
 Common flags: `--top-k N` (default 5), `--threshold F` (default 0.3),
 `--alpha F` (hybrid balance, 0=BM25…1=Vector, default 0.5), `--language CODE`
@@ -97,18 +99,7 @@ Per-result keys are `text`, `source`, `score`, `chunk_id` — there is NO
 `{"error": ...}` (with `detail`/`hint`) and a non-zero exit, with **no**
 `results` key. Never append `2>/dev/null` — diagnostics go to stderr. A
 top-level `index_blocked` object means the index is STALE (paused over
-budget) — never auto-approve.
-
-```bash
-brainpalace query "..." --mode hybrid --top-k 8 --json | python3 -c "
-import json, sys
-d = json.load(sys.stdin)
-if 'error' in d: sys.exit('brainpalace error: %s' % d['error'])
-for r in d['results']:
-    print(r['source'], r['score'])
-    print(r['text'][:500])
-"
-```
+budget) — never auto-approve. (Runnable parsing snippet: `--tier full`.)
 
 **Allowed Glob/Grep cases (NOT codebase search):** searching inside a single file
 BrainPalace already returned; non-indexed paths (`~/.claude/`, `~/.config/`,
@@ -134,6 +125,21 @@ call the `ai_guide` tool).
 
 ---
 
+## Parsing `--json` Output — runnable example
+
+```bash
+brainpalace query "..." --mode hybrid --top-k 8 --json | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+if 'error' in d: sys.exit('brainpalace error: %s' % d['error'])
+for r in d['results']:
+    print(r['source'], r['score'])
+    print(r['text'][:500])
+"
+```
+
+---
+
 ## Paused (Budget-Blocked) Indexing
 
 Query output (CLI `--json` and the MCP `query` tool) may carry a top-level
@@ -225,6 +231,38 @@ is off or no term parses. Tie-break with compute: typed record metric wins.
 
 ---
 
+## Absence Mode — Anti-Join over Typed Records
+
+`--mode absence` — anti-join over typed records: subjects present under one
+partition value (`metric`/`source`/`domain`) but absent under another
+("distance but not duration"). Deterministic, no LLM. Empty when no two
+stored values resolve, or nothing qualifies (e.g. no records exist).
+Auto-routed after compute and scan — a query carrying a compute or scan tell
+alongside an absence tell routes there instead (e.g. "did I discuss gmail but
+not session" is scan, not absence, because it carries "did i discuss").
+
+**`--json` contract for absence:** `results` is always `[]`; rows live under
+`absence`. Each row: `label` (the missing subject), `present_in`,
+`absent_from`, `partition` (`metric`/`source`/`domain`), `score` (reserved,
+always `0.0`).
+
+---
+
+## Timeline Mode — Edge-Validity / Supersession History
+
+`timeline` — walk an entity's edge-validity/supersession history in the graph:
+how a belief/fact evolved ("how did the auth decision evolve", "history of
+auth.py"). Deterministic, no LLM. Requires the graph index (`ENABLE_GRAPH_INDEX`);
+empty when the named entity resolves to no graph node or has no edges.
+Auto-routed after compute, scan, and absence — a query carrying one of those
+tells alongside a timeline tell routes there instead.
+
+**`--json` contract for timeline:** `results` is always `[]`; rows live under
+`timeline`. Each row: `subject`, `predicate`, `object`, `valid_from`,
+`valid_until` (`null` = still valid), `valid`, `score`.
+
+---
+
 ## Session Memory — Optional, Separately Gated
 
 Recall of prior AI-coding sessions (past-session transcript chunks and distilled

brainpalace_cli-26.7.2/brainpalace_cli/doc_sync/checkers/mode_parity_checker.py

@@ -0,0 +1,35 @@
+"""Adapt the query_modes contract-parity result into doc-sync DriftRecords so the
+lint:doc-sync gate fails on any cross-surface mode drift (both directions)."""
+
+from __future__ import annotations
+
+from brainpalace_cli.doc_sync.facts import DriftKind, DriftRecord, InterfaceSnapshot
+from brainpalace_cli.doc_sync.mode_parity import query_modes_mismatches
+
+_SURFACE_LOCATOR = {
+    "cli_choice": "brainpalace_cli/commands/query.py (--mode Choice)",
+    "mcp_literal": "brainpalace_cli/mcp_server/schemas.py (QueryMode)",
+    "hook_guard": "brainpalace_cli/commands/hook.py (_GUARD_QUERY_MODES)",
+    "mode_meta": "brainpalace_cli/doc_sync/mode_meta.py (MODE_META)",
+    "<sot>": "brainpalace_server/models/query.py (QueryMode)",
+}
+
+
+class ModeParityChecker:
+    surface = "mode-parity"
+
+    def check(self, snap: InterfaceSnapshot) -> list[DriftRecord]:
+        records: list[DriftRecord] = []
+        for m in query_modes_mismatches():
+            path = _SURFACE_LOCATOR.get(m.surface, m.surface)
+            if m.error is not None:
+                msg = f"{m.surface}: extractor error: {m.error}"
+            else:
+                msg = (
+                    f"{m.surface} out of sync with server QueryMode enum: "
+                    f"missing={sorted(m.missing)} extra={sorted(m.extra)}"
+                )
+            records.append(
+                DriftRecord(self.surface, m.surface, path, DriftKind.MISMATCH, msg)
+            )
+        return records

brainpalace_cli-26.7.2/brainpalace_cli/doc_sync/checkers/modes.py

@@ -0,0 +1,108 @@
+"""Modes surface: canonical GENERATED:modes block in brainpalace-query.md (add/remove
+gate) + a scoped referential check for `--mode <token>` invocations elsewhere +
+MODE_META coverage + any additional per-doc `targets` (README/docs mode tables in
+their own richer shape, e.g. README's grid or USER_GUIDE's commands table)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from brainpalace_cli.doc_sync.facts import DriftKind, DriftRecord, InterfaceSnapshot
+from brainpalace_cli.doc_sync.generator import MODES_RENDERERS
+from brainpalace_cli.doc_sync.markers import MarkerError, find_block
+from brainpalace_cli.doc_sync.mode_meta import MODE_META
+from brainpalace_cli.doc_sync.referential import dangling_tokens
+from brainpalace_cli.doc_sync.serializer import render_modes_table
+
+SURFACE = "modes"
+CANONICAL = "brainpalace-query.md"
+# Scoped to real invocations: `--mode <tok>` or `--mode=<tok>` (resolution H).
+_MODE_RE = re.compile(r"--mode[= ]([a-z][a-z0-9-]*)")
+
+
+class ModesChecker:
+    surface = SURFACE
+
+    def __init__(self, docs_dir: Path, targets: dict[Path, str] | None = None) -> None:
+        self.docs_dir = Path(docs_dir)
+        # path -> style ("table"/"grid"/"commands"): additional docs whose own
+        # GENERATED:modes block (if present) is checked against that doc's style.
+        self.targets = {Path(p): style for p, style in (targets or {}).items()}
+
+    def check(self, snap: InterfaceSnapshot) -> list[DriftRecord]:
+        records: list[DriftRecord] = []
+        missing_meta = [m for m in snap.modes if m not in MODE_META]
+        if missing_meta:
+            records.append(
+                DriftRecord(
+                    SURFACE,
+                    "mode-meta",
+                    "brainpalace_cli/doc_sync/mode_meta.py",
+                    DriftKind.MISSING,
+                    f"MODE_META has no entry for live mode(s): {missing_meta!r}",
+                )
+            )
+        # A mode lacking MODE_META already yields a MISSING record above; every
+        # render_modes_* call raises ValueError for it, so skip the render-based
+        # comparisons below rather than crash the whole checker on that gap.
+        canon = self.docs_dir / CANONICAL
+        if canon.exists():
+            text = canon.read_text(encoding="utf-8")
+            try:
+                inner = find_block(text, "modes")
+                if (
+                    not missing_meta
+                    and inner.strip() != render_modes_table(snap.modes).strip()
+                ):
+                    records.append(
+                        DriftRecord(
+                            SURFACE,
+                            "query",
+                            str(canon),
+                            DriftKind.MISMATCH,
+                            "canonical modes block out of sync with --mode Choice",
+                        )
+                    )
+            except MarkerError:
+                records.append(
+                    DriftRecord(
+                        SURFACE,
+                        "query",
+                        str(canon),
+                        DriftKind.MISSING,
+                        "canonical GENERATED:modes block absent",
+                    )
+                )
+        if not missing_meta:
+            for path, style in self.targets.items():
+                if not path.exists():
+                    continue
+                text = path.read_text(encoding="utf-8")
+                try:
+                    inner = find_block(text, "modes")
+                except MarkerError:
+                    continue  # block not present in this doc — nothing to gate
+                render = MODES_RENDERERS[style]
+                if inner.strip() != render(snap.modes).strip():
+                    records.append(
+                        DriftRecord(
+                            SURFACE,
+                            path.stem,
+                            str(path),
+                            DriftKind.MISMATCH,
+                            f"GENERATED:modes block ({style}) out of sync with "
+                            "--mode Choice",
+                        )
+                    )
+        all_docs = sorted(self.docs_dir.glob("brainpalace-*.md"))
+        records.extend(
+            dangling_tokens(
+                all_docs,
+                _MODE_RE,
+                set(snap.modes),
+                SURFACE,
+                "`--mode {tok}` references a non-existent mode",
+            )
+        )
+        return records

brainpalace_cli-26.7.2/brainpalace_cli/doc_sync/contract_parity.py

@@ -0,0 +1,88 @@
+"""Generic cross-surface parity gate.
+
+A *contract* is one canonical token set (the source of truth) plus a set of named
+*surfaces* that each independently re-declare that set. The check asserts every
+surface equals the SoT, in BOTH directions (a surface missing a token, or carrying
+an extra one), and fails loud per surface (an extractor that raises is reported by
+name, never crashes the run). Register a contract once; `check_all` loops them all.
+This kills the "same list hardcoded in N places drifts apart" bug class for any
+future contract, not just query modes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Contract:
+    name: str
+    sot: Callable[[], set[str]]
+    surfaces: dict[str, Callable[[], set[str]]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ParityMismatch:
+    contract: str
+    surface: str
+    missing: frozenset[str] = frozenset()  # in SoT, absent from the surface
+    extra: frozenset[str] = frozenset()  # in the surface, absent from the SoT
+    error: str | None = None  # the extractor (or SoT) raised
+
+
+_CONTRACTS: dict[str, Contract] = {}
+
+
+def register_contract(
+    name: str,
+    sot: Callable[[], set[str]],
+    surfaces: dict[str, Callable[[], set[str]]],
+) -> None:
+    _CONTRACTS[name] = Contract(name, sot, dict(surfaces))
+
+
+def clear_contracts() -> None:
+    _CONTRACTS.clear()
+
+
+def check_contract(name: str) -> list[ParityMismatch]:
+    c = _CONTRACTS[name]
+    try:
+        truth = c.sot()
+    except Exception as exc:  # noqa: BLE001 - report, don't crash the gate
+        return [ParityMismatch(c.name, "<sot>", error=repr(exc))]
+    out: list[ParityMismatch] = []
+    for surface, extract in c.surfaces.items():
+        try:
+            got = extract()
+        except Exception as exc:  # noqa: BLE001
+            out.append(ParityMismatch(c.name, surface, error=repr(exc)))
+            continue
+        missing = frozenset(truth - got)
+        extra = frozenset(got - truth)
+        if missing or extra:
+            out.append(ParityMismatch(c.name, surface, missing=missing, extra=extra))
+    return out
+
+
+def check_all() -> list[ParityMismatch]:
+    out: list[ParityMismatch] = []
+    for name in _CONTRACTS:
+        out.extend(check_contract(name))
+    return out
+
+
+def format_mismatches(mismatches: list[ParityMismatch]) -> str:
+    if not mismatches:
+        return "contract parity OK"
+    lines = ["contract parity FAILED:"]
+    for m in mismatches:
+        if m.error is not None:
+            lines.append(f"  [{m.contract}] {m.surface}: extractor error: {m.error}")
+        else:
+            lines.append(
+                f"  [{m.contract}] {m.surface}: "
+                f"missing={sorted(m.missing)} extra={sorted(m.extra)}"
+            )
+    return "\n".join(lines)

{brainpalace_cli-26.7.1 → brainpalace_cli-26.7.2}/brainpalace_cli/doc_sync/generator.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 import re
 import subprocess
 from pathlib import Path
+from typing import Callable
 
 from brainpalace_cli.doc_sync.facts import CommandFact, InterfaceSnapshot
 from brainpalace_cli.doc_sync.markers import (
@@ -20,10 +21,20 @@ from brainpalace_cli.doc_sync.serializer import (
     render_flags_section,
     render_flags_table,
     render_mcp_tools_table,
+    render_modes_commands,
+    render_modes_grid,
     render_modes_table,
     render_params_yaml,
 )
 
+#: style name -> renderer(modes) -> markdown body. Each target doc registers the
+#: style matching its own richer column shape; all pull from the same MODE_META.
+MODES_RENDERERS: dict[str, Callable[[list[str]], str]] = {
+    "table": render_modes_table,
+    "grid": render_modes_grid,
+    "commands": render_modes_commands,
+}
+
 _PARAMS_RE = re.compile(r"^parameters:.*?(?=^\S|\Z)", re.MULTILINE | re.DOTALL)
 
 
@@ -117,6 +128,24 @@ def regenerate_query_modes(path: Path, modes: list[str]) -> None:
     path.write_text(text, encoding="utf-8")
 
 
+def regenerate_modes_block(path: Path, modes: list[str], style: str) -> bool:
+    """Refresh the GENERATED:modes block in ``path`` IF PRESENT, using the renderer
+    for ``style`` (mirrors regenerate_provider_tables: these tables are placed by a
+    human where they belong, never auto-appended). Returns True if the file changed,
+    False when the file has no modes block (skipped, untouched)."""
+    render = MODES_RENDERERS[style]
+    text = path.read_text(encoding="utf-8")
+    try:
+        find_block(text, "modes")
+    except MarkerError:
+        return False
+    new_text = replace_block(text, "modes", render(modes))
+    if new_text != text:
+        path.write_text(new_text, encoding="utf-8")
+        return True
+    return False
+
+
 def regenerate_provider_tables(path: Path, snap: InterfaceSnapshot) -> bool:
     """Refresh every provider/install GENERATED block PRESENT in ``path`` from the
     live registry. Only existing blocks are rewritten (these tables are placed by a