Skip to main content
Product11 min read

1006 - Editing a live site

To change a site, ask. The agent reads the site’s files in place, patches the one that needs to change, and the patch becomes a new release in dev with a number, a note and a diff. Outline, locate, patch, dry run and overlay, the check that refuses an edit made against a release that has moved, and the promotion that takes several edits live in one step.

What you will take away from this lesson

A website is never finished. The Evanston store changes its weekday hours, legal wants a line added to the supplier page, a new store opens in Tulsa. On most sites each of those is a ticket for whoever knows how the site is built.

On Plexara each one is a sentence. The agent reads the site’s files where they are, changes the one that needs changing, and the change becomes a release in dev with a number, a note and a diff. This lesson follows three edits from the request to the public site.

Learning Objectives

  1. 01Address a site’s file, folder or whole tree with a reference.
  2. 02Find where something is said on a site without downloading it.
  3. 03Patch one file and read the release the patch made.
  4. 04Try an edit as a dry run and read what it would change.
  5. 05Add and remove files in one release with an overlay.
  6. 06Take several edits to the public site in one promotion.

Where this lesson sits

Lesson 1005 rebuilt acme-stores from records and layouts as release 4, which has since been promoted to stage and prod. The site is live, and the first change request has arrived.

1000 Series: Sites

Open index

The 1000 series builds on the forms and endpoints of the 700 series and the sharing model of the 800 series: a site is where the pages people open live, with the same people, personas and approvals deciding who reaches them.

Addressing a site’s files

To change a site the agent does not download it, rebuild it and publish it again. It works on the files where they are, and it names them the way it names everything else on the platform: with a reference.

How a site’s files are addressed

One file

mcp:site:acme-stores/dev/_data/stores/0002-evanston.json

The file as that environment’s release holds it. On a rendered site this is the source: a record, a layout, a page template.

A folder

mcp:site:acme-stores/dev/news/

Every file under the path. Listed a page at a time, and searched as one.

The whole tree

mcp:site:acme-stores/dev

Every file of the release the environment serves.

These are the references the agent already uses for reports and dashboards, pointed at a site. Reading works on any environment the person may open, so the agent can compare what prod serves with what dev holds. Changing works on dev alone.

The request

The Evanston store’s manager told store operations about the new closing time, and Jordan passed it to the agent.

What you type

The Evanston store now closes at 8 PM Monday to Saturday. Fix it on acme-stores, show me what changes before you save it, and tell me when it is ready to promote.

Finding what to change

The agent does not know the site by heart, and it does not need to. It searches the store records for Evanston and reads the one file that matches.

Finding the file to change

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_asset
  { "action": "locate",
    "asset_id": "mcp:site:acme-stores/dev/_data/stores/",
    "find": "Evanston" }

← { "version": 4, "environment": "dev", "count": 1,
    "files": [ { "path": "_data/stores/0002-evanston.json", "matches": 1 } ],
    "files_scanned": 303, "files_skipped": 0 }

→ manage_asset
  { "action": "get_content",
    "asset_id": "mcp:site:acme-stores/dev/_data/stores/0002-evanston.json" }

← { "version": 4, "environment": "dev", "type": "application/json",
    "content": "{ \"name\": \"ACME Evanston\", ... \"close\": \"9:00 PM\" ... }" }

A search across a folder or a whole tree reports how many files it scanned and how many it could not read, so a search that missed a file never reads as a clean result. The version in every answer is the release number, which the next call uses to say what it read.

The patch

Jordan asked to see the change first, so the agent ran the edit as a dry run, reported what would change, and then made it.

A dry run, then the patch

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_asset
  { "action": "patch", "dry_run": true,
    "asset_id": "mcp:site:acme-stores/dev/_data/stores/0002-evanston.json",
    "base_version": 4,
    "change_summary": "Evanston closes at 8 PM Monday to Saturday",
    "edits": [ { "find": "\"close\": \"9:00 PM\"", "replace": "\"close\": \"8:00 PM\"" } ] }

← { "dry_run": true, "outputs_changed": 1,
    "message": "Dry run: no release was created." }

→ manage_asset
  { "action": "patch",
    "asset_id": "mcp:site:acme-stores/dev/_data/stores/0002-evanston.json",
    "base_version": 4,
    "change_summary": "Evanston closes at 8 PM Monday to Saturday",
    "edits": [ { "find": "\"close\": \"9:00 PM\"", "replace": "\"close\": \"8:00 PM\"" } ] }

← { "version": 5, "change_summary": "Evanston closes at 8 PM Monday to Saturday",
    "address": "https://acme-stores--dev.pages.example.com/",
    "message": "Patched _data/stores/0002-evanston.json; new release 5." }

The agent changed a record, and the dry run says one served file would change: the Evanston store’s page. The store list shows a name and a city, not hours, so it is untouched. The patch then wrote release 5 and moved dev to it. The change summary is the release note, so the Releases tab reads as a list of what was done and why.

What a patch is

A patch looks like editing a file. It is something stricter, and the strictness is what makes it safe to let an agent do it.

What a patch is

  1. 01

    A patch is a release

    There is no editing a live file. A patch writes a new release derived from the one dev serves and moves dev to it. Release 4 is still there, unchanged, and dev can be rolled back to it.

  2. 02

    The edit names the release it read

    base_version is the release the agent read the file from. When dev has moved past it, because a colleague or another agent published in between, the patch is refused and nothing is written. The agent reads the file again and tries again, so one edit never silently overwrites another.

  3. 03

    Only dev takes an edit

    A patch aimed at stage or prod is refused with the same sentence a publish gets. Those environments can be read here and changed only by promotion.

  4. 04

    On a rendered site, the source is what is edited

    The agent patches a record or a layout, and the pages that read it are rendered again in the same release. Only those pages: a release of thousands of pages is not rebuilt for a change to one.

  5. 05

    A change costs what the change costs

    A derived release stores only what differs from the one before it. The files that did not change are not stored again, and reading the full set stays fast however long the chain of edits grows.

New files and deletions: the overlay

The second request that week was larger. A store opened in Tulsa, with a photograph, and the 2025 holiday post needed to come down.

An overlay: new files, a binary and a deletion in one release

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_site
  { "command": "publish", "site": "acme-stores", "base": 5,
    "note": "Tulsa store opens; retire the 2025 holiday post",
    "files": [
      { "path": "_data/stores/0304-tulsa.json", "content": "{ \"name\": \"ACME Tulsa\", ... }" },
      { "path": "assets/stores/tulsa.webp", "encoding": "base64", "content": "UklGR..." },
      { "path": "news/holiday-hours-2025.md", "delete": true }
    ] }

← { "release": { "number": 6, "note": "Tulsa store opens; retire the 2025 holiday post" },
    "environment": "dev",
    "address": "https://acme-stores--dev.pages.example.com/" }

A patch covers text in one file. For new files, images, deletions, or several files that must change together, the agent publishes with a base: the files sent are added or replaced, an entry marked delete removes a path, and everything else carries over from the base release. The base must be the release dev serves now, which is the same protection a patch has. The new record gave the site a Tulsa page and put Tulsa on the last page of the store list, with no template touched.

Reading what changed

Before promoting, Jordan asked what was different between the live site and the working copy. prod serves release 4 and dev serves release 6.

What changed between two releases

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_asset
  { "action": "diff",
    "asset_id": "mcp:site:acme-stores/dev",
    "from_version": 4, "to_version": 6 }

← { "from_version": 4, "to_version": 6,
    "changed": [ "_data/stores/0002-evanston.json" ],
    "added":   [ "_data/stores/0304-tulsa.json", "assets/stores/tulsa.webp" ],
    "removed": [ "news/holiday-hours-2025.md" ],
    "redirects_added": [], "redirects_removed": [] }

On a tree, a diff names the files changed, added and removed and the redirects that came and went. On one file it is a line-by-line diff. This is what a reviewer reads before promoting, and what the approver is shown when the environment requires approval.

One release of a site in the portal: its number and note, a dev badge and an Open site button, who published it and from what source, how many files and how large, a Files table with a path filter listing each file's type, size and compression, and a Redirects table with one rule from an old path to a new one.
One release in the portal: its note, its files with a path filter, and its redirect rules.

Everything the agent can do in place

Six actions cover reading and changing a site’s files. All of them existed before sites did.

What the agent can do with a site’s files in place

ActionOn one fileOn a folder or the whole tree
outlineThe file’s structure: headings, sectionsThe files, a page at a time, with the total
locateWhere a phrase or pattern occursWhich files hold it, with files scanned and skipped
get_contentThe file, or one section or line range of itNot available: name one file
statsIts size and shapeHow many files the release holds
diffA line-by-line diff between two releasesFiles changed, added and removed, and redirects
patchA new release with the edits applied, in devNot available: a patch names one file

These are the same six actions the agent uses on a saved report (300 series). A site is edited with tools the agent already has, which is why it does not resend a site to change a sentence. Sharing and deleting are not among them: who can open a site and how long it lives are decided on the site itself.

Several edits, one promotion

Both changes are in dev. They reach the people who use the site the way everything does.

Two edits, one promotion

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_site
  { "command": "promote", "site": "acme-stores", "from": "dev", "to": "stage" }

← { "environment": "stage", "release": 6, "status": "promoted",
    "address": "https://acme-stores--stage.pages.example.com/" }

→ manage_site
  { "command": "promote", "site": "acme-stores", "from": "stage", "to": "prod",
    "reason": "Evanston hours, Tulsa opening, retired 2025 holiday post" }

← { "environment": "prod", "release": 6, "status": "awaiting_approval", ... }

Releases 5 and 6 both happened in dev. The public site went from release 4 to release 6 in one step, after one review and one approval. Visitors never saw the site with Evanston fixed and Tulsa missing. Work accumulates where nobody depends on it and arrives all at once where everybody does.

Who can read and who can change

Reaching into a site’s files through the agent follows the standing a person has on the site, with one extra condition for changes.

Who can read and who can change

To patch or overlay

Manage access to the site, and a persona that includes the Sites tool. An agent edits a site only for someone who could have published it.

To read source, earlier releases and diffs

Manage access. The source of a rendered site and its history belong to the people who build it.

To read what is served

Anyone the environment is shared with. Their agent reads the current files of the environments they can open, as served, and nothing else.

Edits without risk

What comes next

acme-stores is built, public, generated from data and maintained by conversation. Lesson 1007 takes a site ACME already runs somewhere else and brings it onto Plexara with every address intact.

Key terms

Five terms cover how a site is changed in place.

Key Terms

Site reference
mcp:site:<site>/<environment>/<path> for a file, a path ending in a slash for a folder, and mcp:site:<site>/<environment> for the whole tree.
Patch
Find-and-replace edits to one text file in dev. Writes a new release derived from the current one.
Base version
The release an edit was read from. An edit against a release dev has moved past is refused and nothing is written.
Dry run
An edit that reports its diff, how many served files would change, and any template error, and creates no release.
Overlay
A publish with a base: files sent are added or replaced, entries marked delete are removed, and the rest carries over.