Scanning and auditing
Run one scan to find broken layouts, bad Twig, hard-coded navigation, dead links and warnings your pages raise while rendering.
What it is
wpcanai/scan is a read-only MCP ability that checks every template and CanAI page on the site. It takes no input and returns a list of findings, each with a severity (ok, info or warning), a type, a plain-language message, and where it can, post_id, field and line. Agents run it after writing content. You can ask an agent to run it and fix what it finds.
The Diagnostics page (CanAI → Tools → Diagnostics, or wpcanai/diagnostics) is the separate environment check: server, WordPress, plugin, capabilities, integrations, tools, languages, menus and render warnings. Add the connectivity tests for CDN, REST and Authorization-header probes (they take a few seconds).
Example
Ask your agent: "Scan the site and fix every warning." It calls wpcanai/scan, then fixes each finding with a targeted edit:
wpcanai/scan {}
wpcanai/replace-in-meta {
"post_id": 42, "field": "html",
"replacements": [ { "from": "get_menu('main')", "to": "get_menu('primary')" } ]
}
What each finding means
Content and Twig
| Type | Triggered by | Fix |
|---|---|---|
twig_syntax_error |
Invalid Twig in html, css or js, with the line. |
Correct the Twig; scan keeps reporting it if an agent forced it in. |
leaky_comment |
<!-- --> in the HTML (reaches view-source), or a /* */ block in JS that looks like infrastructure fingerprinting. |
Use Twig {# #} comments. |
leaky_secret |
A secret-shaped literal in template meta. | Remove it and keep secrets out of templates. |
missing_structure_comment / invalid_structure_comment |
A landmark element without a {# Type / Short Label #} comment right before it, or a malformed one. |
Add one single-line comment, e.g. {# Section / Hero #}. |
split_sentence |
One sentence broken across several t() calls around inline tags. |
Put the whole sentence, tags included, in one t(). |
unsupported_t_markup |
t() text containing block elements or unpaired tags, so markup would show as text. |
Keep inline tags (strong, em, a, span, br) inside, block elements outside. |
Navigation and links
| Type | Triggered by | Fix |
|---|---|---|
hardcoded_nav |
A <nav>, header or footer with a hand-written list of links. |
Write the links with wpcanai/write-menu and render get_menu('primary') or get_menu('footer'). |
unknown_menu_location / legacy_menu_location |
get_menu() with a name that is not a CanAI location, or a retired name. |
Use primary or footer. |
menu_not_assigned |
get_menu('footer') while no menu is assigned there. |
Call write-menu with that location. |
menu_fallback_chain |
One get_menu() falling back to another. |
Remove the fallback; navigation is data. |
menu_children_twice |
Looping every item and then each item's .children. |
Loop only items with depth == 0. |
hardcoded_lang_prefix / unlocalised_internal_href |
A hand-built language prefix, or an internal link with no language handling on a multilingual site. | Use turl('/path/'). |
link_unresolved |
A literal slug_url('x') that matches no page, or several. It renders href="". |
Fix the slug, pass the full path, or use turl(id_url(N)). |
link_moved |
A literal turl('/old/') or href="/old/" to a page that now lives elsewhere. |
Switch to turl(id_url(N)) so the link follows the page. |
Both link checks list every line a literal appears on, and commented-out links are ignored.
Layout and WooCommerce
| Type | Meaning |
|---|---|
no_layout, no_layout_tpl |
A page or template has _canai_html but no layout. |
no_content, no_template |
A template has no HTML, or a WooCommerce page has no CanAI template. |
empty_delegate_page, delegate_mismatch, broken_layout |
A delegate page has no content, or a declared delegate or layout points at a post that no longer exists. |
duplicate_type_template |
Two templates compete for the same type. |
template_ok, template_body_ok, delegate_ok |
Everything is fine (severity ok). |
Render warnings
render_warning reports a PHP warning that a template's own Twig raised while a page rendered in the last 7 days, most often "Array to string conversion" when a value that is a list is printed as text. The finding names the post, the field (html, css or js) and the line when Twig can tell. Print the right item, such as {{ items|join(', ') }}, and the entry clears when you write that field again. To see the entries for one page, ask wpcanai/read-meta for render_warnings.
If something looks wrong
- The same finding keeps coming back. Scan reads stored content, so fix and write the right field, then run it again.
- A warning shows in the PHP log but no post is named. Open Diagnostics and check the Render warnings group; warnings from a template's own code are attributed to a post, field and line, anything else is left alone.
link_movedon a link you meant. The path matches a page that provably moved. If the link is intentional, make it point at the new location.- No
link_*finding for a dynamic link. Only literalslug_url(),turl()and plainhrefvalues are checked.