Static File Engine

Static File Engine

How It Works

The StaticBridge singleton writes discovery files directly to ABSPATH using WordPress’s WP_Filesystem API:

1. tempnam($dir, 'cybermaps_')       → create temp file
2. WP_Filesystem::put_contents($tmp)  → write content
3. rename($tmp, $final)               → atomic move

Step 3 ensures the file never exists in a partial state. If the rename fails, a tempnam left-behind is the worst case.

Files Written

Disk Path Source Conditional
/{base}.xml Sitemap index Always
/{news_base}.xml Google News sitemap enable_google_news
/.well-known/ai.json ADP manifest Always
/ai-discovery ADP manifest (extensionless) Always
/llms.txt LLMS compact Always
/llms-full.txt LLMS exhaustive Always
/llms-tldr.txt LLMS-TLDR summary Always
/ai-usage.json Usage policy Always
/ai-actions.json Action items Always
/skill.md Site skills Always
/.well-known/ai-plugin.json Plugin manifest Always
/.well-known/mcp/server-card.json MCP server card Always
/.well-known/api-catalog API catalog Always
/{lang}/llms.txt Per-language LLMS Multilingual hub enabled

Sync Triggers

Immediate sync (request_sync(true)):

  • Manual regeneration from admin UI
  • WP-CLI cybermaps regenerate command

Debounced sync (request_sync(false)):

  • Fires on: save_post, delete_post, edited_term, create_term, delete_term
  • Schedules wp_schedule_single_event(time() + 60, 'cybermaps_bg_sync_static_files')
  • The 60-second window prevents thrashing during bulk edits

Manual purge:

  • Admin button → deletes all static files → triggers immediate resync
  • WP-CLI cybermaps clear_cache

Multisite

Only the main site writes static files. Sub-sites return immediately. This prevents file conflicts in multisite installations.

Write Error Handling

Failed writes are stored in cybermaps_static_write_errors option:

['llms.txt' => 'Permission denied', 'ai.json' => 'Disk full']

Successful writes clear prior errors for that file. Errors are surfaced as:

  • Admin notices on all admin pages
  • Status indicators in the Discovery Health dashboard
  • Write alerts on the Settings page

Verifying Static Files Are Being Served

Check response headers for a file served directly by the web server (no X-Powered-By: PHP):

curl -I https://example.com/llms.txt
# Look for: Server: nginx (or Apache)
# Absence of: X-Powered-By: PHP

If the response includes PHP headers, the web server isn’t routing to the static file. Check your server configuration.