Automatic Knowledge Sync and Metadata Configuration

Automatic Knowledge Sync keeps selected public WordPress content available to the AI-Kit Knowledge Base without manually publishing each generated base document. It is separate from Static Publisher: one updates the knowledge source used by search and chat; the other deploys public static pages.

Connect the site​

Open SmartCloud → AI-Kit Settings → Knowledge Base → Automatic Knowledge Sync. The connected Pro feature requires a compatible AI-Kit backend. AI-Kit 1.4.19 and later require knowledge.automation capability 5 for automatic document delivery, available in backend release 1.0.85 and later compatible releases. The sync-aware source statuses below are available from AI-Kit 1.4.20.

1. Configure API Settings first. This is the source of truth for the backend: a direct URL is used directly; a Gatey REST API name is resolved to its configured endpoint. Backend from API Settings is read-only.
2. Under Connection and runner, select the appropriate environment and private-key storage. Encrypted WordPress option is available; the Protected file outside webroot option requires the protected server location to be configured. Disabled cannot enroll the site.
3. Save connection settings, then select Create pairing code and enroll. The short-lived code establishes a site-specific signing key for subsequent server-side requests.
4. Confirm Enrolled and use Verify connection if needed.

Enrollment alone does not opt every content type into synchronization.

Choose content and approval policy​

Under Content policy, select a public content type, enable Automatically synchronize this content type, configure its policy, and Save content policy. Repeat for each desired type. Standard posts and pages are supported, as are eligible public custom post types with public URLs.

• WordPress publish is approval permits automatic delivery of published content changes.
• Manual KB review holds changes until an administrator reviews them and selects Approve selected content type under Operational status.
• Taxonomies included in metadata chooses which taxonomies contribute document terms and the WordPress-derived vocabulary. Selecting taxonomies without enabling and saving the content policy does not publish a vocabulary.
• Document profile is an advanced routing label stored with backend document metadata. Keep default unless your retrieval filters explicitly use another profile; it does not change conversion or ingestion by itself.

Only eligible published content in the selected public content types is delivered. Drafts, revisions, unpublished proposals, and private-status content are not sources for automatic delivery. Unpublishing previously synchronized content produces a removal request rather than uploading the unpublished version. Large deletion sets can require explicit approval.

Scheduling and initial synchronization​

AI-Kit registers a WordPress cron event due every five minutes. Ordinary WP-Cron traffic can execute it. On low-traffic sites, or when traffic-driven WP-Cron is disabled, schedule wp cron event run --due-now every five minutes on the WordPress server. A runner lock prevents overlapping passes.

This is a PHP/server-side workflow, not a task performed by visitors to the static frontend. The WordPress host needs outbound connectivity to the resolved backend. The browser-based chatbot and Doc Search can still run on a static site after the source WordPress installation has synchronized its content.

Run one sync pass performs one bounded pass, not necessarily the entire initial import. Baseline and transport batch sizes limit work per pass; cron continues the remaining work. Check Operational status for pending work, baseline records, blocked reasons, ingestion state, and the last runner result.

Metadata configuration layers​

The Metadata configuration layers box combines three independently owned inputs. It is not three editable copies of the same generated file.

All metadata-layer editors and previews use YAML. This presentation and storage format does not change the API's structured JSON request and response objects, or the per-document *.metadata.json sidecars required by Knowledge Base ingestion; those remain JSON.

The generated result merges enabled external and WordPress vocabularies with the manual policy. Use allowedCategories, allowedTags, and namespaceTags for values you intentionally want to retain in the manual layer; values in namespaceTags must also appear in allowedTags. Existing fields such as categoryPolicies remain authored policy. Use vocabularyPolicy only when aliases, exclusions, or locked display values are needed to normalize automatic inputs. Edit the inputs or policy, not the generated result.

For example, an external vocabulary can express a category hierarchy without turning a child category into another top-level category:

- id: docusaurus
  enabled: true
  namespaces:
    category:
      - slug: guides
        label: Guides
      - slug: setup
        label: Setup
        parentSlug: guides
    post_tag:
      - ai-kit

Keep producer IDs stable. The external YAML list contains vocabulary envelopes, not documents to upload. Refreshing this panel only reads its current state; run a sync pass or wait for cron to deliver changed WordPress vocabulary.

Migrating an existing configuration​

When Legacy config ready to migrate appears, external and WordPress inputs are staged while the current effective configuration remains unchanged. Inspect Proposed result before choosing Establish manual layer. The proposed manual layer preserves manual-only and unknown policy fields while leaving producer-supplied vocabulary under producer control.

Establishing the manual layer activates the staged merge. It is not an instruction to discard existing custom policy, and it does not remove old documents from the Knowledge Base. Review any retained manual category and tag values deliberately; do not erase them merely because another producer also uses those terms. After migration, subsequent valid input or policy saves can update the effective result without another establish step.

Source URLs and document overrides​

For an automatically generated base document, the source URL precedence is:

1. The document's explicit Source URL in Edit Base Document Metadata.
2. KB Settings → Base URL Override, applied to the WordPress permalink.
3. The original WordPress permalink.

Use the global override when an editorial site has a different public origin, for example when editing on a development hostname but serving the content on the production hostname. An explicit per-document URL takes precedence.

Automatic sync also respects base-document title, description, category, subcategory, and tag overrides. These metadata overrides do not by themselves lock the generated Markdown. Metadata edits enter the synchronization workflow under the same approval policy; changing the global Base URL Override triggers reconciliation of existing documents.

Read status correctly​

The KB Sources publication-status filter and badges distinguish automatic delivery states such as awaiting sync, syncing, delivered, error, blocked, and removed. Errors include their specific reason where available.

Delivered means the backend received the current document generation. It does not mean Knowledge Base indexing has finished. Check backend ingestion under Operational status before expecting updated search or chat results.

Needs Review remains meaningful for manual-approval work, separate manual documents, or stale locked overrides. A successful automatic base-document delivery does not automatically approve those separate items. Conversely, the absence of a manual publication record alone does not put a synchronized base document into review.