Content Sync Workflow

The pull/push workflow

Content sync is the core PromptWire workflow. You pull pages from ProcessWire into local YAML files, edit them in Cursor (manually or via the AI agent), and push changes back. Every operation previews changes before applying.

Pulling a page

When you pull a page, PromptWire creates a directory under site/assets/pw-mcp/ that mirrors the page's URL path. A page at /about/team/ becomes site/assets/pw-mcp/about/team/.

Each directory contains:

• page.yaml: all field values for the page, structured under a top-level fields key.
• page.meta.json: sync metadata including the page ID, template, canonical path, pull timestamp, and revision hashes for conflict detection.
• fields/: rich text fields are exported as separate HTML files (e.g. fields/body.html) and referenced from the YAML with _file: fields/body.html.

Pull a single page

Pull the About page.

Or via the MCP tool directly: pw_page_pull with pageIdOrPath: "/about/".

Pull multiple pages

Pull all blog posts.

Or: pw_pages_pull with selector: "template=blog_post". You can use any ProcessWire selector. The limit parameter defaults to 50.

Use noParent: true if you're pulling by path and don't want the parent page included.

Editing content

Once pulled, edit the YAML or HTML files directly in Cursor. You can also ask the agent to make changes:

Rewrite the About page body to be more concise.

The agent reads the local file, rewrites the content, and saves it. The change exists only in your local file until you push.

Pushing changes

Push sends your local changes back to ProcessWire. By default, every push is a dry run that shows you what will change without applying anything.

Preview changes (dry run)

Push the About page changes. Show me what will change first.

The agent compares your local YAML against the current database state and shows a field-by-field diff.

Apply changes

Apply the About page changes.

Or set dryRun: false on pw_page_push. The local file and metadata are updated after a successful push to reflect the new database state.

Push to remote

If you have a remote site configured, you can push to production:

Push the About page to production.

Set targets: "remote" or targets: "both" to push to remote, or both local and remote at once. Page references are resolved by path so they work across environments where page IDs differ.

Bulk push

Push all changes in the blog directory.

pw_pages_push finds every page.meta.json under the specified directory and pushes each page's changes.

Conflict detection

PromptWire tracks revision hashes to detect when a page has been modified in ProcessWire after you pulled it. If someone edits the page in the admin while you have a local copy, the push will detect the conflict and refuse to overwrite without confirmation.

When a conflict is detected, you'll see both the remote changes (what changed in ProcessWire) and your local changes (what you edited in the file). You can then choose to:

• Re-pull to get the latest version from ProcessWire (discards your local changes).
• Force push with force: true to overwrite the remote changes with your local version.

Sync status

Check the status of all pulled pages:

Show me the sync status.

pw_sync_status compares every pulled page against the database and reports one of:

Status	Meaning
clean	Local file matches the database. No changes on either side.
localDirty	The local file has been modified since the last pull or push.
remoteChanged	The page was modified in ProcessWire since the last pull.
conflict	Both the local file and the database have changed.
orphan	The page was deleted in ProcessWire but the local file still exists.

Reconciliation

Over time, pages can be renamed, moved, or deleted in ProcessWire while local sync files still reference the old paths. The reconcile tool fixes this:

Reconcile the sync directory.

pw_sync_reconcile detects path drift (page moved in PW, local folder still at old path), orphans (page deleted in PW), and new scaffolds that haven't been published yet. Like push, it's dry-run by default.

How page references are stored

Page reference fields are exported with both the page ID and path:

blog_categories:
  -
    _pageRef: true
    id: 1184
    path: /blog/categories/products/
    _comment: Products @ /blog/categories/products/

When pushing, PromptWire resolves references by path first, falling back to ID. This means references work correctly when pushing between environments where page IDs differ. See Cross-Environment Page IDs for details.

What content sync does not handle

Content sync covers text fields, page references, dates, checkboxes, options, and repeater/matrix content. File and image binaries are not transferred through content push. The YAML records file metadata (filename, description, dimensions) but the actual files need File Sync or manual transfer.