Skip to content

Draft, version, live ​

An edit is not a commit. Between the client typing and the repository changing there are three stages, and knowing which one a value is in answers most questions about why a site does or does not show something.

stagewhat it iswhere it lives
draftwhat the client has typed. Every keystroke that survives a field blurour database
versionwhat somebody deliberately kept, to come back tothe site's git repository
livewhat the site actually servesthe site's git repository

Each page carries all three, with a revision number for each. The panel calls them Draft, Version and Live, and no other names; say them so to the client.

Two of the three are commits. The difference between them is not where they live, it is what has been done with them: a version is a commit, and what is live is a version that has been built and put in front of visitors.

Why the live stage is somewhere else ​

Because a build has to be hermetic. When the published content is a commit in your repository, a build is a checkout and a command — it does not call us, it cannot be affected by us being slow, and it can be reproduced a year later from the same SHA.

It also means the backup story and the handover story are the same story. "Give me this client as they were in March" is git checkout, and "we are parting ways" is you keeping a repository that already has everything in it.

What saving does ​

  1. Writes every page's draft into the repository as one commit — save: <slug> at rev <n> — exactly the files a publish writes.
  2. Marks each page's draft as its version.

In that order, and it waits for the commit. If the repository cannot be reached, nothing is saved: the draft is untouched, the previous version is still the one to go back to, and the panel says which of the two happened rather than reporting success it cannot vouch for.

Two consequences worth knowing:

  • A save can be refused. The same check that refuses a publish over content the draft has not seen refuses a save, with the same JTK_E_OUT_OF_SYNC. Import first. It is the same protection, happening earlier and therefore more cheaply.
  • A site with no repository still saves. The checkpoint is real and there is no commit behind it; the response says so with committed: false, and the panel names which of the two happened.

Saving twice with nothing changed writes no commit. The history is meant to be readable. A save after a push that already committed the edit commits nothing either: committed: false, files empty, and the branch's commit is what is built. An import counts and stamps only the pages whose content it changed — a page the branch says as the panel already did keeps its updated_at.

A deletion is saved like an edit. An entry deleted in the panel is an unsaved change until a save carries it: the strip counts it, and the save's commit removes its file. Until then it can be brought back as it was, from the comparison. On a contract-3 site the deletion also takes the entry out of every reference to it, in the same act — a single ref becomes absent, a many list loses that one id and keeps its order — because the judge refuses a reference to an entry the tree does not have. The panel asks first for a field whose on_delete is restrict, the default, and not for one that says nullify. Each document that named it is an unsaved change beside the deletion, saved and published with it, so after the save git pull (or jtk pull) brings them changed; going back to the saved version, or bringing the entry back, puts the id back. An entry you delete from the tree yourself is not followed: take its id out of what names it in the same commit. An import over a deletion no save carried leaves it deleted — on a contract-2 site it is refused with JTK_E_DRAFT_AHEAD, like any unsaved work — because the branch still has the file. On a launched site the entry leaves visitors' view when the version is published — and the booking form with it: a deleted service or class is still offered, and bookable, while the site shows it. A deleted master, car or table stops taking bookings at once, because the diary is kept against it. A service leaves the site at once only by a person's switch in the panel.

What publishing does ​

  1. Copies every page's draft into its published snapshot.
  2. Writes those snapshots into the repository as one commit — jtk/pages/<path>.json for pages, jtk/entries/<collection>/<slug>.json for collection entries, each language's words in a translation beside its original (<name>.<locale>.json), jtk/shared.json for the text that is on every page, a module's settings — jtk/modules/bookings.json — when the schema turns one on, and jtk/site.json, the platform's own. A file that says what the branch already says is kept byte for byte, so the commit holds only what changed. On a contract-2 site the same commit writes jtk/content/ and jtk/bookings.json. The files has each shape.
  3. Queues a build from that commit.

If the draft and the snapshot are already identical, nothing happens and no build is queued. That is reported rather than hidden — a publish that changed nothing is worth knowing about.

Only a person with the right to publish changes what visitors see, and only from the strip under the header: no card publishes, the hours included. Taking an entry on or off a launched site with its switch is a publish, and asks the same right. Without it — an agent always — the switch changes the draft, and the next save carries it.

A launched site goes live only on code that passed the platform's checks. They judge the code, whoever started the build. A save that changed only content keeps the verdict of the code it was made on. A person's build of new code that fails goes on, so the preview shows it, and publishing it is refused with JTK_E_CODE_UNCHECKED until the code is fixed and built again.

Editing in your editor instead ​

Writing a post by hand in jtk/entries/ — or its translation beside it — is supported, not tolerated: a commit there is the published state, and importing the branch brings it back as the draft. A file you write needs its id and its _keys; npx @jtakeit/astro schema mints them.

The one thing to watch used to be that a hand edit on the build branch did not survive a publish that happened before it was imported, because publish writes the whole file. That is no longer something to watch. A save whose draft has not seen the branch's current content brings it in first and lays the unsaved changes over it (synced in its answer); a branch that moves in the second between is refused with JTK_E_OUT_OF_SYNC. Nothing is overwritten and nothing is lost.

The other direction is guarded too. An import does not write over unsaved work: while the panel holds changes that are in no commit — something the client typed and nobody saved — a contract-3 import brings in every document they did not touch and the branch's other fields of those they did, their changes staying on top; a document where both changed one field waits, named in waited, and a contract-2 import_branch stops whole with JTK_E_DRAFT_AHEAD. Read what they wrote with get_content and carry it into the branch, or ask them to save; pass overwrite_draft: true only to discard it on purpose. A push_code over such work lands its code and leaves what waits in the branch: the panel's next save — commit_and_build, or the owner's — brings it in first and lays their changes over it, theirs standing where both changed one field, and commit_and_build's dry_run says it is waiting (pending). Even then the discarded words stay in the site's history: the import is an edit from the code that says what each value was before it, and a person can copy an entry's old value back. A draft that is saved is a commit on the branch, so bring your copy to it before you commit, every time: git pull, or — for code held on jtakeit, which has no remote to pull from — pull_code and the jtk pull it answers with.

The person's edits are never written over. A push from an older copy meets the person's saves on the branch. On a contract-3 site a content file both of you changed is merged by field — their heading and your hours in one page are both kept — and only one value both of you changed differently is refused, JTK_E_CODE_CONFLICT, with the field and both values (fields: theirs, yours). Keep theirs: tell the person what they changed and that you left it, then write again from a fresh read; write over it only on their word. Every push names what the branch changed since your copy, by field (person_changed). And commit_and_build asks before it saves a person's draft: while the panel holds their unsaved changes it is refused, JTK_E_THEIR_DRAFT, naming them. Ask them; on their yes pass with_their_draft, or build your commits alone with branch_only and leave their draft unsaved.

Rolling back ​

A rollback points the site at an earlier build's artefact — the site is serving last week's pages again within seconds.

It is a person's, in the panel: there is no MCP tool for it. An agent whose build went wrong fixes the source and runs commit_and_build.

It also holds the site there, and that is not a convenience. The artefact now disagrees with the repository, so the next build would quietly undo the rollback. While the hold stands, only builds of the held commit go live; a build of anything newer lands as the candidate, and its log says JTK_E_PUBLISH_HELD. A person lifts the hold in the panel once the source is fixed. A rollback restores what is served; it does not fix what is wrong.

Snapshots ​

Every write to a page's draft leaves a snapshot, and the last thirty per page are kept. They are the platform's record, not a screen: nothing in the panel or the MCP server lists or restores them today. Going back is the three stages — the draft back to the version, in the panel; the site back to an earlier build, by a rollback.

The version is different in kind — it is per site, somebody chose it, and it is a commit you can check out.