feat(wiki): add flow-diagram canonical section (parity with agentic-ai)

agentic-ai added a 14th canonical section ``flow-diagram`` alongside
``sequence-diagram`` because they cover different mermaid types and
different intents:

* ``sequenceDiagram`` — call traces between participants (caller
  → this file → callees). Lives in the existing ``sequence-diagram``
  section.
* ``flowchart`` / ``stateDiagram-v2`` — branching, lifecycle,
  decision trees within one component. Now lives in the new
  ``flow-diagram`` section.

Lumping both into ``sequence-diagram`` forced the LLM to pick one
and skip the other; splitting lets it author whichever shape fits
the file's actual semantics.

Changes:

* ``core/wiki_curation_gaps.py`` — new ``CurationSection(name="flow-diagram", …)``
  with probes for ``## Flow diagram`` / ``## Flowchart`` / ``## State
  diagram`` and the corresponding mermaid fence forms. ``sequence-diagram``
  probes tightened so it no longer claims a ``## Flow diagram`` heading.
* ``handlers/consolidation/headless_authoring.py`` —
  ``_GAP_DESCRIPTIONS`` + ``_gap_heading`` extended so the worker
  knows what to write under ``## Flow diagram``.
* ``ui/unified/js/wiki.js`` — curation banner label for ``flow-diagram``,
  total section count bumped 13 → 14.

121-test wiki suite + ruff format + ruff check all green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: cdeust

mcp_server/core/wiki_curation_gaps.py

@@ -148,7 +148,6 @@ class CurationSection:
         heading="## Sequence diagram",
         probes=(
             "## Sequence diagram",
-            "## Flow diagram",
             "## Sequence",
             "```mermaid\nsequenceDiagram",
         ),
@@ -163,6 +162,29 @@ class CurationSection:
             "why."
         ),
     ),
+    CurationSection(
+        name="flow-diagram",
+        heading="## Flow diagram",
+        probes=(
+            "## Flow diagram",
+            "## Flowchart",
+            "## State diagram",
+            "```mermaid\nflowchart",
+            "```mermaid\nstateDiagram",
+        ),
+        min_chars_under_heading=120,
+        description=(
+            "A `mermaid` flowchart (or state diagram) of the file's "
+            "branching logic, lifecycle, or decision tree. Use "
+            "```mermaid flowchart TD/LR``` fences for branching, "
+            "```mermaid stateDiagram-v2``` for state machines. "
+            "Distinct from the sequence diagram above (sequenceDiagram "
+            "covers call traces between participants; flowchart covers "
+            "branching / lifecycle / trees within a single component). "
+            'For files with no branching to depict, write "Not '
+            'applicable" and explain why.'
+        ),
+    ),
     CurationSection(
         name="parameters",
         heading="## Parameters",

mcp_server/handlers/consolidation/headless_authoring.py

@@ -461,6 +461,17 @@ def _scan_pages_with_gaps(wiki_root: Path) -> list[tuple[Path, dict[str, Any], s
         'data types, constants), explicitly write "Not applicable" '
         "and explain why."
     ),
+    "flow-diagram": (
+        "A `mermaid` flowchart or state diagram of the file's "
+        "branching logic, lifecycle, or decision tree. Use "
+        "```mermaid flowchart TD``` (or `LR`) for branching, "
+        "```mermaid stateDiagram-v2``` for state machines. "
+        "Distinct from the sequence diagram (sequenceDiagram is "
+        "for call traces between participants; flowchart covers "
+        "branching / lifecycle / trees within one component). For "
+        'files with no branching to depict, write "Not applicable" '
+        "and explain why."
+    ),
     "parameters": (
         "Exhaustive table of every parameter exposed by this "
         "file's public entry points. Columns: name | type | "
@@ -500,6 +511,7 @@ def _gap_heading(name: str) -> str:
         "tests": "Tests",
         "see-also": "See also",
         "sequence-diagram": "Sequence diagram",
+        "flow-diagram": "Flow diagram",
         "parameters": "Parameters",
         "request-example": "Request example",
         "response-example": "Response example",

ui/unified/js/wiki.js

@@ -748,7 +748,7 @@
     // is not curation; visibility is.
     var gaps = meta.curation_gaps;
     if (Array.isArray(gaps) && gaps.length > 0) {
-      var totalSections = 13;  // matches FILE_DOC_SECTIONS (incl. sequence-diagram, parameters, request/response-example)
+      var totalSections = 14;  // matches FILE_DOC_SECTIONS (incl. sequence-diagram + flow-diagram + parameters + request/response-example)
       var coveredCount = Math.max(0, totalSections - gaps.length);
       var pct = Math.round(100 * coveredCount / totalSections);
       var banner = el('aside', 'wiki-curation-banner');
@@ -780,7 +780,8 @@
         'failure-modes':    'What can go wrong — failure modes + symptoms',
         tests:              'Tests — which test files exercise this',
         'see-also':         'See also — cross-links to architecture / services / api',
-        'sequence-diagram': 'Sequence diagram — mermaid flow of caller → this file → callees',
+        'sequence-diagram': 'Sequence diagram — mermaid sequenceDiagram of caller → this file → callees',
+        'flow-diagram':     'Flow diagram — mermaid flowchart/stateDiagram of branching, lifecycle, decision tree',
         parameters:         'Parameters — exhaustive table (name, type, required, default, description)',
         'request-example':  'Request example — curl + headers / JSON-RPC envelope / call site',
         'response-example': 'Response example — every field annotated, success + error shapes',