Configuration backup and migration

Understand configuration roots, private backups, and safe settings exchange.

How it works

Settings use four groups: general settings (cybermaps_settings), Content Discovery Strategy (cybermaps_discovery_center), crawler policy (cybermaps_robots_manager), and identity (cybermaps_identity_data). Saving one workspace preserves values owned by other workspaces.

Identity and crawler-policy repeaters are submitted as bounded JSON; the server also accepts the validated nested-field fallback. An invalid structured group keeps its previously saved value and reports an error. If the main settings request is cut off before its final completeness marker, Cybermaps preserves all four groups. Reduce unusually large repeater lists or resolve the server input limit before retrying. Configuration imports have a separate strict validation and preview workflow.

Advanced settings provide two deliberately different exchange formats.

Versioned JSON backup

The JSON backup contains:

• all cybermaps_settings values, including nested values and the private API secret;
• the Content Discovery Strategy;
• Robots Control data;
• Identity Hub data; and
• the IndexNow key.

The file includes its format version and an integrity checksum. Import accepts Smart Merge or Full Replace and validates every configuration group with its owning sanitizer. Smart Merge preserves destination secrets when the source value is empty; Full Replace requires a valid Cybermaps JSON backup. Imports are limited to 1 MiB (1,048,576 bytes).

Each changed group is written only while its stored value still matches the reviewed state. If a write or verification fails, Cybermaps attempts to restore only values still owned by that import. Concurrent changes are preserved. A partial-restoration error requires reviewing the current settings and publication status before making a fresh preview. The group writes are not one atomic transaction.

This is a site-configuration backup, not a backup of every Cybermaps-owned or WordPress-owned record. It excludes:

• Discovery Analytics history;
• saved Content Intelligence Report runs;
• posts, pages, media, and other WordPress content;
• generated files, ownership records, caches, and operational status;
• network-wide settings; and
• cross-site translation relationships.

Because the JSON file can contain the private Cybermaps REST API secret and information entered in plugin settings, keep it private. The IndexNow key is also preserved for exact restoration but is not an integration credential.

AI Configuration Brief

The Markdown AI Configuration Brief is a site-aware, credential-excluding handoff for AI-assisted configuration. It contains operating instructions, privacy and safety rules, current non-secret values, public identity/contact/catalog context, site content and taxonomy inventories, route and publication state, detected integrations, supported crawlers and schema types, and a complete field reference with defaults, allowed values, dependencies, examples, and risk levels. Its fenced JSON changes envelope starts with every editable field set to null; only non-null changes are considered.

The v2 envelope is merge-only and strict: unknown sections, fields, nested properties, crawler IDs, malformed public URLs, incompatible identity types, and invalid cross-field combinations are errors. Cybermaps first produces a non-mutating field-level preview of current, proposed, and canonical sanitized values. Applying requires that exact file and unchanged destination configuration; high-impact changes require explicit acknowledgement.

The complete administrator and AI-assistant workflow, changes-envelope rules, privacy boundary, validation behavior, examples, and troubleshooting guidance are documented in AI-Assisted Configuration.

The canonical machine contracts are published at https://cybermaps.dev/specs/ai-configuration/{version}/schema.json and https://cybermaps.dev/specs/ai-configuration/{version}/catalog.json, with usage guidance at https://cybermaps.dev/docs/ai-configuration/. The same canonical artifacts are committed under docs/dev/ai-configuration/ in the plugin source repository; their hashes appear in its generated manifest. The private Cybermaps REST API secret and IndexNow key, destructive uninstall state, analytics, report data, content, and generated files are not included. Credential-bearing URL userinfo is omitted as well. Because ordinary configuration fields are user-authored and can still contain sensitive business details, review the Brief before sharing it. Use the complete JSON backup—not the Brief—when exact restoration is required, and keep that backup private.

Old backups may contain retired MCP keys. The current sanitizer removes those keys, and imports cannot restore the deleted server or remote tools. The new enable_mcp_adapter boolean controls only the read-only integration; use the optional MCP setup and reconnect clients after upgrading.

Only the complete JSON backup and the self-describing v2 Brief are accepted for configuration import. Earlier Markdown templates are intentionally unsupported.