AI Configuration Briefs and Backups

Cybermaps provides two different exports for two different jobs: a complete backup for recovery and migration, and an AI Configuration Brief for planning configuration changes with an AI assistant.

Choose the right export

Exact configuration backup

Use the JSON backup when you need to restore, migrate, or archive the complete Cybermaps configuration. It is checksum-protected and intended for Cybermaps itself.

Do not upload a complete backup to a third-party AI service. A backup is not an AI prompt and can contain the Cybermaps API secret, IndexNow key, and other operational values that are unnecessary for configuration advice.

AI Configuration Brief

Use the Markdown brief when you want an AI assistant to review the current setup and recommend specific changes. The brief explains Cybermaps, describes every editable field, includes the site’s current non-secret context, and defines the exact JSON response Cybermaps can import.

The brief is self-contained. It also names the version-specific schema and field catalog that correspond to the installed plugin, so a browsing-capable assistant can verify the contract without guessing.

Safe workflow

  1. Download AI Configuration Brief from Cybermaps.
  2. Read the disclosure before sharing it. The brief includes current non-secret settings such as publication guidance, external URLs, report branding, crawler choices, and configured public identity, contact, and catalog information.
  3. Give the brief to the AI assistant and explain the site’s goals, audience, and constraints.
  4. Ask the assistant to return the completed Markdown brief or only its sentinel-delimited JSON changes envelope.
  5. Import the response into Cybermaps.
  6. Review the server-generated comparison of current, proposed, and final sanitized values.
  7. Resolve rejected values and explicitly acknowledge any high-impact changes.
  8. Apply only after the preview matches the intended configuration.
  9. Validate the affected sitemap, schema, crawler policy, or AI publication from the appropriate Cybermaps status page.

Importing does not immediately overwrite configuration. Cybermaps validates the response first and blocks malformed, unknown, forbidden, or out-of-range changes. The preview also identifies values that were normalized, clamped, rejected, or left unchanged.

What changed in Brief format v2

Version 2 adds a machine-validated changes envelope, stable section and field identifiers, explicit field types and allowed values, dependency guidance, current effective values, and risk classifications. It gives an AI enough context to make a useful recommendation without exposing the complete backup format.

The version-specific references use these paths, with the installed plugin version substituted into the URL:

https://cybermaps.dev/specs/ai-configuration/<plugin-version>/schema.json
https://cybermaps.dev/specs/ai-configuration/<plugin-version>/catalog.json

The schema defines the accepted response structure. The catalog explains the editable fields and their Cybermaps behavior. Always use the URLs embedded in the downloaded brief; specifications from another plugin version may not describe the installed configuration.

Preserve means preserve

Inside the v2 changes envelope, an omitted field or a null value means preserve the destination’s current value. It does not mean reset, clear, disable, or replace the value with a default.

An AI should include only deliberate changes. This makes a short recommendation safer to review and prevents an assistant from reconstructing unrelated settings.

Identity and privacy

The AI brief includes the non-secret configuration Cybermaps needs for grounded recommendations: publication guidance and policies, external URLs, report branding, crawler choices, and configured organization/person, contact, and catalog data. Some of this may be operational context rather than public website content. Review all of it before sending the brief to any external service.

Cybermaps excludes its dedicated API secret, IndexNow key, uninstall-deletion control, and credential-bearing URL userinfo from the AI brief. A brief may say that a credential is configured, but it does not include that credential. Ordinary configuration fields are user-authored and can still contain sensitive business details, so the disclosure and the complete file should always be reviewed before sharing.

Keep exact backups private, use an AI service whose data-handling terms fit the site, and import only a response you have reviewed.