---
id: aikit-knowledge-sync
title: Automatic Knowledge Sync and Metadata Configuration
sidebar_label: Knowledge Sync
slug: /ai-kit/knowledge-sync
sidebar_position: 35
description: Synchronize approved public WordPress content into AI-Kit, configure metadata layers and URL overrides, and distinguish delivery from Knowledge Base indexing.
tags: [ai-kit, wordpress, knowledge-base, metadata, synchronization]
---

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.

:::warning Publication status is not an access-control boundary
Do not enable automatic sync for content types containing password-protected
or member-restricted published content unless an explicit exclusion has been
verified. A published status alone does not establish that content is safe to
expose through a public Knowledge Base; do not assume a frontend access-control
plugin also filters the server-side sync projection.
:::

## 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.

| Tab | Format and purpose |
| --- | --- |
| Manual policy | Editable YAML: stable authored settings and merge rules, including values that must remain regardless of producer input. |
| External vocabularies | Editable YAML list: vocabularies supplied by producers outside WordPress, such as documentation. |
| WordPress-derived | Read-only YAML: terms generated from enabled content policies and delivered by the signed runner. |
| Effective result | Read-only YAML: the last-known-valid configuration used by retrieval. |
| Proposed result | Read-only YAML preview during legacy migration, before staged inputs are activated. |
| Provenance | Read-only YAML audit map identifying the layers that contributed each effective value. |

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:

```yaml
- 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.