Dogfooding findings from cms-shuqi (Divi 5.7.1) — tool gaps + skill-doc gaps

[oaris-dev]

Collected while building/polishing the cms-shuqi header mega-menu, mobile off-canvas drawer, and event-calendar side panel (Divi 5.7.1) via the DiviOps MCP + divi-5-builder/diviops-scf skills. Grouped by type. The skill-doc items should land in the DiviOps Suite skill source (divi5-ai workspace), not the synced copy.

MCP tool gaps

1. diviops_page_update_content corrupts block markup — the PHP JSON round-trip strips self-closing /--> markers (tree scrambles → frontend 500 via GroupModule parent TypeError) and mutates empty {} attrs to []. page_create is clean. Suspect section_replace/section_append share the path. Workaround: direct $wpdb->update + clean_post_cache.
2. diviops_tb_layout_get has no per-module / subset read — getting the header layout returned ~54KB and exceeded the tool-result token cap; had to dump to a file and slice it just to read one module's dropdown.alignment. Ask: diviops_module_get(layout_id|page_id, label|index) or a fields filter.
3. No preset-read + diviops_preset_update is destructive (full-replace). preset_update replaces attrs+styleAttrs+renderAttrs (VB-save semantics) and there's no read that returns a preset's current attrs (audit gives only ref counts). So changing ONE attr (e.g. a pill preset's line-height) means knowing + resending the whole blob. Ask: a diviops_preset_get, or dot-notation partial merges like module_update.
4. diviops_preset_audit is an all-or-nothing wall (~30KB / 212 presets). Add a name/id/module filter.
5. diviops_meta_flush_cache doesn't regenerate off-canvas / header-scoped module CSS (.et_pb_link_N_tb_header), even with _divi_dynamic_assets_cached_feature_used postmeta delete + ET_Core_PageResource::remove_static_resources. Native canvas-module spacing saves to markup + shows in VB but won't render on the frontend; must back it with theme CSS. Either flush should cover it or document the limitation.

divi-5-builder skill-doc gaps

6. Wrong adminLabel path. "Critical Block Format Rules" Your MCP server scored Grade A #6 shows top-level "meta":{"adminLabel":...}, but VB only reads module.meta.adminLabel; top-level stores silently and is invisible in the VB layers panel. A validator warning for top-level meta would catch it.
7. No coverage of the Divi 5 off-canvas mobile-drawer pattern, which has sharp edges worth a reference doc: (a) the drawer is an et_pb_section--absolute toggled by an Element Interaction writing inline display, and the et-interaction-target-XXXX id regenerates per page-load → hook the stable --absolute class, never the id; (b) the off-canvas's header-scoped module CSS doesn't reliably recompile on flush (see Your MCP server scored Grade A #5); (c) the off-canvas section index varies per template (_0 on Divi pages, _1 on archives).
8. Override-specificity rule for custom PHP templates is undocumented. On CPT/archive/single templates Divi loads et-core-unified-cpt-*-deferred.min.css with id-scoped .et-db #et-boc .et-l .et_pb_*_N_tb_header { … !important } rules (specificity 1,3,0) that do NOT load on Divi-builder pages. So a plain .et_pb_* override (even !important) works on a builder page but silently loses on server-rendered templates. The fix-pattern — prefix overrides with .et-db #et-boc .et-l — belongs in the design-effects doc (currently only an ad-hoc example in a project's CLAUDE.md).

Happy to split any of these into separate issues if preferred.