Editing a page
You want to change a page that already exists. Which move you make depends on what changed and what status the page is in. This page is the decision; each path links to the command that does the work.
The decision at a glance
| The page’s change is… | Do this |
|---|---|
| An input change (keywords, a config rule, a reference table, a body-determining column) | Don’t touch the page. Change the input → gtmesh plan → gtmesh apply. Reconcile emits the right action (rewrite / redirect; a link move just re-projects the manifest). |
A hand edit to a page still in writing | Just edit the bundle, then gtmesh page seal. No amend — it’s already open. |
A hand edit to a sealed page (review / ready / published) | gtmesh page amend <slug> → gtmesh page seal <slug> → gtmesh page publish <slug>. |
| The prose is wrong enough to start over | gtmesh page recreate <slug> — a full re-author (heavier than amend). |
The rest of this page is just those rows, expanded.
First: is it really a hand edit?
Usually not. The committed graph is desired state, so the durable way to change a page is to change what feeds it — then let the engine reconcile. Retarget a keyword, edit a config rule, fix a reference table row, and:
gtmesh plan # see the diff (read-only)
gtmesh apply # enact it — emits rewrite / redirect per pageReconcile picks the action for you: a body-input change is a
rewrite (the writer reruns), a slug move is a
redirect, and a projection-only change (mesh links, cards) isn’t an action at all — it
re-derives into site.manifest.json with no writer. See
Lifecycle & reconcile for the full table.
Never hand-edit the committed graph (graph/nodes.jsonl, graph/edges.tsv). It’s computed — apply,
seal, and the lifecycle commands are its only writers. To change a node, change the input and re-plan.
Reach for a hand edit only for an out-of-band body change the input diff can’t see: a one-off copy tweak the writer wouldn’t reproduce, or a skill placing generated asset files into the bundle.
Then: what status is the page in?
A hand edit’s follow-up depends entirely on whether the page has been sealed yet.
Still writing
A freshly apply-scaffolded page (or one you’ve recreated) is open. Just edit the bundle and seal
— no amend:
# edit content/<slug>/index.yaml
gtmesh page validate <slug> # schema + editorial lint — the writer's self-check
gtmesh page seal <slug> # → review, stamps the provenance hashesLink to other mesh pages with a symbolic ref, never a
literal URL. Write [the SRU pump](ref:page/products/alfa-laval-sru) (a page by its stable id) or
[its hub](ref:links/up/0) (self-relative: this page’s first up-link) — gtmesh build resolves the
token to the live URL, so the link re-resolves after a rename or when a new hub takes that slot. A
hardcoded internal URL (your own domain, or a root-relative /path) is a validate error. So is a
ref that doesn’t resolve (an unknown page id, or a ref:links index out of range). External links stay
normal URLs.
Already sealed (review / ready / published)
A sealed page carries stamped provenance hashes. Editing its body out of band leaves those hashes
stale, so you re-open it with amend and re-seal to re-stamp:
# edit the bundle (or a skill places assets)
gtmesh page amend <slug> # → needs_update ("this body changed; re-seal it")
gtmesh page seal <slug> # re-validate + re-stamp the body hash → review
gtmesh page publish <slug> # ship it againamend only flips the status, so whether you run it just before or just after the file edit doesn’t
matter — what matters is that a sealed page gets amend and a re-seal, or its stamped hash drifts
from the body and gtmesh doctor flags it. The canonical order is edit →
amend → seal → publish.
amend vs. recreate
Both re-open an already-built page, but they’re different weights:
amend | recreate | |
|---|---|---|
| For | A body edit that isn’t a prose rewrite | Prose that’s wrong enough to start over |
| Classic case | Placing generated images (the image-director skill runs it) | A page whose whole angle is off |
| Effect | → needs_update; you re-seal the existing body | → writing; the writer authors a fresh body over the old one (which stays on disk until then) |
| Prose | Untouched | Rewritten from scratch |
A prose rewrite driven by an input change is neither — that’s the rewrite reconcile action
from apply, and it keeps placed assets, so image work is never undone by a later content edit.
The image seam
The most common sealed-page edit is placing images, and it follows the amend path exactly — the
image-director skill authors the files and runs amend for you. See
Images and the
re-seal seam.
Related
- Lifecycle & reconcile — every reconcile action + the status path in full
- The page registry — why you change inputs, not outputs
amend·recreate·seal— the commands this page routes to- Writer & quality gate — the write flow a
writingpage is in