SmartBlocks User Guide

Vexal SmartBlocks is the core WordPress plugin for AI visibility. It scores page readiness, surfaces governed recommendations, tracks changes in the Visibility Ledger, and runs visibility campaigns—without replacing your theme or page builder.

What SmartBlocks does

• Page Readiness — multi-section scoring (SEO, AI, GEO, schema, social, content)
• SEO fields — title, meta description, canonical, keywords, OG/social signals
• Schema / JSON-LD — FAQPage, Article, Organization, LocalBusiness (conditional output)
• FAQ management — per-post FAQ metabox, shortcodes, FAQPage schema
• Visibility Recommendations — evidence-backed actions via shared registry
• Safe Fix / Apply Fix — governed apply paths with preview, baseline, and compare
• Visibility Ledger — durable event log and daily snapshots
• Before/After reports — ledger compare and campaign compare views
• Snapshots — per-post, site-level, and campaign baseline/after history
• Telemetry — crawler/agent activity, GSC bridges, AI perception logging
• Media readiness bridge — site media signals in ledger when Vexal Media is active
• Agent Intelligence — agent insights, test prompts, copy-to-clipboard with ledger logging

Page Readiness

Readiness appears in the post editor metabox and campaign compare views. The primary score comes from the AI Grader (grade_total), aligned with Overview/Performance snapshots.

Section scores

Stored as readiness_section_scores on per-post snapshots:

• SEO — titles, meta, canonical, headings, internal links
• AI — clarity, entity signals, generative-readiness patterns
• GEO — local-intent signals (contextual—see below)
• Schema — JSON-LD completeness and alignment
• Social — OG title/description presence
• Content — structure, depth, FAQ presence

AI / Generative Signals

SmartBlocks evaluates how clearly a page communicates to AI systems and answer engines. Signals include heading hierarchy, entity mentions, FAQ coverage, schema flags, and telemetry-derived agent activity. The /llms.txt endpoint is served when SmartBlocks is active for site-level machine-readable summary.

SEO fields

SmartBlocks reads and scores SEO-related post meta alongside Rank Math and Yoast when present. Fields include SEO title, meta description, canonical URL, focus/primary keyword, and Open Graph title/description.

Schema / JSON-LD

Schema output is conditional—not injected globally:

• FAQPage — from grounded FAQ rows in post meta
• Article — on supported singular types (can defer to Rank Math)
• Organization — from GEO/settings when configured
• LocalBusiness — when enabled with required fields

FAQ management

Manage FAQ rows in the post metabox. Output via shortcodes [smartblocks_faq_all] or [nad_faq_all]. FAQ Guided Action proposes content-grounded FAQ drafts for review before apply—generic placeholder FAQs are blocked.

Visibility Recommendations

Recommendations map to registry keys with pillars (crawlability, structure, content clarity, AI readiness, technical SEO, authority, conversion). Each key has an apply mode:

• diagnostic_only — insight only
• manual — guidance, user edits
• assisted — guided apply with confirmation
• governed campaign Safe Fix — high-confidence batch path

See Recommendation Engine for registry details.

Safe Fix / Apply Fix

Safe Fix is the governed campaign apply path: scan → stage → forecast → preview → baseline snapshot → apply → compare. Moderate-risk FAQ changes use FAQ Guided Action (review modal) instead of silent apply.

Post-level governed keys are blocked on legacy Telemetry/Coverage apply unless the source is Campaign Safe Fix.

See Visibility Campaigns.

Visibility Ledger

The ledger stores events and daily snapshots (7/30/90-day windows). Admin tabs: Timeline, Snapshots, Compare, Settings.

Logged events include content saves, recommendation applies, AI perception, agent prompt copies, crawl/schema changes, and media readiness fixes (when Vexal Media is active).

See Visibility Ledger.

Before/After reports

• Ledger Compare — Visibility Change Report with metrics, events, and recommendation correlation
• Campaign compare — readiness and section score deltas after Safe Fix
• Recovery & Rollback — before/after overlay per campaign page with manifest diff
• Media readiness section — appears in compare when Vexal Media metadata exists on both snapshots

Media readiness bridge

When Vexal Media is active, ledger snapshots can include metadata.media_readiness: total images, missing alt, oversized images, weak filenames, WebP count, readiness score. Post-fix events log via media_readiness_fix_applied.

Vexal Media user guide →

Agent Intelligence

Production surfaces in the Telemetry dashboard under Intelligence → Insights & actions:

• Primary/secondary agent identification
• Top paths and confidence badges
• Test This Agent and Copy Prompt with AJAX ledger logging

See Agent Intelligence and AI Perception Testing.

Snapshots and historical comparison

• Site-level — ledger daily rows (visibility score, confidence, AI hits, optional GSC, media readiness)
• Per-post — smartblocks_visibility_snapshots post meta with score history and section scores
• Campaign — baseline and after snapshots for Safe Fix compare
• Recovery — dedicated change-snapshots table for rollback engine

How to run checks

1. Open a post or page in the WordPress editor — readiness checklist appears in the SmartBlocks metabox
2. Visit Vexal → Vexal AI Visibility for site-wide dashboards
3. Run a Visibility Campaign scan for batch analysis and Safe Fix queue
4. Review Visibility Ledger → Snapshots for historical site trends
5. Check Telemetry for crawler/agent activity validation

How to interpret scores

Higher readiness means clearer machine understanding—not a guarantee of rankings. Focus on the weakest section first. Section scores drive recommendation priority. Campaign compare shows which sections moved after governed apply.

Site visibility score in the ledger aggregates multiple signals; per-post scores may differ from site aggregate.

What not to worry about (valid fallbacks)

SmartBlocks uses context-aware scoring. These are often informational, not errors:

Recommended workflow

1. Baseline: review Page Readiness on key landing pages
2. Fix informational fallbacks only when they represent a real gap (not when fallback is correct)
3. Address high-impact recommendations from the registry
4. Run a Visibility Campaign for batch Safe Fix on high-confidence items
5. Review FAQ/schema via FAQ Guided Action for moderate-confidence changes
6. Compare before/after in Visibility Ledger or campaign compare
7. If Vexal Media is active, review media readiness in ledger snapshots
8. Monitor telemetry for crawler/agent validation over 7–30 days

Not yet production-ready

• Vexal Hub transport — REST structured, no Hub transport in v1
• Safe Fix Engine v2 — deferred
• HowTo schema builder — future; guidance map exists today
• Some recommendation lifecycle hooks (recommendation_viewed, dismissed) need more UI wiring