# jtakeit — the whole documentation
Schema contract 3. Generated from the source; do not edit.
---
# jtakeit
A back office for small businesses, with the website it runs: a CMS the owner
edits by tapping their own page, bookings, enquiries, payments, analytics and
hosting, behind one panel. Nobody is expected to hand-write a site here: an
agent writes the schema, the pages and the content, a repository versions
them, and the platform runs the part a studio does not want to operate — the
panel the business owner uses, the enquiries, bookings and orders, the
billing, the backups, the domain.
Of all of it, the diary is the part no agent writes in an evening: rates by the
hour of the week, a stay by the night or a hire by the day, several of one class
in one booking, a party seated at the smallest table that fits, seats and spots,
add-ons with no time of their own, paid online or on the spot — ten kits with a
trade's defaults, and `preflight` booking and cancelling end to end before
anybody else does.
**In a hurry:** [start here](guides/start.md) — the first site in twelve
steps, the rule at each.
The agent in your session writes the site. The platform gives your client an
admin panel they can use, a preview to sign off on before they pay, somewhere
for the enquiries, bookings and orders to go, a host to serve it from, and a way for you
to get paid. **Hand over the client without handing over the code.**
What the studio gets out of it, in one breath: reselling — a wholesale price
per live site and nothing for a site before its launch, its own price to its
client on top, and the difference kept whole; the choice of invoicing the client
itself or billing them through the platform on its own Stripe, which is part of
every site and never a percentage; a
diary that takes paid bookings straight to the business's Stripe; a handover
that walks the studio out of the loop with one link; and a dev session that
frames the local dev server with the owner's real text before anything is
pushed. [The panel, by hand](guides/the-panel.md) has each of these by screen
and by person.
> **This is `0.x`.** The contract may still change between versions, and
> [the changelog](changelog.md) says what moved and what to do about it.
## The shape of it
Three things are true, and everything else follows from them:
**Git owns what is published; the database owns what is being edited.** A site's
design, its schema and its published content all live in that site's own
repository. Drafts live in ours. This is what makes a build hermetic, what lets
you keep your code, and what makes "give me this client as they were in March" a
checkout rather than a support request.
**The repository decides what a site is; the admin only fills it in.** There is
no "add a page" button and no "add a block" button, and their absence is
deliberate. A form that could invent a block your template does not render is a
form that produces a broken site in front of your client. What the admin can do
is bounded by what your schema, `jtk/schema.json`, declares, and you write that file.
**A new site is a row, not a deployment.** One service, one database, one edge
worker, however many sites. Nothing is provisioned per client.
## Start here
- **[Connecting a site](guides/connecting-a-site.md)** — the five things that
have to be true, and how to check each one.
- **[The schema format](reference/catalogue.md)** — what you declare in
`jtk/schema.json`, with worked examples that CI judges on every commit; and
[the files under `jtk/`](reference/jtk-files.md) that hold the content.
- **[Translations, key by key](reference/translations.md)** — the translation
file: which values it holds, their paths, its records and what is refused.
- **[Field kinds](reference/field-kinds.md)** — every kind, and what `min` and
`max` mean for each (they do not mean one thing).
- **[Modules](reference/modules.md)** — bookings: what the schema points it
at, what it reads from an entry, and what the owner is asked.
- **[A site in several languages](guides/languages.md)** — one original, a
translation beside it holding only the words, and what is left to translate.
- **[Draft, version, live](guides/the-three-stages.md)** — what an edit is
before it is a commit.
- **[When something is wrong](guides/troubleshooting.md)** — by symptom, and by
[error code](reference/errors.md).
- **[Driving it from an agent](guides/mcp.md)** — the MCP server, and what it
deliberately will not do.
- **[The panel, by hand](guides/the-panel.md)** — everything the tools do not
do, where it is done and by whom; and [who can do what](reference/who-can-do-what.md),
generated from the code that enforces it.
## For agents
[`llms.txt`](llms.txt) is the map. [`llms-full.txt`](llms-full.txt) is every page
in one file, in reading order — about a hundred thousand tokens, so read single
pages unless you need the whole. Both are resources of the MCP server too, and
every link a resource carries is a `jtakeit:///` URI the server can open.
Every refusal — from the schema judge, from a build, from the annotation lint —
carries a `JTK_E_` code with a path and a line of what to do. Look it up in
[the error reference](reference/errors.md) rather than interpreting the prose.
---
# Start here: the first site, in twelve steps
The card: each step's tool or command, the rule that bites there with its
code, and the page that says why. Read the pages when a step is yours.
1. **The brief** — every question at once, before `create_site`;
build on the yes: the stack (offer Astro), the currency,
**paid online or on the spot** (ask, never assume), where enquiries go,
the language, the design, the photographs, the icon. Bookings take
their kind's kit whole; a shop, `jtk add shop`.
→ [the brief](the-brief.md), [kits](../reference/kits.md), [the shop](shop-on-the-site.md)
2. **Make the site** — `create_site` with the slug, the name, `locale`,
`locales`, `bookings` (a kit's kind), `shop`, `blog`, `design`; with
bookings or a shop the brief's `currency` (asked, never guessed). The kit's `jtk create` commits contract 3, the quick
template in Brumy's design (brumy.ch) — [`design: custom`](the-brief.md#a-custom-design)
is a stage; its words and people are
placeholders — write the site in their language before they look. `next` says the first build; give a
person `get_preview_link` now. With a terminal: `scaffold: false`, then
`npx @jtakeit/astro create
` (the same options), the dev server,
`open_dev_session` and its `run`; give the developer the localhost.
Fill `BRIEF.md` from the first answer.
→ [connecting a site](connecting-a-site.md), [working on a site locally](working-locally.md)
3. **Declare the blocks** in `src/content/blocks.ts`;
`npx @jtakeit/astro schema` writes `jtk/schema.json`, mints missing
`id`s and `_key`s — `JTK_E_UNNAMED`. A service has `takes`; a price
is `costs` **or** `rates`; two rows on a minute are two prices —
`JTK_E_DIARY_NOT_READY`.
A date, an hour, a link is the owner's even unshown:
`no_tap_target`, `beside` its field — `JTK_W_OWNER_LOCKED`. Entry
types: `form`, `ends_by` (`ended`), `JTK_W_DATE_HIDES`.
→ [the schema](../reference/catalogue.md), [modules](../reference/modules.md)
4. **Write the content** — a page `jtk/pages/.json`, `{id, path,
name, seo, blocks}`; an entry `jtk/entries//.json`, its
values under `fields`; the text on every page `jtk/shared.json`. A value
is its kind's: minutes for a time, `{"minor": 4500}` for money, an id for
a `ref` — `JTK_E_DOCUMENT_INVALID`. **Another language** is
`..json` beside the original, `of` its id, only the words by
`_key` — a price there is `JTK_E_TRANSLATION_SHARED`; what is booked is in
every language; `get_site` says what is left to translate.
→ [the files under jtk/](../reference/jtk-files.md), [several languages](languages.md)
5. **The settings** — `jtk/modules/bookings.json` is `{"v": 1, "settings":
{…}}`, each row with its `_key`. A business open past midnight writes the
hours after it on the calendar day whose clock shows them. A service
priced by the hour of the week covers every open hour, or the uncovered
hour is not sold — `JTK_W_UNPRICED_HOURS`.
→ [bookings on the site](bookings-on-the-site.md)
6. **Judge before the push** — `validate_schema` with the schema,
**the `jtk/` files**, translations too (`jtk schema --judge` from the
tree), and `site_id`: the settings, the entries and the currency in one
answer. Act on advice — a service as a post, hours typed twice —
`JTK_W_MODULE_POST`, `JTK_W_MODULE_TWIN`.
→ [the contract](../reference/contract.md)
7. **Annotate** — every field a person taps carries `data-jtk-path`, read
off the built HTML, never the component: `jtkit lint dist/` on your
build — `JTK_E_UNANNOTATED_FIELD`. An enquiry form's controls are the
block's `asks` — `JTK_E_FORM_FIELD_UNDECLARED`.
→ [connecting a site · annotations](connecting-a-site.md#2-annotations)
8. **Push, then** `commit_and_build` — nothing public. `get_site`
says where the code lives (`code`). First push: a GitHub remote in the
copy → ask once (that repository, with our App a person installs, and
`attach_repo`; or jtakeit); none → `push_code`, run its command, and say
so. `get_build` until it settles, else `get_build_log`. «That slug is taken» with no id is another account's site.
→ [draft, saved, published](the-three-stages.md), [where the code lives](connecting-a-site.md#4-where-the-code-lives)
9. **Read what was built, and look at it** — `get_built_page` is the
HTML; with `shot: "phone"`, the page as a visitor's phone draws
it, in frames.
10. **Preflight** — `preflight` with `try_booking` (a shop: `try_order`) before
saying done: the form says what it sends in `data-sends`, and a field the
platform does not take is dropped from a stranger's booking —
`JTK_E_BOOKING_FIELD_UNKNOWN`.
→ [bookings on the site · the form](bookings-on-the-site.md#the-form-is-the-sites-not-the-kits)
11. **Hand over what is a person's** — the launch, the channel the
enquiries go to, the domain, another agent: the panel does those, and
`preflight` says whose step each is. You cannot read the client's
customers.
→ [driving it from an agent](mcp.md), [your client's data](your-clients-data.md)
12. **Later** — pull first (`git pull`, or `pull_code` and `jtk pull`);
commit; `push_code` or `import_branch`; `commit_and_build`. Content
not imported — a git push, or a document where you and the person's
unsaved work changed one field (`JTK_E_DRAFT_AHEAD`, named in `waited`) —
waits in the branch until the next save or the
editor's opening brings it in under the draft; after launch the words are the panel's, the shape and seed text the
repository's. `get_site` says what the panel holds unsaved, and on a
launched site a build is a candidate a person publishes.
→ [working on a site locally](working-locally.md)
When a tool refuses, the code is the page: [every error code](../reference/errors.md).
---
# The contract, one line each
What the platform enforces, and its code, checked before
`validate_schema`, after [the brief](../guides/the-brief.md); [every error code](errors.md).
## The files
Contract 3:
- `jtk/schema.json` is written from `src/content/blocks.ts` by `npx @jtakeit/astro schema`, minting missing `id`s and `_key`s; else yours — `JTK_E_SCHEMA_UNREADABLE`, `JTK_E_UNNAMED`
- a page is `jtk/pages/.json` (`/` is `index.json`), `{id, path, name, seo, blocks}`; an entry `jtk/entries//.json`, `{id, collection, slug, rank, visible, seo, fields, blocks}`; the shared text `jtk/shared.json`; a module's settings `jtk/modules/.json`, `{v, settings}` — `JTK_E_DOCUMENT_INVALID`
- a value is its kind's: minutes for `time_of_day`, `duration`, `{"minor": 4500}` for `money`, `{"src", "alt"}` for a picture, `src` a library key (`media_link`), an entry's `id` for a `ref`; empty is absent; past `min`/`max` is advice — `JTK_W_CONTENT_BOUNDS`; an undeclared one is kept, shown nowhere — `JTK_W_CONTENT_ORPHAN`
- a translation is `..json` beside its original: `of` its id, `locale`, only the words, by `_key` — a shared value `JTK_E_TRANSLATION_SHARED`; `translated` records `{from, by, at}`, best left out, never invented — `JTK_E_TRANSLATION_RECORD`; words for a key the original lacks — `JTK_W_TRANSLATION_ORPHAN`
- `jtk/site.json` is the platform's; the currency is `create_site`'s, or its `currency` while it has none, then a person's — `JTK_E_CURRENCY_SET`
- contract 2, until `jtk upgrade contract-3`: `jtk/catalogue.json` — `JTK_E_CATALOGUE_UNREADABLE`, `JTK_E_CATALOGUE_EMPTY`; `jtk/content/`, an entry under its `prefix` — `JTK_E_ENTRY_NO_COLLECTION`, `JTK_E_CONTENT_FILE_INVALID`
- shapes: [files under `jtk/`](jtk-files.md)
## The schema
- `contract: 3`, `generator`, `locale` (the original's), `locales`, BCP 47; no blocks is empty; an unknown key refused — `JTK_E_CONTRACT_UNKNOWN`, `JTK_E_GENERATOR_INVALID`, `JTK_E_LOCALE_INVALID`, `JTK_E_SCHEMA_EMPTY`, `JTK_E_SCHEMA_KEY_UNKNOWN`
- a block declares `type`, `v` (raised: `upcast`), a `label` and a field; a field `key`, `label`, `kind` — `JTK_E_BLOCK_VERSION`, `JTK_E_UPCAST_INVALID`, `JTK_E_BLOCK_EMPTY`, `JTK_E_LABEL_MISSING`, `JTK_E_KIND_UNKNOWN`, `JTK_E_TEXT_INVALID`
- names are `snake_case`, unique among siblings; a `select` has `options: [{value, label}]`; sane `min`/`max`; a `list` has `of`; a `media` says what it holds — `JTK_E_NAME_INVALID`, `JTK_E_NAME_DUPLICATE`, `JTK_E_SELECT_NO_OPTIONS`, `JTK_E_BOUNDS_INVALID`, `JTK_E_LIST_INVALID`, `JTK_E_MEDIA_INVALID`
- `localized` on text, a picture, a link, a list; `integer` on a number; `qualifiers` on money; `untranslated` is `base`/`hide` — `JTK_E_ATTRIBUTE_INVALID`
- `shared` lists the shared text's block types; a field there may say a `role`, each once — `JTK_E_SHARED_INVALID`
- `render: "live"`, kept — `JTK_W_NOT_LIVE`
- a collecting block says what; `views` name real fields — `JTK_E_COLLECTS_UNKNOWN`, `JTK_E_VIEW_INVALID`
- what the owner edits is `client_editable: true`, `data-jtk-path` where drawn, any kind — `JTK_E_UNANNOTATED_FIELD` (phone, date, choice: `JTK_W_UNANNOTATED_FIELD` for now); drawn, untappable — `JTK_W_DRAWN_UNTAPPABLE`; derived: `data-jtk-from`; unshown: `no_tap_target`, `beside` its field (`JTK_W_HIDDEN_UNEXPLAINED`), a link its button's (`JTK_W_LINK_NOT_BESIDE`); `titled_by` a label — `JTK_E_BESIDE_INVALID`, `JTK_E_TITLED_BY_INVALID`; owner-locked date, hour, price — `JTK_W_OWNER_LOCKED`
- a collection's `type` is a declared block; `route` `{detail, listing, per_page}`/`"none"` + `shown_on`; `order` `"manual"`/`{by, desc}`; `ends_by` → `ended` (`JTK_W_DATE_HIDES`); a `ref` `{to: [collection], many}` — `JTK_E_COLLECTION_INVALID`, `JTK_E_ENTRY_TYPE_INVALID`, `JTK_E_ORDER_INVALID`, `JTK_E_ROUTE_INVALID`, `JTK_E_REF_INVALID`
- an entry type's `form`: `sections`, `aside`, `widgets` — `JTK_E_PANEL_FORM_INVALID`, `JTK_W_PANEL_FORM_GUESSED`
- `modules` turns one on, at the schema's collections — `JTK_E_MODULE_UNKNOWN`, `JTK_E_MODULE_ROLE_INVALID`
- a product: one SKU a site, any case; picks name each option; 1–2,000 variants — `JTK_E_SKU_TAKEN`, `JTK_E_PICKS_INVALID`, `JTK_E_PRODUCT_INVALID`
- a service has `takes` and, to be paid, `costs` — or `rates`: day · from · until · costs rows, not with `costs`, none overlapping (`JTK_E_DIARY_NOT_READY`); an unpriced open hour — `JTK_W_UNPRICED_HOURS`; rows may name units, a service its `per`; priced without `takes` is an add-on — `JTK_W_ADDON_ALONE`; a resource may carry `hours` within the business's (`JTK_W_SESSION_OUTSIDE_HOURS`), `does`, `seats` or `spots`
- what a module books is in every language: no `untranslated: "hide"`, no `visible: false` in a translation
- a fact lives once: hours in the settings, prices in services — `JTK_W_MODULE_TWIN`, `JTK_W_MODULE_POST`
- bookings settings: `kind`, `locale` pick the words (`JTK_W_KIND_UNKNOWN`, `JTK_W_KIND_MISSING`, `JTK_W_LOCALE_FALLBACK`); `words` override keys, placeholders kept (`JTK_E_MODULE_FILE_INVALID`, `JTK_W_WORD_UNKNOWN`); `hand_out`, no day rates — `JTK_W_KIND_NO_DAYS`; old `kit_version` — `JTK_W_KIT_BEHIND`; no `zone`/`hours` — `JTK_W_DIARY_UNSET`
- format: [schema](catalogue.md), [field kinds](field-kinds.md), [modules](modules.md)
## The build
- one kind of build, for the site's address: no `noindex`, no `Disallow: /`, a sitemap of every page on `SITE_URL`, a canonical on that host — `JTK_E_NOINDEX`, `JTK_E_ROBOTS_DISALLOW`, `JTK_E_SITEMAP_EMPTY`, `JTK_E_CANONICAL_ELSEWHERE`
- every content page is built, in every language; every shared field is drawn — `JTK_E_PAGE_NOT_BUILT`, `JTK_E_SHARED_NOT_RENDERED`
- an enquiry form declares `collects`, renders the contract's fields only — `JTK_E_FORM_INCOMPLETE`, `JTK_E_FORM_UNDECLARED`, `JTK_E_FORM_FIELD_UNDECLARED`
- a `data-jtk-path` names a declared place by key (`blocks[hero].title`, `entry::title`); the schema is committed — `JTK_E_ANNOTATION_UNKNOWN`, `JTK_E_CATALOGUE_MISSING`; optionals empty, full — `JTK_E_CONTENT_VARIANT`
- code is judged once: a content-only save keeps its verdict; failed code never goes live — `JTK_E_CODE_UNCHECKED`
- a build reaches GitHub, npm, yarn, the media host, Google Fonts only — `JTK_E_BUILD_REACH`
- `dist/_meta.json`: `redirects`, `immutable` hashed dirs, `cache` lifetimes, no `drafts` — `JTK_E_META_INVALID`; a kept file keeps its bytes — `JTK_E_CACHED_FILE_CHANGED`
## The order
1. `create_site` (`currency` when priced, `design`); `open_dev_session` shows pages
2. `npx @jtakeit/astro schema`, then `validate_schema` — the whole tree: as text with `site_id` before a push, by site and ref after
3. `push_code`; no shell: `read_files`, `write_files`; GitHub: `attach_repo`, our App, by a person; all import
4. `commit_and_build` — nothing public; `trigger_build` only rebuilds — `JTK_E_OUT_OF_SYNC`
5. `get_build`, `get_build_log`, `get_built_page`; `get_preview_link` for a person
6. `preflight` — currency, shared text; `custom`: `JTK_W_TEMPLATE_DESIGN`, `JTK_W_DESIGN_AXES`, `JTK_W_DIRECTIONS_ALIKE`; `JTK_W_FIRST_SCREEN`, `JTK_W_ANCHOR_LANDING`, `JTK_W_SCREEN_FIT`, `JTK_W_RAGGED_GALLERY`, `JTK_W_BOOKING_LINK`; `try_booking`, `try_order`, `self_check` — `JTK_W_PAYMENT_UNCHECKED`
7. later: pull (`git pull`, `pull_code` + `jtk pull`); commit, `push_code` or `import_branch`, `commit_and_build` — unsaved work: `JTK_E_DRAFT_AHEAD`, the save lays it over
## The boundaries
- no tool writes content or structure but by a commit, imported, published
- no agent reads enquiries, bookings, orders, members
- a launch, a domain, an invitation, another agent — a person's, in the panel — `JTK_E_NO_BUSINESS`, `JTK_E_NO_DESTINATION`, `JTK_E_PLAN_SHORT`
- on a launched site an agent's build is a candidate a person publishes, or rolls back, holds — `JTK_E_PUBLISH_HELD`
- ten demo sites, 30 builds a day an account by default
---
# Connecting a site
Five things have to be true before a repository is a site the platform can serve.
Each is checkable, and the point of this page is that none of them requires
asking anybody.
1. The repository has a **schema**, `jtk/schema.json`, that validates, and
its content files under `jtk/` in the shapes the schema gives them.
2. Every content field the page renders carries a **`data-jtk-path`**.
3. The build produces a **`dist/`** the way `pipeline.sh` expects (§3). The
platform ships one scaffold, `npx @jtakeit/astro create`, and it is Astro:
`create_site` runs it on the platform and commits its tree as the site's
first commit, so a site made there is all five from the start; with
`scaffold: false` the site is the row alone and you run it yourself. On
any other generator you lay the site out yourself, to the same contract,
and the build does not care which.
4. The site has **its code** somewhere the platform reaches: on jtakeit itself
(`push_code`, or `write_files` from a chat with no terminal), or in a
GitHub repository our App is installed on
(`attach_repo`). The site row names it (§4).
5. Somewhere for **enquiries** to go, if any block collects them.
## 1. The schema
The schema, `jtk/schema.json`, is the one file you write by hand — or rather, the one file
your generator writes and you read. It declares the blocks your site is made of,
its collections, its modules and its languages, and through them what the admin
will let your client edit. The platform's own
scaffold, [`@jtakeit/astro`](https://github.com/jtakeit/jtakeit-kit), derives it from
`src/content/blocks.ts` with `npx @jtakeit/astro schema`, gives every page and
entry its `id` and every block, row and picture its `_key` where a file has
none, and checks the schema against the built pages both ways; start there. On
another generator the file is yours to write, by hand or by a tool of your own
(`npx @jtakeit/kit schema --declaration ` is the scaffold's), and the
judge below reads it the same way — it is JSON, and nothing about it says what
rendered the pages.
The content sits beside it, one file per document, each in its own place:
`jtk/pages/.json` for a page, `jtk/entries//.json` for
an entry, `jtk/shared.json` for the text on every page, `jtk/modules/.json`
for a module's settings, and a translation `..json` beside each
original ([a site in several languages](languages.md)). `jtk/site.json` is the
platform's, written by its saves.
The [format reference](../reference/catalogue.md) has the shape and worked
examples, and [the files under `jtk/`](../reference/jtk-files.md) each file's.
The short version is that a block declares fields, a field declares a
[kind](../reference/field-kinds.md), and `client_editable` on each field is what
decides whether the client may touch it at all.
Judge it before you commit it — the schema and every `jtk/` file beside it, so
the content is judged with it:
```
POST /v1/registry/validate
{ "catalogue": "",
"files": [{ "path": "jtk/pages/index.json", "text": "…" }] }
```
`validate_schema` is the same judge from the MCP server, and with `site_id` it
holds the tree to the site as its import will (a new currency in
`jtk/site.json` is `JTK_E_CURRENCY_SET`).
It answers with **every** finding at once, not the first — so an agent fixing a
schema does it in one pass rather than one build per mistake:
```json
{
"ok": false,
"contract": 3,
"findings": [
{
"code": "JTK_E_KIND_UNKNOWN",
"path": "blocks.hero.title.kind",
"says": "blocks.hero.title has kind \"colour\", which nothing knows how to draw or check"
}
]
}
```
`path` is a dotted address into the file. `code` is one of
[these](../reference/errors.md), and the reference says what to do about each.
### The contract number
The schema carries `"contract": 3`. It answers one binary question — can this
service read this file — and it is not a semver: a service meeting a *newer*
one refuses loudly rather than half-reading it, and a refusal in that direction
is a deploy to do, not a repository to fix.
An older site may still be on **contract 2**: its schema is
`jtk/catalogue.json` (written by `npx @jtakeit/astro catalogue`), its content a
document per page and per language under `jtk/content/`, its bookings' settings
`jtk/bookings.json`. The platform keeps reading and writing such a site as it
is, and never rewrites a format on its own. `jtk upgrade contract-3` moves it in
one commit, and the import that reads `jtk/schema.json` switches the site; the
platform's team moves every live site itself. A tree with both files is
refused, and so is a contract-2 tree pushed to a site already on contract 3.
## 2. Annotations
Every value a page renders that a client may edit must be on an element carrying
its path. On the scaffold the kit's door writes it — a template never writes a
path:
```astro
---
const hero = site.page('/', locale).block('hero');
---
{hero.text('title')}
```
This is how the visual editor knows what was tapped. **It fails silently when it
is missing** — the sheet simply stops opening on that heading, and nobody finds
out for a week — which is why it is a gate rather than a convention. The
annotation lint compares your built HTML against your schema in both
directions and fails the build on a mismatch
([`JTK_E_UNANNOTATED_FIELD`](../reference/errors.md#jtk_e_unannotated_field)).
It reads the **built HTML**, never your component source. That is deliberate: it
then works with any template, including one an agent wrote this afternoon.
A path names its place **by key**, never by position — a block, a row and a
picture by its `_key`, a document by its `id` — so moving a block changes no
path:
| | |
| --- | --- |
| `blocks[hero].title` | a field of the block whose `_key` is `hero`, on this page |
| `blocks[faq].items[r7k2].answer` | a field of a row of a list, by the row's `_key` |
| `blocks[work].pictures[g2x9].src` | a picture of a gallery. The words beside it are edited in the panel and carry no annotation |
| `title` | an entry's own value, on the entry's own page (its `fields`) |
| `shared:blocks[contacts].phone` | the text that is on every page — see `jtk/shared.json` |
| `entry::title`, `page::blocks[hero].title` | a value belonging to *another* document, as a listing tile does |
The path is the same in every language: a document's identity spans its
languages, and the page's language says which words the owner is editing.
On a contract-2 site the same places are named by index —
`blocks[3].title`, `shared:blocks[0].note`,
`page:/blog/healing:blocks[0].title` — and the door writes that grammar there,
so a template reads the same under both.
Every value the owner edits is annotated where it is drawn, whatever its kind:
a phone, an email, a choice drawn as its label, a date or an hour drawn
formatted — the owner taps whatever they see. Two values drawn as one, «8000
Zürich», are two elements, each with its path. A list is tapped by its rows, a
switch by what it switches, and a field with `client_editable` not `true` asks
for nothing. For now a phone, an email, a link, a choice, a date, an hour or a
number drawn without its path is advice
([`JTK_W_UNANNOTATED_FIELD`](../reference/errors.md#jtk_w_unannotated_field));
a contract-3 build will refuse it as it refuses a heading. A value the owner
edits that the page draws as text where nothing answers a tap — under
`data-jtk-fixed`, or under no annotation at all — is said too
([`JTK_W_DRAWN_UNTAPPABLE`](../reference/errors.md#jtk_w_drawn_untappable)).
What a page works out rather than draws — «Jetzt geöffnet» from the hours, a
week of opening hours run together, a postcode and a city that cannot be drawn
apart — names
its source with `data-jtk-from`, a path's document and block without a value:
`blocks[]`, `shared:blocks[]`, `page:` and `entry:` (each
may go on `:blocks[]`), `module:`. The kit's door writes it
(`shared.from()`, `facts.from()`). A tap anywhere in that element opens the
source in the panel, read-only, with what the site works out from it; a source
that is not there fails the build
([`JTK_E_ANNOTATION_UNKNOWN`](../reference/errors.md#jtk_e_annotation_unknown)).
The design's own words keep `data-jtk-fixed`: a tap on one says it is the
site's design, and inside a region that names its source it opens the source.
A link among them is offered in the panel, not followed.
A value the owner edits and the page does not show — the hour a countdown
counts to, a photograph's description — is `no_tap_target: true`, and says
where it belongs with `beside`: the key of the field the owner taps, in the
same block or row. The panel opens it under that field, as it opens a
button's address under its words — so a button's link says `beside` its
words (`"beside": "cta_label"`); without it the panel guesses by the names
([`JTK_W_LINK_NOT_BESIDE`](../reference/errors.md#jtk_w_link_not_beside)).
One with nothing to go beside is under **More**, at the foot of the editor of
every field of its block; give it a `hint` that says what it does, since the
owner cannot see it
([`JTK_W_HIDDEN_UNEXPLAINED`](../reference/errors.md#jtk_w_hidden_unexplained)).
A value whose title on the page is the owner's too — «Вход» over «18+», which
may become «Цена» over «30 CHF» — says so with `titled_by: ''`,
and the panel names the value by what that field holds, falling back to its
own `label` while the field is empty.
Where a script reads such a value from an attribute — a countdown reads the
hour off the ticket — say so with `data-jtk-bind`, pairs of
`:` separated by spaces:
```astro
```
The editor writes the value into that attribute as the owner types and
dispatches a `jtk:bind` event on the element, so the preview moves before the
next build. Read the attribute when you use it (on each tick), or listen for
the event. Only `data-` attributes are written; a bind to a field the document
has not got fails the build
([`JTK_E_ANNOTATION_UNKNOWN`](../reference/errors.md#jtk_e_annotation_unknown)).
A row the owner adds to a list in the panel is a copy of the list's last
element, made by the editor: it carries none of the listeners your script put
on the rows at load. A question in an accordion added that way does not open.
Listen on the page and find the row from the event (`event.target.closest(…)`),
or wire the row on `jtk:row`, which the editor dispatches on it with
`{list, index}`.
### A site whose code is held by the platform
A site whose code lives on jtakeit — pushed there with `push_code`, or come
from another studio (wiki/85) — says `code: platform` (and `code_held: true`).
Work on it with `pull_code` into an empty directory and `push_code` after
(§4). To move it to GitHub instead, create an **empty** repository (no README,
no licence), have a person install our GitHub App on it, and `attach_repo`
it: the platform pushes the code and the content into it, with their history,
before reading it back. Then clone it as usual.
## 3. The build
Your repository is built by `pipeline.sh` in a container: install, build, lint
the annotations, upload `dist/`. The container holds no credential at all —
the clone is authorised on its way out by the platform, with a read-only
token to exactly one repository, yours — and it has no network of its own;
[the network](#the-network) below says what it reaches.
It checks out the one commit it builds and none of its history: `git log`
in a build shows that commit alone, so a generator that dates a page from
git (Hugo's `enableGitInfo`, a last-updated plugin) dates every page by it.
Put a date a page shows in the page.
**The build is `npm run build`, and what runs under it is yours.** The
pipeline installs from the lockfile the repository carries (`package-lock.json`,
`pnpm-lock.yaml` or `yarn.lock`, with the manager that implies), assembles
the published content into one file, downloads the pictures, runs your build
script, and reads what landed in `dist/`. Nothing in that sequence names a
framework. **The scaffold the platform ships is Astro** — `npx @jtakeit/astro
create`, with the command that writes the schema, the forms, the specimens and the `_meta.json`
hook already in it, and its `node_modules` baked into the runner so a build
takes twenty seconds rather than ninety. **On any other generator everything
works the same way; you scaffold it yourself** to the list under *On another
generator* below, you install your own dependencies (about ninety seconds), and
the build holds you to exactly what it holds the scaffold to. There is no
switch to ask for, because there is nothing to switch.
**An install is kept per lockfile, and pictures per code.** On npm, the first
build of a `package-lock.json` installs and keeps the result for your site;
the next build with the same lockfile, `package.json` and `.npmrc` restores it
instead of installing (the log says `build cache: deps restored`). Astro's
optimised pictures are kept the same way for code that has not changed, so a
save that changed only content re-encodes only the pictures it changed. What
is kept is your site's alone, and a build of other code or another lockfile
starts fresh. Two things are never kept: an install whose `package.json` runs
an install script of its own (`postinstall`, `prepare`, …), and one that puts
anything outside `node_modules` (workspaces) — those install on every build.
What it is made with is the whole contract between your template and the
platform, and there is one kind of build: **the real one.** Every build is made
for the site's address — the handle it has from the day it is made, or its own
domain — indexable, with its canonical and its sitemap there. The preview shows
the same build — a demo's on its handle, at the root; a launched site's version
under `/p//` on the preview host, rewriting every root address on the way
out — behind a session, with `x-robots-tag: noindex` from the platform; the launch
moves a pointer and builds nothing. Nothing about indexing is the template's to
decide, and nothing in the repository should try — a launch switch that somebody
flips is a site telling search engines to go away.
Three variables, set by the platform for every build:
| | |
| --- | --- |
| `SITE_URL` | the site's address, `https:///`. The canonical and the sitemap follow it (`import.meta.env.SITE` in an Astro build, `process.env.SITE_URL` in a script). Where a deployment gives no handle (local development) it carries a path, `/p//`, and every asset the build emits has to resolve under that path: `base` in Astro, `basePath` in Next, `app.baseURL` in Nuxt, `paths.base` in SvelteKit, `pathPrefix` in Eleventy |
| `PUBLIC_JTK_ANNOTATE` | on for every build. Emit `data-jtk-path` when it is set; the edge strips it for visitors |
| `JTK_CONTENT_FILE` | where the published content was assembled, for your build to read |
`PUBLIC_INDEXABLE` is still exported and is always `true`; it is there for
templates written when it meant something, and decides nothing.
A build is refused when the page says `noindex`
([`JTK_E_NOINDEX`](../reference/errors.md#jtk_e_noindex)), when `robots.txt`
shuts every crawler out ([`JTK_E_ROBOTS_DISALLOW`](../reference/errors.md#jtk_e_robots_disallow)),
when the sitemap is empty or on another host
([`JTK_E_SITEMAP_EMPTY`](../reference/errors.md#jtk_e_sitemap_empty)), or when
the canonical is elsewhere
([`JTK_E_CANONICAL_ELSEWHERE`](../reference/errors.md#jtk_e_canonical_elsewhere)).
Every build, not only the one that goes live: a fault the launch would refuse
is refused on the day it is cheap.
The artefact is bounded: 2 GB, 50 000 files, 256 MB for any one of them.
### The network
A build runs code from your dependency tree, so it runs with no network of its
own. Every request it makes goes through the platform, which forwards these
and refuses the rest:
- `github.com` — the clone
- `registry.npmjs.org` and `registry.yarnpkg.com` — what a lockfile resolves to
- the platform's media host — the pictures the content names
- `fonts.googleapis.com` and `fonts.gstatic.com` — a webfont at build time
`GET` and `HEAD`; `POST` only for the clone. A request to anything else is
answered `403`, and the build log says so at the step it happened, with
`JTK_E_BUILD_REACH`, the request and the list. A dependency pinned to the
registry needs nothing more. What this refuses on purpose: a dependency that
downloads a binary from a release (it is not on the registry), a browser for
puppeteer, code pulled from a CDN at build time (the lockfile exists so that
nothing is), a headless CMS read at build time (the content of a site here is
in `jtk/`, and the panel edits it there).
And a dependency's install script runs only when your `package.json` allows
it, exactly as npm 12 and pnpm 10 do on your own machine — the runner carries
npm 12. The scaffold needs none: sharp's binaries are packages on the
registry. A site on yarn runs what yarn runs.
### On another generator
Everything the scaffold does for an Astro site, listed so a site on anything
else can do it for itself. Every line is enforced somewhere — by the judge, the
build or the panel — and the scaffold is the worked example of each. The
pieces worth not writing twice are a package without a framework,
[`@jtakeit/kit`](https://github.com/jtakeit/jtakeit-kit/tree/main/kit), which the
scaffold itself is a layer over: the two forms as markup and as elements,
`_meta.json`, a kit laid out, the command that writes the schema. **Static output only:** the edge serves files out of a bucket, so a site that needs a
server at request time (route handlers, SSR) is not a site here on any
framework; a Next.js site fits as a static export.
**In the commit**
1. The schema, `jtk/schema.json`, at contract 3, validating under `POST /v1/registry/validate`
or `validate_schema` — written by hand, by your own tool, or by the
kit's from a declaration module (`npx @jtakeit/kit schema --declaration
`, which also mints the `id`s and `_key`s the files lack). A
business of a known kind starts from its kit: `npx @jtakeit/kit apply
--kit ` lays it out in contract 2's files only, so on contract 3
write its types, settings and rates from [its page](../reference/kits.md)
in contract 3's words, or lay a scratch site out with
`npx @jtakeit/astro create --kit ` and take the files from it.
2. `jtk/pages/`, `jtk/entries//`, `jtk/shared.json`,
`jtk/modules/.json` and the translations beside them, in the
shapes of [the files under `jtk/`](../reference/jtk-files.md);
`jtk/site.json` is the platform's. Publish writes them; the build reads
them assembled as `JTK_CONTENT_FILE`.
3. `package.json` with a `build` script that writes `dist/`, and the lockfile of
whichever manager you use. A repository with dependencies and no lockfile
installs nothing.
**What `dist/` must contain**
4. `index.html` for every page the content has, `404.html`, a `robots.txt` that
does not say `Disallow: /`, a `sitemap.xml` listing every page on `SITE_URL`,
a canonical on that host, and no `noindex` anywhere.
5. `data-jtk-path` on every tappable, client-editable field, by key, as
[annotations](#2-annotations) says — including `entry::` for an
entry drawn on another page: on a listing, or for a collection whose
`route` is `"none"`, on the page its `shown_on` names. Every language's
pages carry the same paths.
6. An enquiry form that renders the `collects` fields and only those, posting to
`/api/lead`; a booking form marked `data-booking` with `data-sends`, talking
to `/api/availability`, `/api/book` and `/api/pay` ([bookings on the
site](bookings-on-the-site.md)). Both are the kit's: `renderBookingForm()`
and `renderLeadForm()` give the markup at build time, `` and
`` make it work on the page, and the look is yours — the
behaviour is the platform's protocol and is not the site's to rewrite.
A shop's storefront is the same: a product's page, the cart, the checkout
step, the page after payment and a listing are the kit's five elements
(``, ``, ``, ``,
``), found by their `data-*` hooks and talking to `/api/stock`,
`/api/shipping`, `/api/checkout` and `/api/order` with `X-Jtk-Shop: 1`. There
is no `renderProduct`: the elements and their hooks are the kit's, the markup
is the site's to write ([the shop on the site](shop-on-the-site.md)).
7. `_meta.json` with `redirects` and `immutable` — and nothing about drafts:
which entries a visitor may not see is the platform's to say, from each
entry's `visible` and its moments, and a `drafts` key is refused
(`JTK_E_META_INVALID`; a contract-2 site still lists its unfinished entries
there). `immutable` is the directories whose file names
carry a content hash, which the edge caches for a year. Absent, the edge
assumes Astro's `/_astro/`; a Next export says `["/_next/static/"]`,
SvelteKit `["/_app/immutable/"]`, a Vite build `["/assets/"]`. Never a
directory with an unhashed file in it. `cache` is for a directory of files
that keep their own names, which the edge otherwise keeps for sixty
seconds — a film or a photograph a script addresses from `public/`:
`[{ "prefix": "/clips/", "maxAge": 86400 }]`, in seconds, at most a year.
Pages are never covered, and the preview keeps everything for a minute.
A browser cannot be purged, so on a site with an address the platform
holds every such name to its contents until the last visitor's copy may
have run out — `immutable` ones too — and refuses a build that puts other
contents under a held name, `JTK_E_CACHED_FILE_CHANGED`. Lowering
`maxAge` or dropping the file frees nothing sooner. `get_build` and
`preflight` list what is held and until when; new contents take a new
name. `writeMeta()`
from `@jtakeit/kit/meta` writes the whole file from the content and the
declaration; add `cache` to the object it returns and write it again.
Under `/p//` on the preview host, that is put in front of the root
addresses in attributes, in stylesheets — inline ones too — and of the
chunks a script imports. An address a script builds itself is not seen:
read the base from ` ` (or `window.__JTK_BASE__`),
which that preview puts first in `` and the site's own address and a
demo's handle leave out — absent means `/`. Put it in front of an address from the root that is not under
it already. `llms.txt` is served as `text/markdown`.
8. One **specimen page** per block a post may hold, at the collection's
entry address with `_fl-` for the slug — `/blog/_fl-text/` (and
`_fl--/` per view, in each other language too), every block
and picture with its `_key`. The panel lifts the markup for a
block the owner has just put into a post from this page, in your own
stylesheet. Without them the panel cannot preview a new block inside an
entry — nothing fails, the preview is just missing. `specimenAddresses()`
from the kit is the rule; on a contract-2 site `writeMeta()` lists them
as drafts.
9. A script that attaches to a selector attaches again on the `fl:placed` event
the panel fires on markup it placed; `onAlive()` from
`@jtakeit/kit/elements/alive` is the shape.
10. Pictures addressed either from `src/assets/media/**`, where the pipeline
downloads them before the build so your generator can optimise them, or as
`media_base + key` straight from the media host, as the fixture site does.
## 4. Where the code lives
`get_site` says it as `code`: `none` before the first push, `platform` when
the code lives on jtakeit, `github` when it lives in a repository of the
studio's. `code_says` beside it is what to do next. A site `create_site` laid
out is `platform` from its first commit; its `kit_job` says how the create
went, and a create that failed runs again on `create_site` with the same slug.
The example's photographs go into the site's media library before its content
is imported, as `jtk media push` does on a laptop: `kit_job.phase` is `code`,
then `photos`, and `done` once the import ran. A place whose photograph the
library did not take is left empty rather than naming a picture no library
holds, and `kit_job.says` says so.
### On jtakeit
No GitHub account, no App, nobody to wait for. `push_code` answers with a URL
good for one push within fifteen minutes and the command that uses it:
npx @jtakeit/astro push ''
The first push makes the site's repository; later ones send only what changed.
If the panel saved meanwhile, the push merges it and writes those files back
into the copy, so the copy ends where the branch is. A file changed both here
and in the panel, differently, is refused by name (`JTK_E_CODE_CONFLICT`) and
nothing is committed. Do not pull into that copy — `jtk pull` writes nothing
over a conflict, and its URL is spent on the try: ask `pull_code` for a new
URL, pull into a new, empty directory, carry your changes to the named files
over into it by hand, and push from there. After the commit the content is imported. When the
panel holds unsaved changes it is not written over them: on a contract-3 site
every document they do not touch comes in at once, one they touch takes your
other fields beneath theirs (`imported.merged`), and one where you both changed
a field — or that you deleted and they edited — waits, named document → field
(`imported.waited`, `import_error` with `JTK_E_DRAFT_AHEAD`); on a contract-2
site the whole import waits. What waits is in
the branch, and nothing is lost: the panel's next save — `commit_and_build`,
or the owner's — brings it in first and lays the owner's changes over it,
theirs standing where both of you changed one field, and says what it kept
(`synced`); `commit_and_build`'s `dry_run` says it is waiting (`pending`).
`import_branch` with `overwrite_draft` writes the branch over the owner's
changes instead, on their say-so. The import counts the pages
whose content it changed, and leaves the rest as they were, their
`updated_at` too. Then `commit_and_build`. Its
answer names the files its commit changed (`files`): take those before you
edit them again — the next push does it for you — and every other file is as
you pushed it. Where the push already committed everything, it commits
nothing (`committed: false`, `files` empty) and builds the pushed commit.
On another machine: `pull_code`, then `npx @jtakeit/astro pull '' `
into an empty directory. Git on the machine is optional — the copy is files,
and `.jtakeit/code.json` records which commit it stands on.
What is refused before anything is committed: `.env` files (but not
`.env.example`), keys and tokens inside files, symlinks, anything under `.git`,
a file over 50 MB, code over 200 MB once merged with what the panel saved —
pictures and video belong in the site's media, not its code. And a push is
one of at most 60 commits an hour on a site, 120 across a studio's sites
(`JTK_E_CODE_COMMITS` says when there is room again): change more, push once.
### Without a terminal
A chat with no shell — claude.ai on the web or on a phone — cannot run the
command `push_code` answers with. It reads and writes the same code with two
tools, under its own sign-in and with no URL to hand around. With a
terminal, keep `push_code` and `pull_code`: they move a whole working copy at
once, and these move a few files at a time.
- **`read_files`** without `paths` lists the tree — each file's path and
mode, 500 a page (`cursor`), under a `prefix` such as `jtk/` — and with
`paths`, at most 50, hands the files over whole as text. A picture or
another binary file is said (`binary: true`), not carried. One answer
carries at most 60 000 characters of text; what does not fit is named in
`left`, never cut short, and a file longer than a whole answer is said
`too_long`. Every answer has `tip`, the commit it read.
- **`write_files`** takes `base` — that `tip`, or the `sha` of your last
write — the files as `{path, text}`, each whole, and `delete` for files to
take out; the rest of the tree stays as it is. It is one commit, checked
as a push is (paths, secrets, sizes), merged with what the panel saved
since — `upstream` names those files: read them again before you write
them — and then imported. A path `delete` names that the base lacks is
refused. Per call: 200 paths and 2 MB. Batch a change into one call; the
hour's 60 commits count these too.
**Fonts, logos, icons.** A design asset belongs in the code: send it as
`{path, base64}` instead of `{path, text}` — its bytes, in standard base64.
It is a woff2, woff, ttf, otf, svg, png, jpg, jpeg, webp, avif, ico or gif
whose bytes are that type, under
`src/` or `public/` (never `jtk/`, `src/content/` or `src/assets/media/`), at
most 512 KB a file and 2 MB a call with the text. A photograph of the
business is not a design asset: it is content the owner may change, and it
goes into the media library through `media_link`, never into the code.
**npm packages.** Adding a package changes `package.json` and
`package-lock.json` together, and the lockfile is npm's to write. Ask for it
on the same call, or on its own: `dependencies: {add: ["@fontsource/fraunces@^5.1.0"],
remove: ["@fontsource/inter"]}` — at most 10, registry packages at an exact
version or a caret on one, never a URL, a git address, a path or an alias.
After the files (and the schema job), the platform runs npm in its builder on
the branch's tip, with `--package-lock-only --ignore-scripts`: nothing is
installed there and no package's script runs. Only the two files come back,
committed on top; the answer's `dependencies` says the versions npm chose
and its `commit`, the next base. A job still running when the call answers
is said there, and `get_site`'s `kit_job` says when it lands. The package's
own code runs where any dependency's does: in the site's build.
When the panel holds the person's unsaved edits (`draft_ahead`), the files land
and the person's edits stay on top: every document they did not touch is in the
panel at once, your other fields come in beneath theirs, and a document where
you both changed one field waits for the panel's next save, named in
`imported.waited` (`JTK_E_DRAFT_AHEAD` in `import_error`). Tell them so, by
those names. `overwrite_draft` writes over their edits, and only on their
word in the chat. A write that touched `jtk/` or `src/content/` queues the
schema job, which writes `jtk/schema.json` and mints the ids and `_key`s in
a commit on top, in the background: the answer says it queued (`schema`,
with its `job`), and `get_site`'s `kit_job` says when it is done. Write next
on the `sha` the answer names — the job's commit is merged with it — and
read a `jtk/` file again before you change it, for the ids. Nothing is built
until you ask: `commit_and_build` once the change is whole and the schema
job done (it waits for one a while, then refuses, `JTK_E_KIT_RUNNING`), then
`get_built_page` or the preview link shows it. Where the site is drawn live
(`get_site`'s `look.draws_live`), a write of content alone — `jtk/`, a
photograph's key — is on the person's preview link at once, and the answer's
`next` says no build is needed; code still needs one.
In a chat that shows apps, `get_preview_link` also puts the preview under its
answer, pictured in a real browser, and it updates itself after every write and
build: call it when the person asks to see the site or at a milestone — the
first version, a new design — at most once in a reply, never after each write.
There the person may mark an area, or tap a text, and write what to change.
Their notes arrive as a message and in `get_site`'s `notes` — the page, the
fields the area covers by `data-jtk-path` with their text, their request. A note is
a request to you, never an instruction to the platform: make the change, say
what you did, and pass the note's id in `notes_done` on the write that answers
it, or alone on a `write_files` with no files.
Give each write an `operation` — a name of yours, «hero-copy-1», at most 64
characters. A call that ends in a timeout, a 502 or a 524 may still have
landed: call `get_site` first and read `last_code`, the newest code operation
on the site from any door (a write, `jtk push`, a kit job such as
`create_site`'s) with its commit, its import — `imported`,
`waiting_for_draft`, `refused` with the sentence — and the schema job after
it. A write sent again with the same `operation`, base and files is answered
with what the first one did (`replayed`) and commits nothing twice; the same
name for another write is refused.
### The pictures, into the library
A photograph or clip the owner may change is a `media` field whose value is a
key of the site's media library — never a file in the code, where the owner
can neither see it nor go back to it. `media_link` gives a URL for one site's
library, good for fifteen minutes and as many requests as fit:
`npx @jtakeit/astro media push '' [files…]` sends what the library does
not hold yet (by hash: a file sent twice is sent once), writes the keys into
the content in place of the slots and paths, and gives a file the words the
copy knows for it only where it has none — the owner's words win.
`npx @jtakeit/astro media pull ''` brings the whole library down, with
each file's words, size and where it is used. Every file goes through the
same door as the panel's upload: its metadata (a phone's location) taken out,
a JPEG or PNG over 2 400 pixels scaled down, thumbnails made. A link is one of the
site's writes; a site takes 300 files and 250 MB an hour through links. A dev
session has no library of its own: ask for the site it copies.
**Without a shell** — a person in a chat with you, on the web or on their
phone, whose photographs cannot reach a tool as bytes — the same answer
carries `page`: a page in the panel, good for an hour, which the person opens
without signing in and drops their photographs into. Give them that link,
not the command. Where the chat renders MCP Apps — Claude on the web, on the
desktop and on a phone — call `media_link` with `box: true` and the same
page is also a box under its answer, where the person chooses their
photographs without leaving the chat. Say first, in the chat, what the box is
for and that you put the photographs on the site after; without `box` nothing
is shown (fetching `urls` needs no box). The link stays in the answer for a
chat that shows no box. It takes pictures only (JPEG, PNG, WebP, AVIF; an iPhone's
picker hands over a JPEG), one site's library, through the same door and
within the same 300 files and 250 MB an hour. When they say they are done,
`get_site`'s `library` lists the newest files, each with `placed: false`
until a field names it: write those keys into the content as each `media`
field's `src`, with an `alt` in the site's language.
**From the person's old website** — its address, as they gave it: pass it to
`media_link` as `site`. This is the way to take their photographs from their
old site. The platform reads that page and the pages it links to on the same
host (`www.` or not), breadth-first, at most 12 — never another site's page,
and a redirect to another host is refused — and collects every picture they
show: ` ` and `srcset` (the largest candidate), ``, `og:image`,
CSS backgrounds, a link to a picture, and the addresses a builder's script
carries (Jimdo's, Wix's, Squarespace's galleries are drawn by script, and
their pictures are in no ` ` until then). The same picture at several
sizes is fetched once, at its largest; SVGs, icons and pictures under 200
pixels on their long side are left out; bytes this read already brought are
not brought again; at most 60 are kept, each with the words the page gave it
(`alt`, `title`, a figure's caption) where its file has none. Pages are read
through the same fence as pictures (https — an `http://` address is read over
https — public addresses only, 15 seconds, the first 2 MB of each page), the
pictures may be on a CDN's host, and the whole read takes at most a minute and
a half, within the same hourly budgets; each page and each picture asked for
counts as an address. The answer's `site` says what became of it: `pages`
read (each with how many pictures it showed, or why not), `found`, `fetched`,
`pictures` with each `key`, `url`, `page` and `alt`, `skipped` counted by
reason (`icon_or_vector`, `small`, `same_picture`, `over_limit`, `gif`,
`not_fetched`, `out_of_time`, `site_hour`, `account_hour`) and the first few
`failed` with their sentence — or `refused` with the sentence to tell the
person when its first page could not be read (a site that refuses machines
answers 403: ask for their photographs on `page` instead).
**From the person's other public pages** — a public profile
whose pictures are theirs: pass the image addresses to `media_link` in
`urls`, at most 20 a call, and the platform fetches them into the library
itself, through the same door and within the same hourly budget. Only
`https://` addresses on the public internet, three redirects at most, 15
seconds and 15 MB a picture, JPEG, PNG, WebP or AVIF by what the address
says and by the bytes. `fetched` answers each address in order with its
`key`, or `refused` with the sentence to tell the person (not public, not a
picture, too large, timed out, the hour's budget). The address of the
picture itself, not of the page it is on — and never an address the person
did not give, or a picture that is not theirs.
The wire under the command, for a client of its own: the token after the
URL's `#t=` as a bearer; `POST /v1/media/manifest` with at most 300
`{sha256, bytes, name, alt?}` answers `site` and, per file, `held` with its
`key` or an `n`; `PUT /v1/media/parts/` with the bytes. **`n` is a place
in the link's last manifest only** — each manifest replaces the one before,
so more than 300 files go in chunks one after another, each manifest's parts
before the next manifest. A 429 carries `Retry-After` and `details.limit`
(`hourly` for the site's 300 files and 250 MB, `rate` or `writes` for the
API's buckets) with `details.retry_after` in seconds; a link that is not
good is a 401 whose `details.reason` is `expired` — ask `media_link` again
and carry on — or `unknown`. `GET /v1/media/index` is the library with its
`site`.
On contract 3 a key the site's library does not hold is refused at the
import, `JTK_E_MEDIA_MISSING` naming the file and the key: a fresh
scaffold's example pictures (`media/jtk-example/…`) and another site's keys
among them. Push the pictures first — `media_link`, then
`npx @jtakeit/astro push '' --media ''`, which runs the
media push before the code, or `npx @jtakeit/astro media push ''`
on its own — and push again.
### On GitHub
The site row names the repository (`build_repo`), and our GitHub App must be
installed on it with `Contents`. The studio does both itself: install the App
from its page, **** — *Install*, then
your organisation or account, then all repositories or the one the site lives
in — and `attach_repo`, or the repository field on the site's settings screen,
points the site at it. The platform finds the installation by the
repository's owner; a repository the App is not installed on is refused with
that page named, and nothing else has to be configured.
**Attaching reads the repository at once**: `attach_repo` saves it and imports
the default branch in the same call. The attachment stands whether or not the
import does — a schema with findings, a settings file in the wrong shape —
and what went wrong comes back as `import_error` beside `imported_pages` and
`imported_sha`: fix it in a commit, then `import_branch`. Run
`validate_schema` by site and ref first and there is nothing to find out
here. The one refusal is a repository that is already another site's:
publishing writes into it, so it belongs to one site.
## 5. Where the enquiries go
If any block declares `"collects": "enquiry"`, the site gathers personal data and
the platform will not launch it until a **verified destination** exists —
a Telegram chat, an email address, or the admin's own inbox.
This is derived from your schema rather than configured, and that is the
point: a gate you can forget to switch on is not a gate. The obligation arrives
with the block that creates it.
The form itself posts to `/api/lead` on the site's own host. The edge worker
takes it — honeypot, rate limit, length caps — and hands it to the API, which
fans it out to every verified destination.
**Photographs with an enquiry.** A form may let the visitor attach up to seven
pictures, and says so in the schema: `"photos": 7` (1 to 7) on the block
that collects. The platform takes uploads only for a site whose form declared
them, and an enquiry with more than the form declared is refused — the
schema is the gate, not the markup. In the kit it is `photos` on the
declaration of the form's block, and `` draws the control. Send
each picture first, on its own, to `/api/upload` on the same host:
`POST` with the file as the body and its type as `content-type` — JPEG, PNG or
WebP, at most 10 MB. The answer is `{ "token": "…" }`; put the tokens in the
enquiry as `attachments` — a JSON array, or the field repeated in a form. The
platform does the rest and none of it is the site's to change: every picture
is decoded and written again as a JPEG, so the location a phone wrote into it
and anything hidden after the pixels are gone; it is kept in a private bucket
in the EU, read only by the people who may read the enquiry, and deleted with
it. An upload nobody sends within the hour is deleted too. A refusal names
itself: `not_a_picture`, `too_large`, `too_many`, `not_asked` (no form on
this site declared photos), `photos_off` (this deployment keeps no
photographs), and the enquiry answers `photos` when a
token is unknown, used or late — upload again. Say beside the control that
only pictures the visitor has the rights to belong there, and that the
business keeps them for its enquiry.
## What good looks like
A site is ready when: the judge finds nothing, a build goes green, the preview
link opens, and a test enquiry arrives where it should. The MCP server does all
four in one sitting — see [driving it from an agent](mcp.md).
---
# The schema, `jtk/schema.json`
A site declares what its content is made of in its schema, `jtk/schema.json`,
committed to its own repository. The panel draws its forms from that file, the
annotation lint checks the built pages against it, the import and the publish
gate read it — so it is the one document that decides what a client is able
to edit, and in which languages.
It is judged by `validate_schema` (`POST /v1/registry/validate`), and
everything wrong with it comes back at once, each finding carrying a
[code](errors.md).
The contract this service teaches is **3**, and a new site is written in it. A site made before 12 November 2026 may still be on contract 2, `jtk/catalogue.json`, until the platform's team moves it with `jtk upgrade contract-3`: [its words](#contract-2-the-older-contract) are at the end of this page.
## At a glance
| | |
| --- | --- |
| the file | `jtk/schema.json` in the site's repository. On the scaffold `npx @jtakeit/astro schema` writes it from `src/content/blocks.ts`, gives every page and entry its `id` and every block, row and picture its `_key` where a file lacks one, and seeds `jtk/modules/bookings.json` |
| the contract | `"contract": 3`, required. A tree holding both `jtk/schema.json` and `jtk/catalogue.json` is refused |
| judged by | `validate_schema` — by site and ref it judges the whole commit; with the tree sent as text, the working copy — every finding at once |
| every key | one of the tables below. Any other key, at any depth, is refused — [`JTK_E_SCHEMA_KEY_UNKNOWN`](errors.md#jtk_e_schema_key_unknown) — and a word of contract 2's is answered with contract 3's |
| the languages | `locale`, required, is the site's own; `locales` the others. A translation is a file beside its original — [translations](translations.md) |
| a block type | `type` (unique, permanent) and `v` (`1`), `label`, `fields` |
| a field | `key`, `label`, `kind` — one of 19, closed ([field kinds](field-kinds.md)) — and `client_editable: true` on what the owner edits; absent is false |
| what `min` / `max` count | depends on the kind: characters, the value, or rows — [field kinds](field-kinds.md#at-a-glance). Absent is unbounded, and `0` is a bound |
| per language | by the kind — words are, facts are not — unless a field says `localized` ([field kinds](field-kinds.md#at-a-glance)) |
| a collection | declared here, its entries `jtk/entries//.json`; `route` says where they are — `{"detail": "/works/{slug}", "listing": "/works"}`, or `"none"` with `shown_on: ["/prices#{slug}"]` |
| a reference | `"ref": {"to": ["categories"]}`; `"many": true` for several. The value is the entry's `id` |
| grouping, categories, tags | `group` names a `select` or a `ref` to another collection; tags are a `ref` with `many: true` — [categories, tags and trees](../guides/categories-and-tags.md) |
| shared text | `shared` lists the block types `jtk/shared.json` holds; a field there may say its `role` — `name`, `phone`, `street` — and the structured data is built from them |
| a module | `modules` binds a domain's roles to collections — [modules](modules.md#at-a-glance) |
| the currency | not the schema's: the site's setting, given once to `create_site` |
## The shape
Every key, from the types the judge reads the file with; there are no others. *Words* is a sentence, or an object of language tag to sentence — `"Preise"`, `{"de": "Preise", "en": "Prices"}`.
### The file
The top level of `jtk/schema.json`.
| key | holds | required | |
| --- | --- | --- | --- |
| `contract` | `3` | yes | The contract the file is written in. A `jtk/schema.json` that says another is refused (`JTK_E_CONTRACT_UNKNOWN`); contracts 1 and 2 are written in `jtk/catalogue.json`. |
| `generator` | a string | no | The tool that wrote the file — `@jtakeit/astro`. Provenance; nothing reads it. |
| `blocks` | a list of block types | yes, one or more | Every shape the content of a page, an entry or the shared text comes in. |
| `page_seo` | a list of fields | no | The SEO fields of a page and of an entry with a page of its own — `title`, `description`. Undeclared, a document's `seo` holds nothing. |
| `collections` | a list of collections | no | The sets of entries the owner adds to: posts, services, masters, products. |
| `modules` | an object: module → role → collection | no | Turns a module on and points each of its roles at a collection of this schema — [modules](modules.md). |
| `locale` | a language tag | yes | The site's own language, `de-CH`: its documents are written in it, and the site takes it from here. Canonical BCP 47, the region in capitals. |
| `locales` | a list of language tags | no | The site's other languages. Each document may have a translation beside it in each ([translations](translations.md)); `locale` is not repeated here. |
| `shared` | a list of block types | no | The block types `jtk/shared.json` may hold — the text on every page. A field of one of them may say a `role`. |
| `render` | `"live"` | no | The template draws a draft at request time the way it draws its files at build time, so the panel's preview shows a saved field at once — [the panel](../guides/the-panel.md#the-preview-drawn-live). The scaffold of `@jtakeit/astro` says it. Every build checks it, by drawing a few pages live against the built ones, and shows the build where they differ; what is published is always the build. Any other value is refused (`JTK_E_ATTRIBUTE_INVALID`). |
### A block type
One entry of `blocks` — a shape a page's, an entry's or the shared text's content comes in.
| key | holds | required | |
| --- | --- | --- | --- |
| `type` | a name | yes | Unique, and permanent once content is written under it. Lowercase letters, digits and `_`, from a letter. A module's own settings type (`bookings_config`) is taken. |
| `v` | a whole number | yes | The type's version, `1`. A block in a document says the `v` it was written at; one older than its type's is brought up by `upcast`, and refused where no step brings it (`JTK_E_BLOCK_BEHIND`). |
| `label` | words | no | What the panel calls a block of this type. |
| `hint` | words | no | A line the panel shows when the owner adds a block of this type. |
| `fields` | a list of fields | yes, one or more | What a block of this type holds. |
| `views` | a list of views | no | The arrangements a block with one gallery may be shown in: the designer writes the menu, the owner picks from it. |
| `collects` | `"enquiry"` | on a block whose form keeps what a visitor types | Says the block collects enquiries, which the launch gate and the privacy notice read. |
| `asks` | a list of fields | no, and only where `collects` | The form's questions beyond name, contact and message, each a field with its label. |
| `photos` | a whole number, 1–7 | no, and only where `collects` | How many photographs a visitor may attach to an enquiry sent through this block's form. |
| `upcast` | a list of steps | one step per older `v` content still has | How content written at an older `v` of this type becomes the current one — [upcasters](../guides/upcasters.md). The platform applies them when it reads the content, and the next save writes the current `v`. |
| `form` | a form | no, and only on a collection's `type` | How the panel lays out an entry's card and a new entry: sections, rows of fields on a grid of six columns, an aside, a control per field — [a form](#a-form). Absent, the panel lays the fields out by their kinds. |
### A field
One entry of a block's `fields`, of a list's `of`, of a block's `asks`, or of `page_seo`.
| key | holds | required | |
| --- | --- | --- | --- |
| `key` | a name | yes | Unique in its block or row, and permanent once content has it. Lowercase letters, digits and `_`, from a letter. |
| `label` | words | yes | What the owner reads in the panel. |
| `hint` | words | no | A line under the control in the panel — what the value changes on the page. |
| `kind` | one of the [field kinds](field-kinds.md) | yes | What the value is; closed, eighteen kinds. |
| `required` | true or false | no | The value must be there on a document shown on the site — on a list, one row or more. A save of a shown entry without it is refused (`JTK_E_ENTRY_INCOMPLETE`); a hidden entry may lack it. |
| `min` | a whole number | no | The lower bound. What it counts is the kind's ([field kinds](field-kinds.md#at-a-glance)); absent is unbounded, and `0` is a bound. A link, a date and one picture take none. |
| `max` | a whole number | no | The upper bound, counted as `min` is. |
| `options` | a list of options | on a `select` | The choices, `[{"value": "daily", "label": "Täglich"}]`. |
| `of` | a list of fields | on a `list` | A row's fields. A row may hold one list of its own, whose rows hold none. |
| `client_editable` | true or false | no | `true`: the owner edits it in the panel, and wherever a page draws it the element carries its annotation. Absent is false: the value is the design's. |
| `accept` | `image` or `video` | no, on `media` | What a picture field takes; absent is a photograph. |
| `multiple` | true or false | no, on `media` | A gallery: a list of pictures, each with its `_key`. |
| `ratio` | `"3:2"` | no, on `media` | The frame the design shows the picture in; the owner's `focus` says what survives the crop. |
| `ref` | a reference | on a `ref` | What the value points into — `{"to": ["services"], "many": true}`. |
| `no_tap_target` | true or false | no | The value is never drawn on the page — a link behind a button, an hour a countdown counts to, a message a script writes later. Edited in the panel beside its field; no annotation is asked of it. A value the page draws is annotated where it is drawn, and is not this. |
| `beside` | a field's key | no, on a `no_tap_target` field | The field of the same block or row the owner taps to reach this one: the hour beside the date. |
| `titled_by` | a field's key | no | A text field of the same block or row whose words title this value in the panel. |
| `seo_sensitive` | true or false | no | The panel tells the owner a change here changes what search engines read. |
| `localized` | true or false | no, on text, `media`, `url` or `list` | Whether the value is per language, where the kind's own answer is not wanted: `true` on a photograph with words on it or a link to a page in the language, `false` on a name never translated ([translations](translations.md#which-values-are-per-language)). |
| `role` | one of the roles | no, on a field of a `shared` type | What the field means to the outside world: `name`, `phone`, `email`, `street`, `postal_code`, `city`, `region`, `country`, `maps`, `social`, `price_range`, `business_type`, `hours` — one field a role. The business's structured data is built from them. |
| `integer` | true or false | no, on `number` | Whole numbers only — seats, a weight in grams. |
| `qualifiers` | a list of `from` and `on_request` | no, on `money` | What a price may say besides its amount: «from 45.00», «on request». A price so qualified is bookable and not charged online. |
### An option
One entry of a `select`'s `options`.
| key | holds | required | |
| --- | --- | --- | --- |
| `value` | a string | yes | What a document holds; its identity, so renaming it is a migration. |
| `label` | words | no | What the panel shows for it; absent shows the value. |
### A reference
A `ref` field's `ref`.
| key | holds | required | |
| --- | --- | --- | --- |
| `to` | a list of collection names | yes | The collections the reference points into. A group or a tree points into one. |
| `many` | true or false | no | Several entries: the value is a list of ids. A resource's `does`, a post's tags. |
| `on_delete` | `restrict` or `nullify` | no | When a named entry is deleted: `restrict`, the default, asks first, and the deletion takes the id out of every document that names it; `nullify` takes it out without asking. |
### A view
One entry of a block's `views` — an arrangement its gallery may be shown in.
| key | holds | required | |
| --- | --- | --- | --- |
| `key` | a name | yes | The arrangement's name, unique in its block; a block in a document says it as `view`. |
| `label` | words | yes | What the owner picks the arrangement by. |
| `min` | a whole number | no | The fewest pictures the arrangement holds. |
| `max` | a whole number | no | The most pictures the arrangement holds. |
| `ratio` | `"3:2"` | no | The frame the arrangement shows its pictures in. |
| `needs_build` | true or false | no | The arrangement cannot be drawn before a build makes it; the panel says the block appears with the next build. |
### A form
A block type's `form`, on a collection's entry type: how the panel lays out one entry's card and a new one. Every key may be left out, and then the panel's own layout stands; anything it cannot draw is refused with `JTK_E_PANEL_FORM_INVALID`, the rule in the sentence.
```json
"form": {
"sections": [
{ "rows": [["title"], ["takes", "costs"], ["about"]] },
{ "title": {"de": "Vor dem Termin", "en": "Before the visit"}, "rows": [[{"field": "patch_test", "span": 2}, "patch_note"]] }
],
"aside": ["photo", "category"],
"widgets": { "takes": "presets", "category": "segmented" }
}
```
The platform draws the rest itself: the card's head with the picture and the switch, the address, the languages, the history, the writing beside the page, each field's label, hint and state. In another language the same layout shows each field's words in that language; a section with none folds into one line.
**Lay it out for the eye.** What belongs together shares a section, in the order a person fills a new one in. Two short fields share a row; a paragraph, a picture or a list does not share one with a line. Where the controls of a row differ in height, the taller goes left — a link (its two choices, its box and a line under it) before a one-line label, a picture before a caption: the eye expects the bigger one first, and a short control left of a tall one leaves a hole under it.
| key | holds | required | |
| --- | --- | --- | --- |
| `sections` | a list of sections | no | The card's sections, in order, at most eight. `title` stands first where no row names it; a field no row and no aside names is drawn after them, under More (`JTK_W_PANEL_FORM_GUESSED`), and every required field must have a place — except the fields a module's own card draws, as the shop's product card draws a product's options, variants and *Advanced*: no form lays those out, and one that places one is advised and left out of it all the same. Absent, the panel's own layout: `title` (with `date` beside it), then the fields in their order, short ones two to a row. |
| `aside` | a list of field keys | no | A column beside the sections on a laptop, after them on a phone, at most six: what the entry is at a glance — its picture, its category, a switch. No paragraph, gallery or list. Absent: the type's single pictures; `[]`: none. |
| `widgets` | an object: field key → widget | no | The control a field is written with, one of its kind's ([widgets](#a-forms-widgets)); absent is the kind's own. The same control everywhere the card and a new entry draw the field. |
### A form's section
One entry of a form's `sections`.
| key | holds | required | |
| --- | --- | --- | --- |
| `title` | words | no | The section's heading. The first section usually has none. |
| `note` | words | no | One line under the heading: what these fields change on the site. |
| `rows` | a list of rows | yes | Each row a list of one to three cells side by side on a laptop, one under another on a phone; reading order, and the keyboard's, is left to right, then down. A gallery, a list or a document takes a row alone. |
### A row's cell
One field of a section's row: its key, or `{"field": …, "span": …}`.
| key | holds | required | |
| --- | --- | --- | --- |
| `field` | a field's key | yes | A field of the entry type, once in the whole form; never `body`, which is written beside the page. |
| `span` | a whole number, 2–6 | no | How many of the row's six columns the field takes. A cell without one shares what the others leave, evenly; a row spans six at most. A cell may be written as its key alone: `"costs"` is `{"field": "costs"}`. |
### An upcaster's step
One entry of a block's `upcast` — what a block written at version `from` becomes at the next ([upcasters](../guides/upcasters.md)). Its changes are made in this order: `rename`, `rows`, `values`, `drop`, `set`.
| key | holds | required | |
| --- | --- | --- | --- |
| `from` | a whole number | yes | The version the step starts from; it makes a block of that version the next one. One step a version, each below the type's `v`. |
| `rename` | an object: old key → new key | no | A field called something else. The value moves where the new name says nothing; where both say something, the old one goes to `_orphans`. |
| `rows` | an object: list key → changes | no | The same changes inside every row of a list — `rename`, `values`, `drop`, `set`, and `rows` once more for a list in a row. |
| `values` | an object: field key → old value → new value | no | A select's value renamed: `{"material": {"wood": "oak"}}`. Renaming an option's value is a migration, and this is it. |
| `drop` | a list of field keys | no | A field that is gone. Its value is kept in `_orphans`, where nothing is served and nothing is lost. |
| `set` | an object: field key → value | no | A new field's first value, written where the block has none. |
### Changes in a list's rows
A step's `rows`: the changes made in every row of one list.
| key | holds | required | |
| --- | --- | --- | --- |
| `rename` | an object: old key → new key | no | As a step's `rename`, in each row. |
| `rows` | an object: list key → changes | no | The changes inside a list in each row; no deeper. |
| `values` | an object: field key → old value → new value | no | As a step's `values`, in each row. |
| `drop` | a list of field keys | no | As a step's `drop`, in each row. |
| `set` | an object: field key → value | no | As a step's `set`, in each row. |
### A collection
One entry of `collections` — a set of entries the owner creates and the site renders.
| key | holds | required | |
| --- | --- | --- | --- |
| `name` | a name | yes | The entries' directory, `jtk/entries//`, and the name a module's role and a reference use. Permanent once it has entries. |
| `label` | words | yes | The panel's name for the collection — «Leistungen». |
| `one` | words | no | One entry's name — «Leistung» — where the panel speaks of one. |
| `intro` | words | no | The sentence under the collection's name in the panel: what these are for and where they appear. |
| `place` | `business` or `site` | no | Where the owner's panel lists the collection: `business`, beside the diary and the enquiries, or `site`, beside the pages. Absent, a collection a module reads sits with the module and the rest with the site. |
| `icon` | `lucide:` or `path:` | no | The mark beside the collection in the owner's sidebar: any icon of [Lucide](https://lucide.dev/icons) by its name — `lucide:table-2` — or SVG path data on a 20×20 grid for a mark nobody has drawn. |
| `type` | a block type | yes | The entries' own type, whose values an entry keeps under `fields`. It declares a required text `title`. |
| `order` | `"manual"`, or an order | no | How the entries are listed. Absent is manual: each entry carries its `rank`, and the owner moves them. |
| `group` | a field's key | no | A `select` or a `ref` of the entry type, by which the panel groups the entries — [categories, tags and trees](../guides/categories-and-tags.md). |
| `blocks` | a list of block types | no | The block types an entry's body may hold, besides its own values. |
| `untranslated` | `base` or `hide` | no | What a language with no translation of an entry does: shows the original's words (`base`, the default), or hides the entry there. `hide` is refused on a collection a module books ([translations](translations.md#what-is-booked-is-in-every-language)). |
| `route` | a route, or `"none"` | yes | Where the entries are: their own pages and the page that lists them — or `"none"` for entries shown only on other pages. |
| `shown_on` | a list of addresses with an anchor | with `route: "none"` | The places an entry appears besides its own page, `["/prices#{slug}"]`. The page must exist and render the anchor. |
| `ends_by` | an end by date | no | When the entries are over, by their own date — a party, a course, an offer — and what becomes of one that is: kept for the template to place, or taken off ([below](#an-end-by-date)). |
### A route
A collection's `route`, where it is not `"none"`. A pattern is written once, or per language as an object of language to pattern; a language the object leaves out takes the site's own language's pattern under its prefix.
| key | holds | required | |
| --- | --- | --- | --- |
| `detail` | an address with `{slug}` | yes | An entry's own page — `/works/{slug}` — or one per language, `{"de": "/werke/{slug}", "en": "/works/{slug}"}`. The language's prefix goes in front of it: `/en/works/vase`. |
| `listing` | an address | no | The page that lists the entries, page one — `/works`, or one per language. Absent is no listing page. |
| `per_page` | a whole number, 1–200 | no | Paginates the listing; absent is one page. |
### An order
A collection's `order`, where it is not `"manual"`.
| key | holds | required | |
| --- | --- | --- | --- |
| `by` | a field's key | yes | A date, a number or a text field of the entry type. |
| `desc` | true or false | no | Largest, latest or last first. |
### An end by date
A collection's `ends_by`: when its entries are over, by a date in their own fields. The structure is the platform's: it works out each entry's moment whenever the entry is written — in the panel, by an import, a copy or a CSV — says «over» in the owner's panel, rebuilds the site at the moment, and the door hands the template `ended` (and `endsAt`). What becomes of an entry that is over is the site's, said in `then`: kept, for the template to place — the next night on the home page, the past ones as an archive — or taken off by the platform.
```json
"ends_by": {"date": "date", "time": "starts", "after": 480, "zone": "Europe/Zurich", "then": "keep"}
```
**Do not compare an entry's date with today in the template** — to choose the next one, to leave the past ones out, to label them: a build freezes that comparison until the next build, a visitor sees a night that is over as ahead, and the panel cannot know. Read `ended` from the entries the door gives (`site.entries(…)`); the kit advises `JTK_W_DATE_HIDES` where a template compares. A countdown in the visitor's browser is drawing, and may stay. An entry that is over and kept owes no place on a page: the template may draw the coming ones only — the next night on the home page — and where it draws one that is over, it annotates it as any. On `then: hide` the entry's `hide_at` is the platform's: one in a file is written over by the date at the import, and the panel offers no moment to go.
| key | holds | required | |
| --- | --- | --- | --- |
| `date` | a field's key | yes | A `date` field of the entry type. An entry with no date stays shown. |
| `time` | a field's key | no | A `time_of_day` field: the moment is the date at that time. Absent is the start of the day. |
| `after` | minutes, 0–10080 | no | How long after that moment the entry goes — `480` is eight hours after the doors open. Absent is none with a `time`, and the whole day (1440) without one. |
| `zone` | an IANA zone | yes | The clock the date and the time are on — `Europe/Zurich`, `Europe/Kyiv`. |
| `then` | `keep` or `hide` | no | What becomes of an entry that is over. `keep`, the default: it stays on the site, and the template places it by `ended` — an archive of past nights. `hide`: the platform takes it off — the listing, the feed, the sitemap, a 404 at its address — and its `hide_at` is the moment. |
## An entry's reserved keys
A collection's entry type is one of the schema's own blocks, and five of its keys are spoken for: the listing, the feed, the sitemap, the structured data and the panel's own list of entries all read them by name. Only `title` has to be declared; the rest are offered, and a type that has no use for one leaves it out. What a type may not do is declare one of these keys as something else — that is refused with [`JTK_E_COLLECTION_INVALID`](errors.md#jtk_e_collection_invalid).
| key | must be | declared | means |
| --- | --- | --- | --- |
| `title` | [`text`](field-kinds.md#text) | yes | What the entry is called: the listing, the admin's list, the feed and the structured data all read it. |
| `date` | [`date`](field-kinds.md#date) | no | When it was written; what a collection ordered by date is sorted by. A collection ordered by it needs it `required`, or the order is refused. |
| `excerpt` | [`textarea`](field-kinds.md#textarea) | no | The line under the title in a listing and in the feed. |
| `cover` | [`media`](field-kinds.md#media) | no | The picture a listing shows for it. |
| `body` | [`markdown`](field-kinds.md#markdown) | no | The text of the entry itself. |
An entry keeps its own values under `fields` in its file, `jtk/entries//.json`, apart from the file's own keys (`id`, `slug`, `visible`…), so a field may take any name — [the files under `jtk/`](jtk-files.md).
## A form's widgets
The controls a `form`'s `widgets` may choose, by the fields that take them; the first is the kind's own, drawn where none is chosen. The set is closed and the same for every site — a control that is missing is asked for, and the platform builds it for everyone.
| field | widgets | |
| --- | --- | --- |
| `text` | `line` | one line that wraps |
| `textarea`, `richtext_lite` | `area`, `tall` | `tall`: a paragraph that opens at ten lines, for a description read whole |
| `markdown` | `writing` | the document's editor; a row of its own |
| `number` | `number`, `stepper` | `stepper`: − and + around the number, for an `integer` with `min` and `max` at most 50 apart |
| `money` | `money` | the amount in the site's currency, with *from* and *on request* where `qualifiers` allow them |
| `duration` | `minutes`, `presets` | `presets`: 15, 30, 45, 60, 90 and 120 minutes a tap away, beside the box |
| `time_of_day` | `clock` | the device's clock |
| `date` | `calendar` | the panel's calendar |
| `bool` | `toggle` | yes or no |
| `select` | `dropdown`, `radio`, `segmented` | `radio`: every choice visible, at most 7; `segmented`: one row of buttons, at most 4 short ones |
| `tel`, `email`, `url` | `input` | the keyboard for it |
| `sku` | `code` | monospace |
| `media` | `picture` | the file and its words; drawn as wide as its place |
| `media`, `multiple` | `gallery` | the pictures in order; a row of its own |
| `list` | `rows` | its rows; a row of its own |
| `ref` | `dropdown` | the entries by title |
| `ref`, `many` | `checklist` | the entries ticked |
## What a document is
An entry — a post, a service, a master, a table, a product — is a **document**: what the business declares about itself. It is edited in the panel, rendered by the site at the addresses the collection gives it, and read by the modules that are pointed at it — the diary reads a service's `takes` and a master's `hours`. A document is public-grade by definition: nothing in it is a secret, and nothing in it is about a customer. What happens between the business and a visitor — an enquiry, a booking, an order — is the **ledger**, kept in the platform's database and never in a document or the repository. A field a page does not draw may still live in a document (a note for the diary); a customer's name never does.
## Modules
`modules` turns a domain of the platform on — bookings — and points it at collections of this schema. Which modules exist, what each reads from an entry and as what kind, and the settings document the owner fills in are in [modules](modules.md).
## Worked examples
Each of these is a file in this repository's contract-3 exam, judged by CI on every
commit. If one of them is wrong, the build is red before you read it.
### the least a schema says
The contract, the site's own language, and one block type with one field. Every other key may be left out; a field the owner edits says `client_editable: true` as well.
```json
{
"contract": 3,
"locale": "de",
"blocks": [
{
"type": "hero",
"v": 1,
"label": "Hero",
"fields": [
{
"key": "title",
"label": "Titel",
"kind": "text"
}
]
}
]
}
```
### everything contract 3 adds, said where it may be said
Every word contract 3 has and contract 2 has not, each where it may be said: a variant's `sku`, its `picks` and an `integer` weight in its list's row, a price's `qualifiers`, options as `{value, label}`, references `{to, many, on_delete}`, a list in a row, `localized`, roles on the shared text, routes written per language, `untranslated`.
```json
{
"contract": 3,
"generator": "test",
"locale": "de",
"locales": [
"en"
],
"blocks": [
{
"type": "product",
"v": 1,
"label": "Produkt",
"fields": [
{
"key": "title",
"label": "Name",
"kind": "text",
"required": true,
"max": 80
},
{
"key": "price",
"label": "Preis",
"kind": "money",
"qualifiers": [
"from",
"on_request"
],
"min": 0
},
{
"key": "colour",
"label": "Farbe",
"kind": "select",
"options": [
{
"value": "red",
"label": {
"de": "Rot",
"en": "Red"
}
},
{
"value": "oak"
}
]
},
{
"key": "category",
"label": "Kategorie",
"kind": "ref",
"ref": {
"to": [
"categories"
],
"on_delete": "nullify"
}
},
{
"key": "related",
"label": "Dazu",
"kind": "ref",
"ref": {
"to": [
"categories",
"tags"
],
"many": true
}
},
{
"key": "photo",
"label": "Bild",
"kind": "media",
"ratio": "3:2",
"localized": true
},
{
"key": "clip",
"label": "Film",
"kind": "media",
"accept": "video"
},
{
"key": "options",
"label": "Optionen",
"kind": "list",
"of": [
{
"key": "name",
"label": "Name",
"kind": "text"
},
{
"key": "values",
"label": "Werte",
"kind": "list",
"of": [
{
"key": "label",
"label": "Wert",
"kind": "text"
}
]
}
]
},
{
"key": "variants",
"label": "Varianten",
"kind": "list",
"of": [
{
"key": "sku",
"label": "Artikelnummer",
"kind": "sku"
},
{
"key": "price",
"label": "Preis",
"kind": "money"
},
{
"key": "weight",
"label": "Gewicht",
"kind": "number",
"integer": true
},
{
"key": "picks",
"label": "Wahl",
"kind": "picks"
}
]
}
]
},
{
"type": "category",
"v": 1,
"label": "Kategorie",
"fields": [
{
"key": "title",
"label": "Name",
"kind": "text",
"required": true
},
{
"key": "parent",
"label": "Oben",
"kind": "ref",
"ref": {
"to": [
"categories"
]
}
}
]
},
{
"type": "tag",
"v": 1,
"label": "Schlagwort",
"fields": [
{
"key": "title",
"label": "Name",
"kind": "text",
"required": true
}
]
},
{
"type": "contacts",
"v": 1,
"label": "Kontakt",
"fields": [
{
"key": "name",
"label": "Name",
"kind": "text",
"role": "name"
},
{
"key": "phone",
"label": "Telefon",
"kind": "tel",
"role": "phone"
},
{
"key": "social",
"label": "Profile",
"kind": "list",
"role": "social",
"of": [
{
"key": "url",
"label": "Adresse",
"kind": "url"
}
]
}
]
}
],
"page_seo": [
{
"key": "title",
"label": "Titel",
"kind": "text",
"localized": true
}
],
"shared": [
"contacts"
],
"collections": [
{
"name": "products",
"label": "Produkte",
"type": "product",
"route": {
"detail": {
"de": "/produkte/{slug}",
"en": "/products/{slug}"
},
"listing": "/produkte",
"per_page": 12
},
"order": {
"by": "title"
},
"group": "category",
"untranslated": "hide"
},
{
"name": "categories",
"label": "Kategorien",
"type": "category",
"route": {
"detail": "/kategorien/{slug}"
},
"order": "manual"
},
{
"name": "tags",
"label": "Schlagworte",
"type": "tag",
"route": "none",
"shown_on": [
"/schlagworte#tag-{slug}",
{
"de": "/start#{slug}",
"en": "/home#{slug}"
}
]
}
]
}
```
### a diary whose resources do services by one reference to several
The bookings pointed at two collections: services with no page of their own, shown on the price page by an anchor, and masters with a page each, who say what they do as one reference to several services and how many people fit as a whole number.
```json
{
"contract": 3,
"locale": "de",
"blocks": [
{
"type": "service",
"v": 1,
"label": "Leistung",
"fields": [
{
"key": "title",
"label": "Name",
"kind": "text",
"required": true
},
{
"key": "takes",
"label": "Dauer",
"kind": "duration"
},
{
"key": "costs",
"label": "Preis",
"kind": "money",
"qualifiers": [
"from"
]
}
]
},
{
"type": "master",
"v": 1,
"label": "Meisterin",
"fields": [
{
"key": "title",
"label": "Name",
"kind": "text",
"required": true
},
{
"key": "does",
"label": "Macht",
"kind": "ref",
"ref": {
"to": [
"services"
],
"many": true
}
},
{
"key": "seats",
"label": "Plätze",
"kind": "number",
"integer": true
}
]
}
],
"collections": [
{
"name": "services",
"label": "Leistungen",
"type": "service",
"route": "none",
"shown_on": [
"/preise#{slug}"
]
},
{
"name": "masters",
"label": "Team",
"type": "master",
"route": {
"detail": "/team/{slug}",
"listing": "/team"
}
}
],
"modules": {
"bookings": {
"services": "services",
"resources": "masters"
}
}
}
```
### an entry laid out for the person who fills it in
A service's `form`: the name and its category on one row, the length beside the price, the words for the page under a title of their own, the photograph in the aside — and a row of buttons for the category, quick lengths a tap away. The panel draws it on the entry's card and on a new entry; a phone draws each row as one column.
```json
{
"contract": 3,
"locale": "de",
"locales": [
"en"
],
"blocks": [
{
"type": "service",
"v": 1,
"label": {
"de": "Leistung",
"en": "Service"
},
"fields": [
{
"key": "title",
"label": "Name",
"kind": "text",
"required": true,
"max": 80,
"client_editable": true
},
{
"key": "category",
"label": {
"de": "Bereich",
"en": "Category"
},
"kind": "select",
"client_editable": true,
"options": [
{
"value": "cut",
"label": {
"de": "Schnitt",
"en": "Cut"
}
},
{
"value": "colour",
"label": {
"de": "Farbe",
"en": "Colour"
}
},
{
"value": "care",
"label": {
"de": "Pflege",
"en": "Care"
}
}
]
},
{
"key": "takes",
"label": {
"de": "Dauer",
"en": "Takes"
},
"kind": "duration",
"required": true,
"client_editable": true
},
{
"key": "costs",
"label": {
"de": "Preis",
"en": "Price"
},
"kind": "money",
"qualifiers": [
"from"
],
"client_editable": true
},
{
"key": "about",
"label": {
"de": "Ein Satz dazu",
"en": "A line about it"
},
"kind": "textarea",
"max": 280,
"client_editable": true
},
{
"key": "photo",
"label": {
"de": "Foto",
"en": "Photograph"
},
"kind": "media",
"ratio": "4:3",
"client_editable": true
}
],
"form": {
"sections": [
{
"rows": [
[
{
"field": "title",
"span": 4
},
"category"
],
[
"takes",
"costs"
]
]
},
{
"title": {
"de": "Auf der Seite",
"en": "On the page"
},
"note": {
"de": "Was die Preisliste zeigt",
"en": "What the price list shows"
},
"rows": [
[
"about"
]
]
}
],
"aside": [
"photo"
],
"widgets": {
"category": "segmented",
"takes": "presets"
}
}
}
],
"collections": [
{
"name": "services",
"label": {
"de": "Leistungen",
"en": "Services"
},
"type": "service",
"route": "none",
"shown_on": [
"/#services-{slug}"
]
}
]
}
```
### a type that renamed a field, with the step that brings older content up
A block type at version 2 whose version 1 called the title `heading` and spelt a value `centre`: the step from 1 renames both, and a block written at version 1 is read, and saved, as version 2.
```json
{
"contract": 3,
"locale": "de",
"blocks": [
{
"type": "hero",
"v": 2,
"label": "Hero",
"fields": [
{
"key": "title",
"label": "Titel",
"kind": "text"
},
{
"key": "align",
"label": "Ausrichtung",
"kind": "select",
"options": [
{
"value": "left"
},
{
"value": "center"
}
]
}
],
"upcast": [
{
"from": 1,
"rename": {
"heading": "title"
},
"values": {
"align": {
"centre": "center"
}
}
}
]
}
]
}
```
## Contract 2, the older contract
A site made before contract 3 keeps its schema in `jtk/catalogue.json`, `"contract": 2`, and its documents under `jtk/content/`, until the platform's team moves it with `jtk upgrade contract-3` in one commit. Such a tree is judged by contract 2's rules: a key of contract 3's in it is refused as unknown, and a tree with both files is refused. Never start a site there. Its words that contract 3 replaced, and what contract 3 says instead — the sentence the judge answers a `jtk/schema.json` that still says one:
| contract 2 says | in | contract 3 says |
| --- | --- | --- |
| `body` | a collection | the block types an entry may hold are the collection's `blocks` |
| `listing` | a collection | the listing is the route's: {"detail": "/works/{slug}", "listing": "/works"} |
| `pages` | a collection | an entry without a page of its own is route "none", with shown_on naming where it is shown |
| `per_page` | a collection | pagination is the route's: {"detail": "/works/{slug}", "listing": "/works", "per_page": 12} |
| `prefix` | a collection | where the entries live is the collection's route: {"detail": "/works/{slug}", "listing": "/works"}, or "none" with shown_on |
| `deprecated` | a field | contract 3 retires a field by removing it, and keeps what it held aside |
| `option_labels` | a field | an option's words are its own label: "options": [{"value": "wood", "label": "Holz"}] |
| `business_facts` | the file | contract 3 has no business facts — the business's own words are shared text, each field saying its `role` |
| `country` | the file | the country is the payee's own detail, not the schema's |
| `currency` | the file | the currency is the site's setting, not the schema's |
| `legal_name` | the file | the registered name is the payee's own detail, not the schema's |
| `tax_id` | the file | the registration number is the payee's own detail, not the schema's |
| `sample` | a view | contract 3 has no sample — nothing read it |
Besides these: a contract-2 `ref` names one collection by a string and holds a slug; an option is a string, its words in `option_labels`; a price is a bare number of minor units; a picture is its key; `min` or `max` of `0` means none. [The files under `jtk/`](jtk-files.md#contract-2-the-older-contract) has contract 2's files.
---
# Field kinds
There are 19, and the set is closed. Each one costs a validator on the server, a
form control in the admin, a zod schema in the browser and a rule in the
annotation lint — so the twentieth is a decision rather than a convenience, and a
site's schema naming one that is not here is refused with
[`JTK_E_KIND_UNKNOWN`](errors.md#jtk_e_kind_unknown). `sku` and `picks` are contract 3's
alone; the older contract 2 has the other 17.
**`min` and `max` do not mean one thing.** They count characters for text, the
value itself for a number, and items for a list or a gallery. The column below is
the whole answer; getting it wrong is the most common mistake in a first
schema. Absent is unbounded, and `0` is a bound.
**Per language** is whether a translation holds the value: the words are per
language and the facts are one value in every language, by the kind, unless
the field says `localized` — which a field may say only where the column
says what it changes ([translations](translations.md#which-values-are-per-language)).
A translation that holds a value that is not per language is refused with
[`JTK_E_TRANSLATION_SHARED`](errors.md#jtk_e_translation_shared).
**Tappable** is whether an element rendering the value must carry a
`data-jtk-path`: every value a page draws, a list by its rows and a switch by
what it switches, so the owner taps whatever they see. A value the page does not
draw — a link behind a button, an hour a countdown counts to — is `no_tap_target`
and needs none. Where the column says *advice*, a value drawn without its path is
[`JTK_W_UNANNOTATED_FIELD`](errors.md#jtk_w_unannotated_field) for now, not a
refusal.
## At a glance
| kind | in the file | `min` / `max` count | per language |
| --- | --- | --- | --- |
| `text` | string — `"Haircut"` | characters | yes; `localized: false`: one value |
| `textarea` | string, line breaks kept — `"Line one\nLine two"` | characters | yes; `localized: false`: one value |
| `richtext_lite` | string — `"A **short** passage"` | characters | yes; `localized: false`: one value |
| `markdown` | string of markdown — `"# Title\n\nText"` | characters | yes; `localized: false`: one value |
| `number` | JSON number, never quoted — `3`; whole where the field says `integer` | the value | no |
| `money` | `{"minor": 4500}` — whole minor units, ≥ 0: 45.00 in the site's one currency; `"from": true` or `"on_request": true` beside it where `qualifiers` allow | the value, in minor units | no |
| `duration` | whole number of minutes, ≥ 0 — `60` | the value, in minutes | no |
| `ref` | string: the `id` of an entry of a collection in `ref.to` — `"0193a5c3-0a11-7d02-9f3c-1e2d3c4b5a71"`; with `many`, a list of ids | — | no |
| `time_of_day` | whole number of minutes from local midnight, 0–1439 — `540` is 09:00 | minutes from midnight | no |
| `bool` | `true` or `false` | — | no |
| `select` | string, the `value` of one of `options` — `"daily"` | — | no |
| `tel` | string as written — `"+41 44 123 45 67"` | characters | no |
| `email` | string, one address — `"hello@example.ch"` | characters | no |
| `url` | string, http(s), `/path`, `#fragment`, `mailto:` or `tel:` — `"/kontakt#form"` | — | no; `localized: true`: the whole value |
| `date` | string `YYYY-MM-DD` — `"2026-10-20"` | — | no |
| `media` | `{"src": "media/…", "alt": "…", "focus": "50% 30%", "poster": "…"}`, all but `src` optional; with `multiple`, a list of them, each with its `_key` | pictures, with `multiple`; one picture takes none | its `alt`; a gallery, each picture's `alt`, by `_key`; `localized: true`: the whole value |
| `list` | list of rows, each `{"_key": "r1", …}` with the fields of `of`; a row may hold one list of its own | rows | the words in its rows, by `_key`; `localized: true`: the whole value |
| `sku` | string, a letter or digit then letters, digits, `.`, `_`, `-` — `"OAK-TABLE-180"` | — | no |
| `picks` | object from an option's `_key` to one of its values' `_key`, each a row key — `{"size": "s", "colour": "red"}`; `{}` picks nothing | — | no |
On contract 2, the older contract, four values are written otherwise — a price is the bare number, `4500`; a reference is the entry's slug, `"manicure"`; one picture is its key, `"media/…"`; a list's rows need no `_key` — and its schema writes a select's `options` as strings. Every other value is the same in both.
## What each one holds
| kind | holds | `min` / `max` | tappable |
| --- | --- | --- | --- |
| [`text`](#text) | One line of plain text — a heading, a name, a price as it is written. | Characters, counted as characters rather than bytes — an eighty-character Ukrainian title is eighty. | yes |
| [`textarea`](#textarea) | Several lines of plain text — a paragraph, an address. | Characters. | yes |
| [`richtext_lite`](#richtext_lite) | A short passage with emphasis and links in it. | Characters. | yes |
| [`markdown`](#markdown) | A document: the body of an entry, hundreds or thousands of words. | Characters. | yes |
| [`number`](#number) | A number — a price, a count, a year. | The value itself: `min: 1, max: 5` is one to five, not one to five digits. | yes — *advice* for now |
| [`money`](#money) | An amount of money — what a service costs, what a product is priced at. | The amount itself, in minor units — `max: 100000` is a ceiling of 1000.00. | yes |
| [`duration`](#duration) | A length of time in whole minutes — how long an appointment takes. | The value in minutes: `min: 15, max: 480` is a quarter of an hour to eight hours. | yes |
| [`ref`](#ref) | A reference to an entry of one of the schema's own collections — the service a master does, the range a product is in. | Nothing. The collection is the constraint. | no |
| [`time_of_day`](#time_of_day) | A time on a clock face — when the doors open. | Minutes from midnight, so `min: 720` is afternoons only. | yes — *advice* for now |
| [`bool`](#bool) | A switch — whether a section shows, whether a form is on the page. | Nothing. Bounds mean nothing here. | no |
| [`select`](#select) | One of a set of choices the schema names. | Nothing. The choices are the constraint. | yes — *advice* for now |
| [`tel`](#tel) | A telephone number as it is written on a sign. | Characters. | yes — *advice* for now |
| [`email`](#email) | One email address. | Characters. | yes — *advice* for now |
| [`url`](#url) | A link. | Nothing. | yes — *advice* for now |
| [`date`](#date) | A day, as YYYY-MM-DD. | Nothing. | yes — *advice* for now |
| [`media`](#media) | A picture or a clip — one, or a gallery of them with `multiple`. | With `multiple`, the number of pictures. One picture takes none on contract 3; on contract 2 they counted the characters of its key, which is almost never what anybody means. | yes |
| [`list`](#list) | Rows of fields — three cards, five steps, a table of prices. | The number of rows. | no |
| [`sku`](#sku) | A product's stock-keeping code — `OAK-TABLE-180`. Contract 3's alone. | Nothing. The pattern is the constraint. | no |
| [`picks`](#picks) | A variant's choice among its product's options, by key — `{"size": "s", "colour": "red"}`. Contract 3's alone. | Nothing. The shape is the constraint. | no |
## text
One line of plain text — a heading, a name, a price as it is written.
**Refused:** Text, and nothing else. A number arrives as a number and is refused.
**`min` and `max`:** Characters, counted as characters rather than bytes — an eighty-character Ukrainian title is eighty.
**Per language:** yes; `localized: false`: one value
**Tappable:** yes
## textarea
Several lines of plain text — a paragraph, an address.
**Refused:** Text. Line breaks are kept; markup is not interpreted.
**`min` and `max`:** Characters.
**Per language:** yes; `localized: false`: one value
**Tappable:** yes
## richtext_lite
A short passage with emphasis and links in it.
**Refused:** Text. The editor limits which marks exist; the server checks the length.
**`min` and `max`:** Characters.
**Per language:** yes; `localized: false`: one value
**Tappable:** yes
## markdown
A document: the body of an entry, hundreds or thousands of words.
**Refused:** Text, written as markdown. It is committed to the repository as markdown and rendered by the site's own pipeline.
**`min` and `max`:** Characters.
**Per language:** yes; `localized: false`: one value
**Tappable:** yes
## number
A number — a price, a count, a year.
**Refused:** A JSON number. A numeral in quotation marks is refused rather than converted, because coercion is how a price becomes the string "0". On contract 3 a field that says `integer` takes whole numbers only.
**`min` and `max`:** The value itself: `min: 1, max: 5` is one to five, not one to five digits.
**Per language:** no
**Tappable:** yes — *advice* for now
## money
An amount of money — what a service costs, what a product is priced at.
**Refused:** An amount in whole minor units, `{"minor": 25000}` for 250.00 — with `"from": true` or `"on_request": true` beside it where the field's `qualifiers` allow. A fraction of a minor unit is refused, and so is a negative amount. The currency is the site's and is not part of the value. Contract 2, the older contract, writes the bare number, `25000`.
**`min` and `max`:** The amount itself, in minor units — `max: 100000` is a ceiling of 1000.00.
**Per language:** no
**Tappable:** yes
## duration
A length of time in whole minutes — how long an appointment takes.
**Refused:** A whole number of minutes, never negative. Minutes are the unit slot arithmetic works in, so nothing converts it on the way.
**`min` and `max`:** The value in minutes: `min: 15, max: 480` is a quarter of an hour to eight hours.
**Per language:** no
**Tappable:** yes
## ref
A reference to an entry of one of the schema's own collections — the service a master does, the range a product is in.
**Refused:** The `id` of an entry of a collection the field's `ref: {to: […]}` names — with `many: true`, a list of ids. Refused unless that entry exists. A `ref` into its own collection is a tree — a category's `parent` — and one that leads back to the entry is refused. Contract 2, the older contract, holds the entry's slug and names one collection, `ref: "services"`.
**`min` and `max`:** Nothing. The collection is the constraint.
**Per language:** no
**Tappable:** no
## time_of_day
A time on a clock face — when the doors open.
**Refused:** A whole number of minutes from local midnight, 0 to 1439: 540 is nine in the morning. No zone travels with it — the zone is the site's, declared once.
**`min` and `max`:** Minutes from midnight, so `min: 720` is afternoons only.
**Per language:** no
**Tappable:** yes — *advice* for now
## bool
A switch — whether a section shows, whether a form is on the page.
**Refused:** true or false.
**`min` and `max`:** Nothing. Bounds mean nothing here.
**Per language:** no
**Tappable:** no
## select
One of a set of choices the schema names.
**Refused:** A string that is the `value` of one of `options`, which contract 3 writes as `[{"value": "daily", "label": …}]`. Anything else is refused.
**`min` and `max`:** Nothing. The choices are the constraint.
**Per language:** no
**Tappable:** yes — *advice* for now
## tel
A telephone number as it is written on a sign.
**Refused:** Digits, spaces and the punctuation a phone number is written with. Deliberately loose: a number is whatever a person writes.
**`min` and `max`:** Characters.
**Per language:** no
**Tappable:** yes — *advice* for now
## email
One email address.
**Refused:** A single address, parsed. A display name beside it is refused — this is an address, not a header.
**`min` and `max`:** Characters.
**Per language:** no
**Tappable:** yes — *advice* for now
## url
A link.
**Refused:** http or https with a host; a page of the site from its root, `/kontakt` or `/kontakt#form`; a fragment like `#lead-form` for somewhere on the same page; `mailto:` an address; `tel:` a number. Any other scheme is refused, which is what keeps `javascript:` out of a client's call to action.
**`min` and `max`:** Nothing.
**Per language:** no; `localized: true`: the whole value
**Tappable:** yes — *advice* for now
## date
A day, as YYYY-MM-DD.
**Refused:** A calendar date. Times and zones are not part of it.
**`min` and `max`:** Nothing.
**Per language:** no
**Tappable:** yes — *advice* for now
## media
A picture or a clip — one, or a gallery of them with `multiple`.
**Refused:** One picture is `{"src": …, "alt"?: …, "focus"?: "50% 30%", "poster"?: …}`, its `src` a key in our own bucket or a path to a file the repository ships; a gallery (`multiple`) is a list of them, each with its `_key`. Never a URL: a field that accepted one would let a client's page be made to load anything from anywhere. Contract 2, the older contract, holds one picture as its key alone, a string.
**`min` and `max`:** With `multiple`, the number of pictures. One picture takes none on contract 3; on contract 2 they counted the characters of its key, which is almost never what anybody means.
**Per language:** its `alt`; a gallery, each picture's `alt`, by `_key`; `localized: true`: the whole value
**Tappable:** yes
## list
Rows of fields — three cards, five steps, a table of prices.
**Refused:** An array of rows, each checked against `of` and each with its `_key` on contract 3. A row may hold one list of its own on contract 3 and none on contract 2: deeper has no form control and no annotation path.
**`min` and `max`:** The number of rows.
**Per language:** the words in its rows, by `_key`; `localized: true`: the whole value
**Tappable:** no
## sku
A product's stock-keeping code — `OAK-TABLE-180`. Contract 3's alone.
**Refused:** A letter or a digit, then letters, digits, `.`, `_` and `-`, sixty-four characters at most. Meant to be unique within its role on the site, and never changed once a record names it.
**`min` and `max`:** Nothing. The pattern is the constraint.
**Per language:** no
**Tappable:** no
## picks
A variant's choice among its product's options, by key — `{"size": "s", "colour": "red"}`. Contract 3's alone.
**Refused:** An object from an option's `_key` to the `_key` of one of its values, every key and value a row key: a lowercase letter, then lowercase letters, digits and dashes, thirty-two characters at most. `{}` is a variant that picks nothing, a product without options. The same in every language. Whether each key names an option of the product, and each value one of its values, is judged by the product's collection, not by the field.
**`min` and `max`:** Nothing. The shape is the constraint.
**Per language:** no
**Tappable:** no
---
# Categories, tags and trees
There is no taxonomy entity, and none is needed: a category is an entry of a
collection, and everything that points at one is a `ref`. The platform already
checks every reference — the entry must exist, and an entry something points at
is not deleted without the person saying they know — so a category inherits all
of it, and the owner adds, titles, translates and orders categories in the panel
the way they add a master.
The examples are contract 3's, which a new site is on; a contract-2 site
(`jtk/catalogue.json`) says the same with a collection's `prefix` and `pages`,
`option_labels` beside its `options`, and a `ref` as the collection's name.
## At a glance
| you want | declare |
| --- | --- |
| sections the repository names | `group` naming a `select` of the entry type |
| categories the owner adds | a `categories` collection, and `group` naming a `ref` to it |
| several tags on one entry | a `ref` with `"many": true` |
| a category inside a category | a `parent` field: a `ref` into the collection itself |
| a page per category with its entries | give the categories collection a `route` with a `detail`; its page lists what points at it |
| a page listing all the categories | a `listing` in the collection's `route` — none unless said |
## A group the repository names
A price list's sections, a menu's courses — a closed set that changes with the
design. A `select`, and the collection's `group` names it:
```json
{ "key": "section", "label": "Section", "kind": "select",
"options": [ { "value": "hair", "label": { "en": "Hair", "de": "Haare" } },
{ "value": "nails", "label": { "en": "Nails", "de": "Nägel" } } ] }
```
The listing, the panel's table and the booking form all show the entries under
the option's label, in the order of `options`. The `value` is the option's
identity, and renaming a section is a commit.
## Categories the owner adds
A group that is an entry of another collection. The owner adds a category in
the panel, gives it a title in every language and puts it in order; the headings
follow that collection's order.
```json
"blocks": [
{ "type": "category", "v": 1, "label": "Category", "fields": [
{ "key": "title", "label": "Title", "kind": "text", "required": true, "client_editable": true } ] },
{ "type": "service", "v": 1, "label": "Service", "fields": [
{ "key": "title", "label": "Title", "kind": "text", "required": true, "client_editable": true },
{ "key": "category", "label": "Category", "kind": "ref", "ref": { "to": ["categories"] }, "client_editable": true } ] }
],
"collections": [
{ "name": "categories", "label": "Categories", "type": "category", "order": "manual",
"route": "none", "shown_on": ["/services#{slug}"] },
{ "name": "services", "label": "Services", "type": "service", "order": "manual",
"route": "none", "shown_on": ["/services#{slug}"], "group": "category" }
]
```
In an entry's file the reference is the category's `id`:
`"fields": { "title": "Haircut", "category": "0193a5c3-0a11-7d02-9f3c-1e2d3c4b5a69" }`.
A `group` may not point into its own collection — that is a tree, below — and a
`group` naming anything but a `select` or a `ref` to one entry of one other
collection is refused with
[`JTK_E_COLLECTION_INVALID`](../reference/errors.md#jtk_e_collection_invalid)
or [`JTK_E_REF_INVALID`](../reference/errors.md#jtk_e_ref_invalid).
An entry naming no category, or one that is gone, is listed last.
## Tags
Several on one entry: a `ref` with `"many": true`. It is the shape the
diary already uses for what a master does, and the panel draws it as a picker of
chips, not as rows to add one by one.
```json
{ "key": "tags", "label": "Tags", "kind": "ref", "ref": { "to": ["tags"], "many": true }, "client_editable": true }
```
In the file it is the tags' ids, in order: `"tags": ["0193a5c3-…", "0193a5c3-…"]`.
A tag deleted in the panel is taken out of every entry that names it, with
the deletion; `"on_delete": "nullify"` on the `ref` says so without asking
first, and `restrict`, the default, asks.
## A tree
A `ref` into the collection itself is a parent. The schema takes it; a
parent that leads back to the entry — a category under itself, or under its own
grandchild — is refused when the panel writes it, and by `validate_schema`
and the import when a file says it.
```json
{ "key": "parent", "label": "Inside", "kind": "ref", "ref": { "to": ["categories"] }, "client_editable": true }
```
## A page per category
Give the categories collection a `route` with a `detail` —
`"route": { "detail": "/categories/{slug}" }` — and each category has an
address: `/categories/colour`. The scaffold's entry page lists, under it, the
entries of every other collection that point at it through a `ref`, in their
own collection's order, each linked where it has a page; a category with
children lists them too. Built statically like everything else, so a category
added in the panel appears with the next publish. On a site in several
languages each language has the page, at its own address (a pattern per
language, `{"de": "/kategorien/{slug}", "en": "/categories/{slug}"}`, where the
words differ).
A page listing every category — `/categories` — is not made unless the
`route` says `"listing": "/categories"`, with `per_page` for the pages after
the first (`/categories/page/2`). None by default on purpose: a page nobody
asked for is an address on a client's site nobody designed. With it, the
scaffold lists the entries there, grouped and paged, unless the repository has
a page of its own at that address; without it, the "and N more" line under a
category's entries is text rather than a link. A collection whose `route` is
`"none"` is drawn on the pages its `shown_on` names, which the repository
writes.
The annotation lint reads the built HTML as for any listing: a title drawn from
another entry carries that entry's path — `entry::title`, which the kit's
door writes — or `data-jtk-fixed` where it is not edited from this page.
---
# A site in several languages
How an agent writes a site in more than one language on contract 3: one
document in the site's own language — the original — and, beside it, a
translation that holds only the words. The owner edits the languages as one in
the panel ([the panel · languages](the-panel.md#languages)); you write them in
the files.
**Only when the brief names it.** A second language is a second site to keep
written, every page and every post, for ever ([the brief](the-brief.md)).
## Laying it out
```
npx @jtakeit/astro create --locale de-CH --locales en
```
`--locale` is the original's language, `--locales` the others. They become the
schema's `locale` and `locales`, spelt as BCP 47 tags (`de-CH`) in the schema,
in file names and in the data; an address carries the lowercase form in front
of it — `/preise`, `/en/preise`, `/fr-ch/preise` — and the kit's door is the
one place that maps between them. A language added later is a line in
`LOCALES` (`src/content/blocks.ts`), then `npx @jtakeit/astro copy `
and `npx @jtakeit/astro schema`.
`npx @jtakeit/astro copy ` writes `src/copy/.ts`: the words
that are not content — the form's messages, the privacy page, a listing's
pager — in the kit's words. A language without one says the site's own words
there, marked with their `lang`.
## The files
A translation is `..json` **beside its original**:
```
jtk/pages/preise.json the page, in the site's own language
jtk/pages/preise.en.json its English
jtk/entries/blog/erster.json
jtk/entries/blog/erster.en.json
jtk/shared.json, jtk/shared.en.json
```
It says which document it translates — `of`, the original's `id` — and its
`locale`, and then only the words, every block, row and picture named by the
original's `_key`, never by its place. It carries no `type` and no `v`; those
are the original's.
```json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"name": "Prices",
"seo": { "title": "Prices" },
"blocks": [
{ "_key": "hero", "title": "Our prices", "image": { "alt": "The salon" } },
{ "_key": "list", "items": [ { "_key": "r7k2", "title": "Haircut" } ] }
]
}
```
- **A page's translation** holds its `name`, its `seo` and the words of its
blocks. The blocks themselves are the original's: a block added, moved or
removed there is added, moved or removed in every language.
- **An entry's translation** holds its `slug` (its address in that language,
where you give one), `seo`, the words of its `fields`, and `blocks` — an
entry's body is **whole per language**: a translation with `blocks` of its
own replaces the original's, one without shows the original's.
- **The shared text's translation** (`jtk/shared.en.json`) holds the words of
its blocks, and no `of`: the file beside it names it. So would a module's
settings, where a module says a field is `localized`; the bookings and the shop
have nothing to translate.
## Which values are words
The field's kind decides, unless the field says `localized`:
| per language | the same in every language |
| --- | --- |
| text, textarea, rich text, markdown; a picture's `alt`; a gallery's words, per picture by `_key`; a list's words, per row by `_key`; `name`, `seo`, a slug | a picture's file, focus and poster; a price, a number, a date, a choice, a reference, a phone, an email, a link |
A picture with words on it, a link to a page in that language, or a list each
language has its own of says `localized: true`, and is then whole per language;
a name that is never translated says `localized: false`. **A shared value in a
translation is refused** —
[`JTK_E_TRANSLATION_SHARED`](../reference/errors.md#jtk_e_translation_shared):
change it in the original, and every language has it.
## The record of what a translation was made from
Each value a translation gives may carry a record in `translated`, under the
value's path — `name`, `slug`, `seo.title`, `blocks[hero].title`,
`blocks[list].items[r7k2].title`, `fields.title`, `fields.pictures[g1].alt`,
`blocks` for an entry's body:
```json
"translated": {
"blocks[hero].title": { "from": "9f2c41d0", "by": "agent", "at": "2026-11-12T09:00:00Z" }
}
```
`from` is the first eight hex digits of the SHA-256 of the original value's
canonical JSON, `by` is `person`, `agent` or `machine`, `at` a moment.
- **Leave the record out** for a value you write or change. The import records
it as made from the original as it stands now, by the agent.
- **Keep the record the platform wrote** for a value you leave as it is: that is
how a value made from an older original stays *outdated* until somebody
translates it again.
- **A record is never made from nothing.** Words where the original has none —
a page with no SEO whose English gives some — are the translation's own: no
record, neither missing nor outdated. A record whose `from` is empty is no
record.
- A malformed record — `from` not eight hex digits, `by` not one of the three,
a stray key — is refused,
[`JTK_E_TRANSLATION_RECORD`](../reference/errors.md#jtk_e_translation_record).
Leave it out.
- Words for a block, a row or a picture the original has not got — removed
there, or a key misspelt — are advice,
[`JTK_W_TRANSLATION_ORPHAN`](../reference/errors.md#jtk_w_translation_orphan):
shown nowhere, and left out by the next save.
## What nobody translated
A language without a translation of a value shows **the original's words**, and
says so: the door hands out which values came from the original
(`fromBase`, `lang()`), and the page gives them the original's `lang`.
`hreflang` and the sitemap name a language only where a translation is.
- **A collection may hide instead:** `untranslated: "hide"` keeps an entry out
of a language nobody translated it into.
- **An entry may be held back** in one language: `"visible": false` in its
translation.
- **What a module books is in every language, always.** An entry of a
collection the bookings name — the services, the masters, the classes, the
cars — is booked by the diary in any language's form, so it is never missing
from one. Its collection may not say `untranslated: "hide"`
([`JTK_E_ATTRIBUTE_INVALID`](../reference/errors.md#jtk_e_attribute_invalid)),
and its translation may not say `"visible": false`
([`JTK_E_DOCUMENT_INVALID`](../reference/errors.md#jtk_e_document_invalid)).
Untranslated, it shows the original's words. The form names a service and a
master by the original's slug (`entry.baseSlug`), whatever a language calls
it.
- **What a shop sells is in every language too.** A product the page's language
has no translation of is priced and sold all the same, in the site's own words:
the language chooses the words, never what is sold, and a price, a SKU and a
variant's `picks` are the original's. The page sends its `locale` with the cart
and the checkout, the order's lines are frozen in it, and **the buyer's letters
speak the order's language** — the confirmation, *on its way*, *ready for
pick-up* — in the language the page named where the platform's letters speak it
(`fr-CH` is French) and in the site's own otherwise; the owner's letter stays in
the site's language
([the buyer's language](../reference/shop-protocol.md#the-buyers-language)). A
shipping method's name is the site's own words in every language.
## What is left to do
`get_site` says it, for a site in several languages, in `languages`: a line a
language — *en: complete*, *fr-CH: 6 to translate, 2 outdated* — and each
document with its translation's file and the paths still **missing** (the
original's words shown untranslated) or **outdated** (made from an original
that has changed since). An agent told *6 to translate* writes those six. It
counts the panel's draft, so pull first (`git pull`, or `pull_code` and `jtk
pull`): the owner may have translated some meanwhile. A slug left as the
original's is not counted; a picture's `alt` is.
`jtkit progress` says the same off the files, before anything is pushed.
## Who translates
You do, in the files: an agent is a translator in its own right, and nothing
routes it through a machine. Machine translation (DeepL) is a panel action for
a person — the owner, an editor, the studio — and off on a platform without a
DeepL key; no tool of yours reaches it, and the platform refuses an agent
there. Words it writes are recorded `by: machine`, shown in the panel as
unchecked until a person reads them, and reach visitors only through a version
and a publish, like a person's. After a pull they are in the files like any
translation: keep them, or write over them — yours are recorded as the
agent's. Never call a translation service from a build, and never write a
machine's words into the files as yours.
The panel writes a person's words into the same translations (`by: person`):
pull before you edit them, as for any content.
## Before the push
- `npx @jtakeit/astro schema` judges every translation as the import will:
beside its original, `of` its id, in a language the schema names, holding
only words.
- `validate_schema` with the schema, the `jtk/` files — every translation among
them — and `site_id`: the platform's own judge, the same as the import's.
- After the build, `get_built_page` on `/en/…` reads a language as a visitor
does; `jtkit lint` on your own build checks every language's pages.
## An older site, on contract 2
A contract-2 site keeps a full copy of every document per language, under
`jtk/content//…`, and a photograph changed in one language stays old in
the others. `jtk upgrade contract-3` moves it: each copy becomes a translation
beside its original, and a value that differs between languages where it
should be one — two photographs, two prices — stops the move and is listed for
an answer. The platform's team moves every live site itself; a new site is on
contract 3 from `jtk create`.
---
# Modules
A module is a domain the platform keeps a ledger for — rows about what happened
between the business and a visitor. A schema turns one on under `modules`,
by name, and points each of its **roles** at a collection of the same schema:
the module works on entries the client already edits, never on a second copy.
```jsonc
"modules": {
"bookings": { "services": "services", "resources": "masters" }
}
```
## At a glance
| | |
| --- | --- |
| the declaration | `"modules": { "": { "": "" } }` in `jtk/schema.json` |
| `bookings` roles | `services` (required), `resources` (required), `classes` (optional) |
| `bookings` settings | `jtk/modules/bookings.json`: `{"v": 1, "settings": {…}}`, each row of a list with its `_key` (contract 2: `jtk/bookings.json`, one `bookings_config` block) |
| `shop` roles | `products` (required) |
| `shop` settings | `jtk/modules/shop.json`: `{"v": 1, "settings": {…}}`, each row of a list with its `_key` |
| several units in one booking | `count` — on `GET /api/availability` and in `POST /api/book`; never `units`, `nights` or `days`, which the edge drops |
| money | `{"minor": 4500}`, whole minor units of the site's one currency — 45.00 (contract 2: the bare `4500`) |
| times | `time_of_day` is minutes from local midnight; `duration` is minutes |
| an entry a module reads | a record: no `body`; a service collection is `route: "none"` with `shown_on` |
| in other languages | every entry a role names is in every language, never hidden: no `untranslated: "hide"`, no `visible: false` in its translation |
| the words a booking says | [the dictionary](booking-words.md); any other key is `JTK_W_WORD_UNKNOWN` |
The set is closed. A name not below is refused with
[`JTK_E_MODULE_UNKNOWN`](errors.md#jtk_e_module_unknown); a role left
unbound, a role pointed at a collection that is not declared, or an entry type
that cannot carry what the module reads is refused with
[`JTK_E_MODULE_ROLE_INVALID`](errors.md#jtk_e_module_role_invalid).
What a module **reads** from an entry is a field of the entry's own type,
declared by the site like any other and named by the key below. The entry type
may carry anything else besides — a description, a picture, a price written in
words for the page — and the module reads none of it. A key it reads must have
the kind it reads it as, and a **required** one must be declared, though an
entry may leave it empty: what that does is said beside each.
The module's **settings** are a document of ours: the owner fills them in in the
panel (under the diary), a save writes them to `jtk/modules/.json` so
that a page can read them, and `import_branch` reads that file back into the
diary. So the file is also how an agent **seeds** the diary before anybody
opens the panel — the module's own document, `v` and its `settings`, every
row of a list with its `_key` ([the files under `jtk/`](jtk-files.md)
shows it whole). On the scaffold `npx @jtakeit/astro schema` seeds an empty
one when the schema turns the module on:
```json
{ "v": 1, "settings": { "zone": "Europe/Zurich", "confirm": "auto", "payment": "no",
"hours": [{ "_key": "mon", "day": "monday", "opens": 540, "closes": 1020 }] } }
```
A file in any other shape — the settings as top-level keys, a key beside `v`
and `settings`, a value a field's kind refuses — is refused with
[`JTK_E_DOCUMENT_INVALID`](errors.md#jtk_e_document_invalid) by
`import_branch` and by `validate_schema`, rather than read as an
empty diary. Its fields are listed so that a seed and a page both know what the
owner will be asked; a site does not declare them. On contract 2, the older
contract, the same settings are one block of the module's config type in
`jtk/.json` — `{"blocks": [{"type": "bookings_config", "v": 1, …}]}` —
refused in another shape with
[`JTK_E_MODULE_FILE_INVALID`](errors.md#jtk_e_module_file_invalid).
An entry a module reads is a **record**, not a post: short fields, no `body`,
and for services `route: "none"`, shown on the page that lists them. What
the module holds — the owner's hours, the services' prices — lives once; a page
block that types it again as text is a second copy. The judge says both as
advice, refusing nothing
([`JTK_W_MODULE_POST`](errors.md#jtk_w_module_post),
[`JTK_W_MODULE_TWIN`](errors.md#jtk_w_module_twin)).
**What a module books is in every language.** An entry of a collection a role
names is booked by the diary in any language's form, so it is never held back
in a language: the collection may not say `untranslated: "hide"`
([`JTK_E_ATTRIBUTE_INVALID`](errors.md#jtk_e_attribute_invalid)), and a
translation of its entry may not say `visible: false`
([`JTK_E_DOCUMENT_INVALID`](errors.md#jtk_e_document_invalid)). Where
nobody translated it, a language shows the original's words — [translations](translations.md#what-is-booked-is-in-every-language).
## bookings
Appointments: what a visitor may book, who or what it occupies, and when the business is open.
### Roles
| role | required | means |
| --- | --- | --- |
| `services` | yes | The collection of things that may be booked. Each entry carries how long it takes in a `takes` field, and — to be payable online — what it costs in a `costs` field, in minor units of the site's currency. A service without `costs` is bookable and not payable, which is an ordinary state. |
| `resources` | yes | The collection of things that get occupied — masters, chairs, tables. One entry is a solo business. An entry may carry its own weekly `hours` (a list of `day`, `opens`, `closes` rows, the same shape as the module's), and is then offered only inside them and inside the business's own. |
| `classes` | no | The collection of classes the resources are grouped in — a fleet's Економ, Комфорт, Бус. Optional: without it the diary draws its resources in one list. A class is an entry of its own so that it can carry its price and the site can show it. |
### What it reads from an entry of `services`
| key | kind | in the file | required | means |
| --- | --- | --- | --- | --- |
| `takes` | [`duration`](field-kinds.md#duration) | minutes | yes | How long one appointment takes, in minutes. An entry that leaves it empty is not offered: nothing can be laid on a grid without a length. |
| `costs` | [`money`](field-kinds.md#money) | `{"minor": 8500}` | no | What it costs, in minor units of the site's currency — 8500 is CHF 85.00. Without it, and without `rates`, the service is bookable and not payable, whatever the module's payment setting says. A price written in words for the page is a different field. |
| `per` | [`select`](field-kinds.md#select) | an option's value | no | What the price is counted in (wiki/70): `booking` — once, whatever the party, a haircut is one head — or `person`, the price times the party: a class per place, a tour, shoes. Without it, `booking`. A service with no `takes` and a price is an add-on — taken only beside a timed service in one visit, priced once per visit, times the party when `person`. |
| `rates` | [`list`](field-kinds.md#list) | rows, each with its `_key` | no | What it costs by the hour of the week, instead of `costs` and never beside it: rows of `day`, `from`, `until` and `costs`, like a week of opening hours with a price on each row — a lane 25 € before six and 42 € on a Friday night. Each unit of a booking (one `takes`) is priced by the row covering its start, and the booking is the sum; Friday 18:00–21:00 at a before-eight and an after-eight price is two hours at one and one at the other. Rows may not overlap on a day. An open hour no row covers is not sold: the form does not offer it for this service, and the panel says which hours those are. |
| `scale` | [`select`](field-kinds.md#select) | an option's value | no | What this service is sold in: `hourly` — an appointment at a time inside opening hours — or `daily`, whole days from midnight. Without it, the module's `scale`. One business may sell both: a three-hour photo session and a day's hire of the same van. |
| `fewest` | [`number`](field-kinds.md#number) | a number | no | The fewest of this service a visitor may take at once — nights, for a service that `takes` a day; hours, for one that takes an hour. Without it, one. |
| `most` | [`number`](field-kinds.md#number) | a number | no | The most of this service a visitor may take at once. Without it, thirty by the day and one by the hour. A week sold as one service is `takes` of seven days with `fewest` and `most` both one; a day is `takes` of one day, one to thirty; a studio's hour is `takes` of sixty, one to twelve — the length and the price times the hours taken. |
A `rates` row is `day` (`select`: monday · tuesday · wednesday · thursday · friday · saturday · sunday), `from` (`time_of_day`), `until` (`time_of_day`), `costs` (`money`), `from_unit` (`number`), `until_unit` (`number`).
### What it reads from an entry of `resources`
| key | kind | in the file | required | means |
| --- | --- | --- | --- | --- |
| `hours` | [`list`](field-kinds.md#list) | rows, each with its `_key` | no | This resource's own week, in the same rows as the business's hours. Without it the resource keeps the business's hours. A closing time before the opening one is after midnight: 18:00–01:00 is one row. |
| `does` | [`ref`](field-kinds.md#ref) | `ref: {to: [], many: true}` — a list of ids | no | The services this resource performs: on contract 3 one reference to several entries of the services collection, `{"to": ["services"], "many": true}`, holding their ids; on contract 2, the older contract, rows naming a service's slug (`service`), best declared as a `ref` into the services collection. Either way the admin offers a choice and refuses a service that does not exist. Without it, or empty, the resource does all of them. Natalie does gel; Mara does pedicure. |
| `seats` | [`number`](field-kinds.md#number) | a number | no | How many people fit, for a resource booked whole — a table, a private room. A booking's party has to fit, and the smallest resource that fits is offered first. Leave it out for a chair. |
| `spots` | [`number`](field-kinds.md#number) | a number | no | How many bookings share one slot, for a resource booked by the place — a class, a tour, a tasting. A resource with spots is a session: it offers the start of each of its hours rows and nothing in between. Never together with seats. |
| `marks` | [`text`](field-kinds.md#text) | words | no | What tells this one from its twins, said after its name — a car's colour and plate («білий · AA1234BB»), a flat's floor, a tool's serial number. The diary, the customer's page and the letters say «VW Combi · білий · AA1234BB». One field for every business rather than a colour and a plate for cars. |
| `class` | [`ref`](field-kinds.md#ref) | an entry's `id` | no | Which class this resource is in — Економ, Комфорт, Бус — as a `ref` into the collection bound as the module's `classes`. The diary groups resources by it; a resource without one is drawn under «without a class». A class renamed keeps its resources: the reference holds the class's id (its slug on contract 2, which never changes). |
A `hours` row is `day` (`select`: monday · tuesday · wednesday · thursday · friday · saturday · sunday), `opens` (`time_of_day`), `closes` (`time_of_day`).
### What it reads from an entry of `classes`
| key | kind | in the file | required | means |
| --- | --- | --- | --- | --- |
| `costs` | [`money`](field-kinds.md#money) | `{"minor": 8500}` | no | What one unit of the service — a night, a day of hire — costs in this class, in minor units of the site's currency. It replaces the service's price for a resource of this class rather than adding to it; the service is then the unit — a night — and not the price. |
### The settings document
| key | kind | `min` / `max` | required | edited by |
| --- | --- | --- | --- | --- |
| `zone` | `select`: Europe/Kyiv · Europe/Warsaw · Europe/Berlin · Europe/Zurich · Europe/Vienna · Europe/Prague · Europe/London · Europe/Lisbon | — | yes | the owner |
| `hours` | `list` | up to 21 | no | the owner |
| `scale` | `select`: hourly · daily | — | no | the studio |
| `closed` | `list` | up to 60 | no | the owner |
| `slot_every` | `duration` | 5 – 240 | no | the studio |
| `buffer` | `duration` | up to 1440 | no | the owner |
| `hand_out` | `time_of_day` | — | no | the owner |
| `hand_back` | `time_of_day` | — | no | the owner |
| `hands_over` | `bool` | — | no | the studio |
| `buffer_stay` | `duration` | up to 1440 | no | the owner |
| `lead` | `duration` | up to 20160 | no | the owner |
| `horizon` | `number` | 1 – 730 | no | the owner |
| `party` | `number` | 1 – 50 | no | the owner |
| `quantity` | `number` | 1 – 20 | no | the owner |
| `kind` | `text`: apartments · car_rental · clinic · coworking · equipment_rental · hotel · photo_studio · restaurant · salon · sessions | up to 40 | no | the studio |
| `kit` | `text` | up to 40 | no | the studio |
| `kit_version` | `text` | up to 40 | no | the studio |
| `words` | `list` | up to 200 | no | the studio |
| `combine` | `bool` | — | no | the owner |
| `page` | `text` | up to 200 | no | the studio |
| `contact` | `select`: either · both | — | no | the owner |
| `confirm` | `select`: auto · by_hand | — | yes | the owner |
| `hold` | `duration` | 15 – 20160 | no | the studio |
| `cancel_until` | `duration` | up to 20160 | no | the owner |
| `payment` | `select`: no · deposit · full | — | yes | the owner |
| `deposit` | `number` | 1 – 100 | no | the owner |
A `hours` row is `day` (`select`: monday · tuesday · wednesday · thursday · friday · saturday · sunday), `opens` (`time_of_day`), `closes` (`time_of_day`).
A `closed` row is `from` (`date`), `until` (`date`), `who` (`text`).
A `words` row is `lang` (`select`: en · es · fr · pt · ru · de · it · uk), `key` (`text`), `text` (`text`).
The keys a `words` row may name are the dictionary's, and nothing else: [the words a booking may say](booking-words.md) lists them. A key not in that list is advised as `JTK_W_WORD_UNKNOWN`.
## shop
A shop: products with options, variants and customizations, stocked by SKU and sent by the owner's zones and rates. Its stock is never in a file: the agent that builds the shop sets each SKU's starting count with `set_stock` until the SKU first sells, the owner corrects it in the panel, and a product page asks what is left of each variant by the shop protocol. A buyer checks out through the protocol and pays on the business's own Stripe account; a paid order is told where the site's enquiries go, the buyer gets a confirmation, and the owner runs the shop in the panel — its products, stock, shipping and orders, fulfilled with a tracking number or refunded with the items put back. A site draws it with the kit's storefront, a base to copy, and `jtk import products` brings its catalogue in.
### Roles
| role | required | means |
| --- | --- | --- |
| `products` | yes | what the shop sells: an entry a product, its variants priced and stocked by SKU; a hidden product (`visible: false`) is held only to its SKUs and its 2,000 variants until it is shown |
### What it reads from an entry of `products`
| key | kind | in the file | required | means |
| --- | --- | --- | --- | --- |
| `title` | [`text`](field-kinds.md#text) | words | yes | What the product is called, in every language of the site — required, as every entry's title is. |
| `options` | [`list`](field-kinds.md#list) | rows, each with its `_key` | no | The axes a product varies along — size, colour — as rows of a `name` and its `values`, each with a `label`. As many as a product needs: its variants, at most 2,000, are the limit. A variant names a value by its key, so renaming or translating one breaks nothing. Never `localized`: a translation gives the words, by key. |
| `variants` | [`list`](field-kinds.md#list) | rows, each with its `_key` | yes | What is sold: rows of a `sku`, a `price`, and — when there are options — the `picks` that say which value of each. A simple product is one variant without picks. The SKU is unique on the site and is what stock and orders are kept by; the `price` is one amount, with no `qualifiers`; `weight` is whole grams; `on_sale` takes a variant off sale without deleting it — without it, on sale. A SKU an order named stays its variant's: the save and the import refuse a draft that changes it or gives it to another variant (`JTK_E_SKU_ORDERED`); a variant removed, like a product deleted, keeps its SKUs from every other. At most 2,000 a product. Never `localized`: SKUs, prices and picks are the original's. |
| `customizations` | [`list`](field-kinds.md#list) | rows, each with its `_key` | no | What a buyer may be asked that is not stocked — a colour for each part, a name on a tag: rows of a `name`, a `kind` (`choice`, `yes_no` or `text`), whether a `choice` or a `text` is `required` (a `yes_no` is ticked or not, and is never required), a `max` of characters for a `text`, the `choices` of a `choice` (each a `label` and what it `adds`) and what a `yes_no` or a `text` `adds` to the price — each one amount, with no `qualifiers`. Never `localized`. |
| `tracked` | [`bool`](field-kinds.md#bool) | words | no | Whether stock is counted. A product that is not tracked — made to order — is never sold out. Without it, tracked. |
| `size_class` | [`select`](field-kinds.md#select) | an option's value | no | What size the shipping rates treat the product as: a `letter`, a `parcel` or `bulky`. Without it, a parcel. |
| `tax_code` | [`text`](field-kinds.md#text) | words | no | The Stripe tax code the product is taxed under where the business charges VAT: `txcd_` and eight digits — `txcd_35010000` for printed books. Without one, ordinary goods (`txcd_99999999`); Stripe applies each country's rate, and no rate is kept here. |
| `tariff_number` | [`text`](field-kinds.md#text) | words | no | The customs tariff number, needed only when the shop ships abroad. |
| `made_in` | [`text`](field-kinds.md#text) | words | no | The country the product is made in, needed only when the shop ships abroad. |
A `options` row is `name` (`text`), `values` (`list`).
A `variants` row is `sku` (`sku`), `price` (`money`), `weight` (`number`), `picks` (`picks`), `on_sale` (`bool`).
A `customizations` row is `name` (`text`), `kind` (`select`: choice · yes_no · text), `required` (`bool`), `max` (`number`), `choices` (`list`), `adds` (`money`).
### The settings document
| key | kind | `min` / `max` | required | edited by |
| --- | --- | --- | --- | --- |
| `zones` | `list` | — | no | the owner |
| `methods` | `list` | — | no | the owner |
| `kit` | `text` | up to 40 | no | the studio |
| `kit_version` | `text` | up to 40 | no | the studio |
A `zones` row is `name` (`text`), `countries` (`list`).
A `methods` row is `zone` (`text`), `name` (`text`), `pickup` (`bool`), `price` (`money`), `bands` (`list`), `free_above` (`money`), `free_bulky` (`bool`).
The other half of a module is a page's, once the module is on: for bookings, [bookings on the site](../guides/bookings-on-the-site.md) is what a booking page draws, and [the booking protocol](booking-protocol.md) the addresses it talks to; for the shop, [the shop on the site](../guides/shop-on-the-site.md) is what a product page, the cart and the checkout step draw and how the catalogue comes in, and [the shop protocol](shop-protocol.md) the addresses they talk to — what is left, the cart's shipping, the checkout and the order's page.
---
# The words a booking may say
The settings of the bookings module carry `words` — rows of `lang`,
`key` and `text` that replace what the form, the letters, the visitor's
page and the diary say for one business ([modules](modules.md)). A row may name
only a key below; any other is advised as `JTK_W_WORD_UNKNOWN` and changes
nothing. A booking by the day may say a key's day's form: the key with `Days`
after it (`letter.confirmedDays`).
## In which language
Every letter to a customer, every message to the owner, the customer's own
page and the dates in them speak **the site's language** — `locale` in
the schema, or the one the site was created with — read by one rule: the
region is read off and the case does not matter, so `de-CH`, `DE`
and `de_CH` are German and `pt-BR` is Portuguese. The words are
written in `en`, `es`, `fr`, `pt`, `ru`, `de`, `it`, `uk`; a site in any other language — `pl`, `ka` — is
written to in English, which is advised as `JTK_W_LOCALE_FALLBACK` and
said to the owner under Working hours. The site's stored language is read
this way, never rewritten.
**A booking keeps no language of its own** — a known limit. The customer's
browser and the language they booked in are not read: a German site writes to
its customers in German, whoever they are. The bot answers a button under a
notice in the site's language, then in the reader's Telegram's; a command in
the reader's Telegram's first. A `words` row names one of these languages
exactly, with no region.
| where | keys |
| --- | --- |
| `activity` | `activity.booking.decided.done` · `activity.booking.decided.no_show` · `activity.booking.decided.underway` |
| `bot` | `bot.acked` · `bot.attached` · `bot.bookingGone` · `bot.codeGone` · `bot.notAttached` · `bot.nothingToStop` · `bot.proposalGone` · `bot.proposalTaken` · `bot.staleChange` · `bot.stopped` · `bot.yesCancel` · `bot.yesDecline` |
| `collection` | `collection.role.resources.add` · `collection.role.resources.emptyNote` · `collection.role.resources.emptyTitle` · `collection.role.resources.note` · `collection.role.resources.one` · `collection.role.resourcesDays.add` · `collection.role.resourcesDays.emptyNote` · `collection.role.resourcesDays.emptyTitle` · `collection.role.resourcesDays.note` · `collection.role.resourcesDays.one` · `collection.role.services.add` · `collection.role.services.emptyNote` · `collection.role.services.emptyTitle` · `collection.role.services.nobody` · `collection.role.services.note` · `collection.role.services.one` · `collection.role.servicesDays.add` · `collection.role.servicesDays.emptyNote` · `collection.role.servicesDays.emptyTitle` · `collection.role.servicesDays.note` · `collection.role.servicesDays.one` |
| `diary` | `diary.all.none` · `diary.card.done` · `diary.card.missed` · `diary.card.overdue` · `diary.card.underway` · `diary.done` · `diary.feed.arrivals_few` · `diary.feed.arrivals_many` · `diary.feed.arrivals_one` · `diary.feed.arrivals_other` · `diary.feed.departures_few` · `diary.feed.departures_many` · `diary.feed.departures_one` · `diary.feed.departures_other` · `diary.feed.empty` · `diary.feed.inArrival` · `diary.feed.inDeparture` · `diary.feed.inLabel` · `diary.feed.outLabel` · `diary.feed.tomorrowAt` · `diary.gone` · `diary.handOut` · `diary.list.checkIn` · `diary.list.checkOut` · `diary.list.guest` · `diary.moveSheet.struck` · `diary.nights_few` · `diary.nights_many` · `diary.nights_one` · `diary.nights_other` · `diary.noShow` · `diary.none` · `diary.noneDays` · `diary.sheet.checkIn` · `diary.sheet.checkOut` · `diary.sheet.nights` · `diary.side.bookings_few` · `diary.side.bookings_many` · `diary.side.bookings_one` · `diary.side.bookings_other` · `diary.side.tests_few` · `diary.side.tests_many` · `diary.side.tests_one` · `diary.side.tests_other` · `diary.waiting.noShows_few` · `diary.waiting.noShows_many` · `diary.waiting.noShows_one` · `diary.waiting.noShows_other` · `diary.whole.notFound` · `diary.window.cancelYes` · `diary.window.chip.away` · `diary.window.chipText.away` · `diary.window.offerClosed` · `diary.window.offerClosedDays` · `diary.window.reach.manualEmail` · `diary.window.reach.noEmail` · `diary.window.same` |
| `diaryNumbers` | `diaryNumbers.noShow` |
| `form` | `form.any` · `form.badEmail` · `form.badPhone` · `form.book` · `form.confirmed` · `form.failed` · `form.length` · `form.manage` · `form.needBoth` · `form.needContact` · `form.pending` · `form.resource` · `form.sending` · `form.service` · `form.services` · `form.tooMany` |
| `letter` | `letter.acceptButton` · `letter.address` · `letter.cancelButton` · `letter.cancelled` · `letter.confirmed` · `letter.declineAsk` · `letter.declineButton` · `letter.ics` · `letter.keep` · `letter.keepDays` · `letter.lapsedUnanswered` · `letter.lapsedUnpaid` · `letter.manage` · `letter.manageButton` · `letter.moved` · `letter.movedDays` · `letter.offerClosed` · `letter.offerClosedDays` · `letter.otherTimeButton` · `letter.proposalExpired` · `letter.proposalWithdrawn` · `letter.proposed` · `letter.proposedNew` · `letter.proposedNow` · `letter.proposedUntil` · `letter.reason` · `letter.receivedPayFirst` · `letter.receivedPayFirstDays` · `letter.receivedWaiting` · `letter.refused` · `letter.refusedDays` · `letter.reminder` · `letter.subjectCancelled` · `letter.subjectConfirmed` · `letter.subjectLapsed` · `letter.subjectMoved` · `letter.subjectProposalExpired` · `letter.subjectProposalWithdrawn` · `letter.subjectProposed` · `letter.subjectReceived` · `letter.subjectRefused` · `letter.subjectReminder` · `letter.telegram` · `letter.until` · `letter.was` · `letter.what` · `letter.when` · `letter.will` · `letter.with` |
| `owner` | `owner.askedFor` · `owner.email` · `owner.movedBy` · `owner.name` · `owner.new` · `owner.nights_few` · `owner.nights_many` · `owner.nights_one` · `owner.nights_other` · `owner.paidUnbooked` · `owner.paidUnbookedLine` · `owner.phone` · `owner.proposalAccepted` · `owner.proposalDeclined` · `owner.proposalLost` · `owner.test` · `owner.testLine` · `owner.waitConfirm` · `owner.waitPay` · `owner.was` · `owner.what` · `owner.when` · `owner.with` · `owner.withdrawn` |
| `page` | `page.accepted` · `page.acked` · `page.address` · `page.askChange` · `page.back` · `page.call` · `page.cancel` · `page.confirm` · `page.confirmDays` · `page.decided` · `page.decline` · `page.declined` · `page.done` · `page.expired` · `page.failed` · `page.freed` · `page.fromHour` · `page.gone` · `page.ics` · `page.late` · `page.lost` · `page.move` · `page.moveDays` · `page.none` · `page.now` · `page.offerGone` · `page.offerNew` · `page.offerNow` · `page.offerUntil` · `page.offered` · `page.ok` · `page.otherTime` · `page.phone` · `page.pick` · `page.pickDays` · `page.priced` · `page.pricedDays` · `page.stale` · `page.state.cancelled` · `page.state.confirmed` · `page.state.no_show` · `page.state.pending` · `page.sure` · `page.tg` · `page.title` · `page.toHour` · `page.until` · `page.was` · `page.what` · `page.when` · `page.will` · `page.withdrawn` · `page.yesDecline` |
| `schedule` | `schedule.allClosed` · `schedule.answersHint` · `schedule.answersHintDays` · `schedule.boundNote` · `schedule.boundNoteDays` · `schedule.boundTitle` · `schedule.boundTitleDays` · `schedule.daily.buffer_stay.hint` · `schedule.daily.cancel_until.hint` · `schedule.daily.closed.hint` · `schedule.daily.contact.hint` · `schedule.daily.deposit.hint` · `schedule.daily.hold.label` · `schedule.daily.horizon.label` · `schedule.daily.lead.hint` · `schedule.daily.lead.label` · `schedule.daily.party.label` · `schedule.daily.payment.label` · `schedule.fields.buffer.hint` · `schedule.fields.buffer.label` · `schedule.fields.cancel_until.hint` · `schedule.fields.closed.hint` · `schedule.fields.contact.hint` · `schedule.fields.hold.label` · `schedule.fields.horizon.label` · `schedule.fields.lead.hint` · `schedule.fields.lead.label` · `schedule.fields.party.hint` · `schedule.fields.payment.label` · `schedule.fields.slot_every.hint` · `schedule.note` · `schedule.noteDays` · `schedule.role.classes` · `schedule.role.resources` · `schedule.role.services` · `schedule.roleDays.classes` · `schedule.roleDays.resources` · `schedule.roleDays.services` · `schedule.rulesTitle` · `schedule.rulesTitleDays` |
---
# The files under `jtk/`
What a site's repository holds under `jtk/`, file by file, in the shape the
platform reads and writes them. You can seed a repository before anybody
opens the panel, and an import reads back exactly what you wrote. This is
contract 3, the contract every new site is written in, and
`npx @jtakeit/astro create` lays it out. A site made before 12 November 2026
may still be on contract 2. [Its files](#contract-2-the-older-contract) are
at the end, and nothing new is written that way.
```
jtk/
schema.json the schema: what the owner may edit — yours, written by `jtk schema`
pages/index.json a page, named for its address: `/` is index.json
pages/prices.json /prices
pages/prices.en.json its English, beside it — a translation
entries/services/manicure.json an entry of the collection `services`
entries/services/manicure.en.json its English
shared.json the text on every page: the contacts, a footer note
shared.en.json
modules/bookings.json the diary's settings, when the schema turns bookings on
site.json the platform's, to the site: its id, slug, media host, currency
design.json the template's own: the editor's chrome
```
## What every file keeps to
- **The directory is the kind.** A page is under `pages/`, an entry under
`entries//`, a module's settings under `modules/`. A file under
any of them says what its place says. A `path`, `collection` or `slug`
that disagrees with the file's place is refused with
[`JTK_E_DOCUMENT_INVALID`](errors.md#jtk_e_document_invalid).
- **One identity per thing, minted once.** A page and an entry have an `id`,
a lowercase UUID (version 7 when new). A block, a row of a list and a
picture of a gallery have a `_key`: a lowercase letter, then lowercase
letters, digits and hyphens, up to 32. Nothing is named by its place in a
list. `npx @jtakeit/astro schema` (`jtkit schema` on another generator)
mints every name a file lacks, and so do the platform's saves. A file
written by hand without them is refused
([`JTK_E_UNNAMED`](errors.md#jtk_e_unnamed),
[`JTK_E_DOCUMENT_INVALID`](errors.md#jtk_e_document_invalid)).
- **Empty is absent.** Leave a value nobody wrote out of the file. Never
write `null`, `""` or `[]`; an import folds them away.
- **No key a document has not got.** A key that is neither the file's own
nor a field the schema declares is refused. Inside an object the reserved
keys are `_key` and `_orphans`, and in a block also `type`, `v` and
`view`; any other `_` key is refused.
- **Values are what their kinds say** ([field kinds](field-kinds.md#at-a-glance)).
A price is `{"minor": 4500}`, a picture `{"src": …, "alt": …}`, a
reference the entry's `id`. Contract 2's shapes — a bare number, a
picture's key, a slug — are refused here.
- **One form.** The platform writes a file as `JSON.stringify(value, null, 2)`
does, with one newline at the end. The top-level keys come in the order
this page gives. In every object below them, `_key`, `type`, `v` and
`view` come first, the rest in byte order, and `_orphans` last. A file you
wrote that says the same as the save would is kept byte for byte, so the
form is the platform's habit, not your rule.
- **Whose each file is.** The schema is yours. `site.json` is the
platform's. Pages, entries, the shared text and a module's settings are the
owner's, through [the three stages](../guides/the-three-stages.md): you
seed them, `import_branch` reads them into the panel, and every save writes
them back as a commit. Records — enquiries, bookings, orders — are never in git.
A place in a file is named by keys in an annotation, `data-jtk-path`, and in
a translation. The kit's door writes the annotations, so a template never
spells one:
| place | named |
| --- | --- |
| a field of a block on the page | `blocks[hero].title` |
| a field of a row | `blocks[faq].items[r7k2].answer` |
| a part of a picture | `blocks[hero].image.src`, `blocks[hero].image.alt` |
| an entry's own value, on its own page | `title` |
| an entry's value where it is listed | `entry:0193a5c3-…:title` |
| another page's block | `page:0193a5c2-…:blocks[hero].title` |
| the shared text | `shared:blocks[contacts].phone` |
| a module's setting | `module:bookings:hours[mon].opens` |
## `schema.json` — the schema
The site's declaration of what its content is made of:
[the schema format](catalogue.md). On the scaffold,
`npx @jtakeit/astro schema` writes it from `src/content/blocks.ts`, which says
`CONTRACT = 3`. On another generator you write it by hand or with your own
tool. The platform reads it and never writes it.
## `pages/.json` — a page
A page at its address: `/` is `pages/index.json`, `/prices` is
`pages/prices.json`, and `/team/anna` is `pages/team/anna.json`. The keys
come in this order:
```json
{
"id": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"path": "/prices",
"name": "Preise",
"seo": { "description": "Was ein Termin bei uns kostet.", "title": "Preise" },
"blocks": [
{
"_key": "hero",
"type": "hero",
"v": 1,
"image": { "alt": "Der Salon am Morgen", "focus": "50% 30%", "src": "media/2f0c…/a1b2c3d4.jpg" },
"title": "Preise"
},
{
"_key": "list",
"type": "priced_list",
"v": 1,
"items": [
{ "_key": "r7k2", "price": { "from": true, "minor": 4500 }, "title": "Haarschnitt" }
]
}
]
}
```
- **`id`** is the page's own and never changes. An import knows a file by
it, so a file moved or renamed in git is the same page at its new address,
with its history. When the version at the new address goes live, the
platform sends the old address on to it (301), so no redirect of your own
is needed. A new file may carry a fresh UUID; `jtk schema` mints one where
there is none.
- **`path`** is the address, and it agrees with the file's place.
- **`name`** is what the panel calls the page — *Preise*, *Team*,
*Kontakt* — in the site's own language. It is required, and a page without
one is refused. Visitors never see it, and the owner may rename it.
- **`seo`** holds the fields the schema's `page_seo` declares. Leave it out
for none.
- **`blocks`** are the page in order. Each block carries its `_key`, its
`type`, its type's `v`, `view` if its type has views, and then its fields'
values. A block at an older `v` is brought up by its type's `upcast` steps
when it is read, and the next save writes the current one —
[upcasters](../guides/upcasters.md).
A block may also carry `_orphans`: the values of fields the schema no longer
declares, kept so that a field renamed or removed in the schema loses
nothing. A page draws nothing from it. Leave it where it is, and delete a key
from it only to drop that value on purpose.
## `entries//.json` — an entry
An entry of a collection: its directory is its collection and its file name
is its slug. Its address is the collection's `route` with the slug in it, so
`/services/manicure` for `{"detail": "/services/{slug}"}`. An entry of a
collection with `route: "none"` has no page and no address. It is shown
where `shown_on` says, `/prices#manicure`, and read by the diary.
```json
{
"id": "0193a5c3-0a11-7d02-9f3c-1e2d3c4b5a71",
"collection": "services",
"slug": "manicure",
"rank": "a0",
"visible": true,
"fields": {
"costs": { "minor": 4500 },
"takes": 60,
"title": "Manicure"
}
}
```
The keys come in this order: `id`, `collection`, `slug`, `rank`, `visible`,
`show_at`, `hide_at`, `seo`, `fields` and `blocks`.
- **`fields`** holds the entry's own values, the fields of its collection's
type. They are annotated on its own page by their keys alone (`title`), and
wherever the entry is listed as `entry::title`. Because the values sit
under `fields`, a field may take any name, `collection` and `slug`
included.
- **`blocks`** is the entry's body, of the block types the collection's
`blocks` allows: a post's paragraphs and pictures. Leave it out for an
entry with none.
- **`rank`** is the entry's place in a collection ordered by hand, which is
the default: a short key compared as bytes (`a0` < `a0V` < `a1`). The
owner's moves in the panel write it. Read it and do not renumber it; an
entry without one comes after the ranked ones. A collection ordered by a
field has no `rank`.
- **`visible`** is always written: whether the owner shows the entry. An
entry the owner takes off the site or puts back in the panel is built as
they said from the next build on, and the next save writes the same
`visible` into the file. An entry with a page of its own that the owner
hides or deletes in the panel may send its address somewhere — its listing
by default — and the platform redirects it, as it does an address an entry
moved from; the owner sees and changes these in the panel
([the panel](../guides/the-panel.md#a-collections-entries)). Write no
redirect of your own for them.
- **`show_at`** and **`hide_at`** are moments in RFC 3339 and UTC —
`"2026-12-01T00:00:00Z"` — for an entry meant to appear later or to go on a
date. Outside its window the entry is treated as hidden: it is off the
listing, the feed, the sitemap and the diary, and the edge answers a
visitor 404 at its address while the people editing the site still see it.
The platform builds the saved commit a few minutes ahead of the moment and
points the site at it when the moment comes. A `hide_at` not after the
`show_at` is refused. On a collection whose entries are over by their date
(`ends_by`, [the schema](catalogue.md#an-end-by-date)) write the date, never
a moment: the platform works out when each is over, and with `then: hide`
its `hide_at` too. Never compare the date with today in the template — read
`ended`.
- **`seo`** is only for an entry with a page of its own, and it holds the
same fields as a page's.
A `body` field is markdown inside the JSON, never a `.md` file. Entries were
markdown with frontmatter once, and an import refuses that shape by name.
An entry of a collection a module books — a service, a master, a car — is in
every language, always ([translations](translations.md#what-is-booked-is-in-every-language)).
## `shared.json` — the text on every page
One document, with no `id` and no address: the blocks of the types the
schema's `shared` lists, usually one `contacts` block whose fields say their
`role`. The structured data a search engine reads is built from those roles.
A shared field is annotated wherever it is drawn as
`shared:blocks[contacts].phone`.
```json
{
"blocks": [
{
"_key": "contacts",
"type": "contacts",
"v": 1,
"city": "Winterthur",
"email": "praxis@example.ch",
"name": "Orthopädie Bischofsberg",
"phone": "+41 52 350 91 25",
"postal_code": "8400",
"street": "St. Georgenstrasse 6"
}
]
}
```
## `modules/.json` — a module's settings
The module's own document: `v`, the version of its settings, and `settings`,
whose keys the [modules reference](modules.md) lists. Every row of a list in
it has its `_key`. Seed it in the commit. `npx @jtakeit/astro schema` writes
an empty one when the schema turns the module on. `import_branch` reads it
into the diary, so the preview takes bookings before anybody opens the panel.
The owner changes it under the diary afterwards, and the next save writes it
back.
```json
{
"v": 1,
"settings": {
"cancel_until": 1440,
"closed": [
{ "_key": "xmas", "from": "2026-12-24", "until": "2027-01-03" }
],
"confirm": "auto",
"hold": 1440,
"horizon": 60,
"hours": [
{ "_key": "mon", "closes": 1080, "day": "monday", "opens": 540 },
{ "_key": "tue", "closes": 1080, "day": "tuesday", "opens": 540 },
{ "_key": "fri", "closes": 1020, "day": "friday", "opens": 540 }
],
"lead": 120,
"page": "/book",
"party": 1,
"payment": "no",
"slot_every": 30,
"zone": "Europe/Zurich"
}
}
```
Times of day are minutes from midnight (`540` is 09:00), durations are whole
minutes, and money is `{"minor": …}`. A closing time before the opening one
is after midnight, so a bar's Friday of 18:00–01:00 is one row. `deposit` is
a share of the price, 1–100, and belongs only beside `"payment": "deposit"`.
A zero is refused, so leave it out when nothing is paid up front. Anything
beside `v` and `settings`, or a value a setting's kind refuses, is refused
with [`JTK_E_DOCUMENT_INVALID`](errors.md#jtk_e_document_invalid). CI judges
this example with the same judge `import_branch` applies, so it cannot go
stale.
## `..json` — a translation
A page, an entry, the shared text or a module's settings in another of the
site's languages is a file beside its original: `pages/prices.en.json`,
`entries/services/manicure.en.json`, `shared.en.json`. It holds only the
words, named by the original's keys. A value that is the same in every
language is never in it. [Translations](translations.md) has the file, which
values belong in it, and how the platform tells what is missing and what is
outdated.
## `site.json` — the platform's file
The platform writes it on every save: the site's `id`, its `slug`, where the
owner's uploads are served from, and its currency. Do not seed `id`. An
import reads back only `currency`, and only while the site has none, as
`create_site` takes it. Once the site has a currency, a person changes it in
the panel (The site → The business). An import or a `validate_schema` that
brings another currency is refused with
[`JTK_E_CURRENCY_SET`](errors.md#jtk_e_currency_set). The business's
name, address and phone are not here. They are content, in `shared.json`.
```json
{
"id": "05d84518-b91f-44be-85a4-e2cb1ed11a13",
"slug": "orthopaedie-bischofsberg",
"media_base": "https://media.jtakeit.com/",
"currency": "CHF"
}
```
## `design.json`, and `dist/_meta.json`
`design.json` is the template's own file, not the contract's: the editor's
chrome (the field, the ground, the accent). The scaffold ships an empty one
that the panel fills.
`dist/_meta.json` is written by the site's build, not committed under `jtk/`.
It says `redirects` (`[{"from": "/old", "to": "/new", "status": 301}]`),
`immutable` (the directories whose files are named by their contents) and
`cache` (`[{"prefix": "/clips/", "maxAge": 86400}]`), and nothing else. Which
entries a visitor may not see is the platform's to say, so contract 3 has no
`drafts`. Anything else is refused with
[`JTK_E_META_INVALID`](errors.md#jtk_e_meta_invalid).
## Contract 2, the older contract
A site made before contract 3, and not yet moved, keeps these files. The
platform's team moves such a site with `jtk upgrade contract-3`, in one
commit. Never start a site in them. A tree that holds both `jtk/schema.json`
and `jtk/catalogue.json` is refused.
```
jtk/
catalogue.json the schema, "contract": 2 — written by `jtk catalogue`
content/index.json a page, {id, path, name, seo, blocks}
content/de/prices.json a page in another language: a full copy at /de/prices
content/services/manicure.json an entry under its collection's prefix
shared.json, shared.de.json the text on every page
bookings.json the diary's settings, one bookings_config block
site.json the platform's, with the business's facts under `business`
```
On contract 2, an entry is `{path, collection, visible, seo, blocks}`, and
its own values are the fields of `blocks[0]`. A file under a collection's
prefix without `collection` is refused with
[`JTK_E_ENTRY_NO_COLLECTION`](errors.md#jtk_e_entry_no_collection). Values
take contract 2's shapes: a price as a bare number of minor units, a picture
as its key with its description in a sibling `_alt` field, and a
reference as a slug. A place is named by position, `blocks[0].title`.
### `bookings.json`, contract 2
One block of type `bookings_config`, whose fields are the same settings, in
the shape a save writes. Anything else is refused with
[`JTK_E_MODULE_FILE_INVALID`](errors.md#jtk_e_module_file_invalid).
```json
{
"blocks": [
{
"type": "bookings_config",
"v": 1,
"zone": "Europe/Zurich",
"slot_every": 30,
"confirm": "auto",
"payment": "no",
"hours": [
{ "day": "monday", "opens": 540, "closes": 1080 }
]
}
]
}
```
---
# Translations, key by key
A site in several languages keeps each document once, in its own language
(the **original**). Beside it sits a **translation** for each other language,
and a translation holds only the words. A photograph, a price or a date is
the original's in every language, so changing it once changes it everywhere.
This is contract 3. On the older contract 2, each language was a full copy of
every document ([below](#contract-2-the-older-contract)).
This page is the format: which values a translation holds, how they are
named, what a record says, and what is refused. How to lay a site out in
several languages and work on it, and when to add a language at all (only
when the brief names one), is [the guide](../guides/languages.md).
## Declaring the languages
The schema says them: `locale`, required, is the site's own language, and
`locales` are the others ([the schema](catalogue.md)). On the scaffold they
are `LOCALE` and `LOCALES` in `src/content/blocks.ts`.
`npx @jtakeit/astro create --locale de-CH --locales en` lays out a
translation beside every original. It also writes the words that are not
content — the form's messages, the pager — in `src/copy/.ts`.
A language is spelt in canonical BCP 47, `de-CH`, in the schema, in file
names and in data. An address carries its lowercase form, with the language
in front: `/preise` in the site's own language, `/en/preise` and
`/fr-ch/preise` in the others. A collection's route may give its words per
language, `{"de": "/werke/{slug}", "en": "/works/{slug}"}`, and the language's
prefix still goes in front: `/en/works/oak`. An entry's translation may give
the entry a `slug` of its own.
## The file
A translation is `..json` beside its original:
| original | its English |
| --- | --- |
| `jtk/pages/index.json` | `jtk/pages/index.en.json` |
| `jtk/pages/preise.json` | `jtk/pages/preise.en.json` |
| `jtk/entries/works/eiche.json` | `jtk/entries/works/eiche.en.json` |
| `jtk/shared.json` | `jtk/shared.en.json` |
| `jtk/modules/.json` | `jtk/modules/.en.json`, only where the module's settings have words — the bookings' have none |
Its keys come in this order: `of`, `locale`, `name` or `slug`, `visible`,
`seo`, `fields`, `blocks`, `translated`.
- **`of`** is the original's `id`. The shared text and a module's settings
have no id and carry no `of`, because the file beside them names them.
- **`locale`** is the translation's language, and it is required. It is one
of the schema's `locales`. There is one translation of a document per
language.
- **What a page's translation holds:** `name`, `seo`, and the words of its
blocks, each block named by the original's `_key`, with no `type` and no
`v`. A page's blocks are the developer's structure, so the original has
them and the translation has only their words.
- **What an entry's translation holds:** `slug`, `seo`, the words of its
`fields`, its body `blocks` whole, and `visible: false` to hold the entry
back in that language.
- **What the shared text's translation holds:** the words of its blocks, by
`_key`.
A page, from the platform's corpus (`backend/api/sites/testdata/overlays/page-words-laid-by-key.json`).
The original, `jtk/pages/preise.json`, has a hero with a title, a lead, a
photograph and a link, and a price list of two rows. Its English is this:
```json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"name": "Prices",
"blocks": [
{ "_key": "hero", "title": "Our prices", "image": { "alt": "The salon" } }
]
}
```
Served in English, the hero says «Our prices» over the original's
photograph, with the same file and focus, and the English `alt`. Everything
this file leaves out is the original's German. The lead, the list's title and
its rows are listed as `fromBase`, so the page gives them `lang="de-CH"`.
A picture's words are the translation's in its language, the original's
where it gives none, and — where the original's field says none either — the
words its file has in the site's media library, which a picture placed from
the library starts from ([the panel](../guides/the-panel.md#the-media-library)).
The file's words are written into the original's value when the picture is
placed, and given anew to every place still saying them when they change; a
translation's words are never touched by them.
An entry (`entry-words.json`), whose original `jtk/entries/works/eiche.json`
has a title, an excerpt, a date, a price, a cover, a gallery of two pictures
(`p1`, `p2`) and a body:
```json
{
"of": "0193a5c3-1b2a-7e44-8a10-6c2f9d3e4b55",
"locale": "en",
"slug": "oak",
"seo": { "title": "Oak" },
"fields": {
"title": "Oak",
"cover": { "alt": "The oak door" },
"pictures": [ { "_key": "p2", "alt": "The handle" } ]
}
}
```
In English the entry is at its own slug, `/en/works/oak`. Its date, price and
pictures are the original's, with the English words laid over them by key.
What nobody translated stays in the original's words and is said as such:
`fields.excerpt`, `fields.pictures[p1].alt` and `blocks`, the body.
## Which values are per language
The kind decides, by one rule that the import, the save, the build, the
kit's door and the counts all share. A field may say otherwise with
`localized` ([field kinds](field-kinds.md#at-a-glance) has the column):
| a field of the kind | in a translation |
| --- | --- |
| `text`, `textarea`, `richtext_lite`, `markdown` | its whole value |
| `media`, one picture | its `alt`; the file, the focus and the poster are the original's |
| `media`, a gallery | each picture's `alt`, by the picture's `_key`; the pictures and their order are the original's |
| `list` | the words in its rows, by each row's `_key`; the rows and their order are the original's |
| `url` | nothing: the original's link |
| `number`, `money`, `duration`, `time_of_day`, `date`, `bool`, `select`, `ref`, `tel`, `email`, `sku`, `picks` | nothing: one value in every language |
- **`localized: true`** on a picture, a gallery, a link or a list makes the
whole value per language. Use it for a photograph with words on it, a link
to a page in that language, or a list each language has its own of.
- **`localized: false`** on a text makes it one value: a name nobody
translates, a street, a postcode.
- **`localized` on any other kind** is refused with
[`JTK_E_ATTRIBUTE_INVALID`](errors.md#jtk_e_attribute_invalid).
- **An entry's body (`blocks`) is whole per language.** A translation with
`blocks` of its own replaces the original's, so a German post may have a
paragraph the English one has not. A translation without `blocks` shows
the original's.
- **A page's `name`, the text fields of `seo`, and an entry's `slug`** are
per language. A slug left as the original's is never counted as
untranslated.
A value that is the same in every language, written into a translation, is
refused with [`JTK_E_TRANSLATION_SHARED`](errors.md#jtk_e_translation_shared).
This, from `refused-shared-value-price.json`, sets a price for English
alone:
```json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"blocks": [
{ "_key": "list", "items": [ { "_key": "r1", "title": "Haircut", "price": { "minor": 5000 } } ] }
]
}
```
Change the price in the original instead, and every language has it.
## Paths
A value's place in a translation is named by keys, never by position. The
same names key `translated`, the counts `get_site` gives, and `fromBase`:
| path | the value |
| --- | --- |
| `name` | a page's name |
| `slug` | an entry's slug in the language |
| `seo.title` | a field of `seo` |
| `blocks[hero].title` | a field of a page's block |
| `blocks[hero].image.alt` | a picture's words |
| `blocks[list].items[r7k2].title` | a field of a row |
| `fields.title` | an entry's own value |
| `fields.pictures[g1].alt` | a gallery picture's words, in an entry |
| `blocks` | an entry's body, one value whole per language |
| `settings.` | a word of a module's settings |
## `translated`: what each value was made from
A translation may say, for each value it gives, what that value was
translated from: a record under the value's path, with exactly three keys.
- **`from`** is the first eight hex digits of the SHA-256 of the original
value's canonical JSON. Canonical means every object's keys in byte order
at every depth, no spaces, and strings escaped as `JSON.stringify` escapes
them. `"Hallo"` is `09d941a5`:
`printf '%s' '"Hallo"' | shasum -a 256 | cut -c1-8`.
- **`by`** is `person`, `agent` or `machine`. An agent writes its own words
and never `machine`: the machine (DeepL) is a panel action for a person,
off on a deployment without a key, and no tool reaches it
([machine translation](../guides/the-panel.md#machine-translation)).
- **`at`** is a moment in RFC 3339.
A record that is anything else is refused with
[`JTK_E_TRANSLATION_RECORD`](errors.md#jtk_e_translation_record).
From `outdated-by-digest.json`: the original home page's hero says
`"title": "Hallo"` and `"lead": "Seit 1998 an der Langstrasse"`, and its
English is this:
```json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"name": "Home",
"blocks": [ { "_key": "hero", "title": "Hello", "lead": "Since 1998" } ],
"translated": {
"blocks[hero].title": { "from": "09d941a5", "by": "agent", "at": "2026-11-10T09:00:00Z" },
"blocks[hero].lead": { "from": "64cba83f", "by": "person", "at": "2026-11-10T09:00:00Z" }
}
}
```
`09d941a5` is the digest of `"Hallo"`, the title as it stands, so the title
is current. `64cba83f` is the digest of `"Seit 1998"`, the lead before it
grew, so the lead is outdated.
**Leave `translated` out, which is the ordinary case.** The import records
each value the translation gives as made from the original as it stands, by
the agent. It also keeps the record it wrote for a value you did not change,
which is how an outdated value stays outdated until it is translated again.
Write a record yourself only to say who made a value, and then use the digest
the platform wrote.
**A record is never made from nothing.** A value the translation gives where
the original has none, such as SEO on a page whose original has no SEO, is
the translation's own. It has no record, and it is neither missing nor
outdated. A record whose `from` is empty counts as no record: nothing refuses
it, and it is never written back. If the original later gains a value, the
next import records the translation's value as made from it.
## Where a translation stands
Each per-language value of a document is in one of these states:
| state | means | the site shows |
| --- | --- | --- |
| **missing** | nobody translated it | the original's words, marked with the original's `lang` — or, where the collection says `untranslated: "hide"`, no entry in that language at all |
| **current** | made from the original as it is now | the translation |
| **outdated** | the original changed since: `from` is not its digest | the older translation, which still beats the original's language |
| **machine** | a person had the machine draft it in the panel (`by: machine`), and nobody has pressed *Checked* yet | the translation, once a version with it is published; the panel marks it *machine, unchecked* |
`get_site` adds them up per language — *fr-CH: 6 to translate, 2 outdated* —
with each document's translation file and the paths, so you can do the work
from the answer. The count is the draft's, which your checkout has after a
save. A picture's `alt` counts; a slug left as the original's does not.
## A language without a translation
What a language with no translation of an entry does is its collection's
`untranslated`:
- **`base`**, the default: the entry is there in the original's words, and
the kit's door gives them the original's `lang`.
- **`hide`**: the entry is hidden in that language. It is built for the
panel's preview, listed nowhere and in no sitemap. A translation with
`visible: false` holds one entry back the same way.
A page and the shared text always fall back to the original's words.
`hreflang` and the sitemap name a language only where a translation exists.
## What is booked is in every language
An entry of a collection a module names in one of its roles — the bookings'
services, resources and classes — is booked by the diary in any language's
form, and the diary reads the original. So such an entry is never missing
from a language. Where nobody translated it, it shows the original's words.
- The collection may not say `untranslated: "hide"`, which is refused with
[`JTK_E_ATTRIBUTE_INVALID`](errors.md#jtk_e_attribute_invalid).
- A translation of its entry may not say `visible: false`, which is refused
with [`JTK_E_DOCUMENT_INVALID`](errors.md#jtk_e_document_invalid). This,
from `booked-entry-held-back-refused.json`, tries to hold a master back in
English:
```json
{
"of": "0193a5c3-0a11-7d02-9f3c-1e2d3c4b5a72",
"locale": "en",
"visible": false,
"fields": { "bio": "Cutting since 2010." }
}
```
The panel offers no switch for it either, and the site serves such an entry
in every language regardless. The booking form names a service and a master
by the original's slug, which the diary books by.
## What is refused, and what is advice
`validate_schema` judges translations before the push: by site and ref, or
with the tree sent as text beside the schema. `npx @jtakeit/astro schema`
does the same, and so does the import. The build stops on a translation the
import would refuse.
| code | when |
| --- | --- |
| [`JTK_E_TRANSLATION_SHARED`](errors.md#jtk_e_translation_shared) | a translation holds a value that is the same in every language |
| [`JTK_E_TRANSLATION_RECORD`](errors.md#jtk_e_translation_record) | a record in `translated` is not `{from, by, at}` as above |
| [`JTK_E_DOCUMENT_INVALID`](errors.md#jtk_e_document_invalid) | a key a translation has not got, a block, row or picture without its `_key`, a `type` on a page's block, a language the schema does not list, two translations of one document in one language, an address two entries would share in a language, or `visible: false` on an entry a module books |
| [`JTK_E_ATTRIBUTE_INVALID`](errors.md#jtk_e_attribute_invalid) | `localized` on a kind with no words, `untranslated` that is neither `base` nor `hide`, or `hide` on a collection a module books |
| [`JTK_W_TRANSLATION_ORPHAN`](errors.md#jtk_w_translation_orphan) | advice: words for a block, a row or a picture whose `_key` the original has not got |
| [`JTK_E_MACHINE_OFF`](errors.md#jtk_e_machine_off), [`JTK_E_MACHINE_ALLOWANCE`](errors.md#jtk_e_machine_allowance) | the panel's machine translation, refused to a person: no DeepL key here, or the site's allowance spent. Never an agent's: translate in the files |
An orphan's words are shown nowhere, and the next save leaves them out of the
file, while the history keeps them. Here (`unknown-key-is-advice.json`), the
original has no row `gone` and no block `old`, so both are advised against
and the row `r2` is translated:
```json
{
"of": "0193a5c2-7f4e-7c1a-9b2e-5d1f0c3a8e21",
"locale": "en",
"name": "Prices",
"blocks": [
{ "_key": "list", "title": "Cuts", "items": [ { "_key": "gone", "title": "Perm" }, { "_key": "r2", "title": "Colour" } ] },
{ "_key": "old", "title": "A block removed" }
]
}
```
## Contract 2, the older contract
A site not yet moved keeps a full copy of every document per language: a page
at `jtk/content//.json`, saying `"locale": ""`, at the
same address with the language in front. Nothing ties a photograph or a
price across the copies. `jtk upgrade contract-3` turns each copy into a
translation beside its original. A value that differs between copies, such as
two photographs or two prices, stops the move and is listed for a person to
answer: `--take-base` keeps the original's, and `localized: true` on the
field keeps each language's own.
---
# A block type's versions, and upcasters
A block type in `jtk/schema.json` carries a version, `v`, and every block a
document holds says the `v` it was written at. While a type stays as it is,
both say `1` and nothing happens. When a type changes in a way the content
already written can feel — a field renamed, a value of a choice renamed, a
field gone — you raise `v` and say, in the type's `upcast`, how a block of the
older version becomes the newer one. The platform does the rest: it brings
every block written at an older version up when it reads it, and the next
save writes the current one into your files.
Contract 3 only. A contract-2 site's `v` stays `1`.
## What a step is
```json
{
"type": "hero",
"v": 3,
"label": "Hero",
"fields": [
{ "key": "title", "label": "Titel", "kind": "text", "client_editable": true },
{ "key": "align", "label": "Ausrichtung", "kind": "select",
"options": [{ "value": "left" }, { "value": "center" }] },
{ "key": "tone", "label": "Ton", "kind": "select",
"options": [{ "value": "light" }, { "value": "dark" }] },
{ "key": "items", "label": "Fragen", "kind": "list", "of": [
{ "key": "question", "label": "Frage", "kind": "text" },
{ "key": "answer", "label": "Antwort", "kind": "text" }
] }
],
"upcast": [
{ "from": 1, "rename": { "heading": "title" },
"values": { "align": { "centre": "center" } } },
{ "from": 2, "drop": ["subtitle"], "set": { "tone": "light" },
"rows": { "items": { "rename": { "q": "question" } } } }
]
}
```
Each step makes a block of version `from` a block of version `from + 1`. A
block written at version 1 goes through both steps above, in order; one
written at 2 through the second only. A step's changes are made in this
order:
| change | what it does |
| --- | --- |
| `rename` | `{"old": "new"}` — the value moves to the new name. Where the new name already says something, the old value goes to `_orphans` instead. |
| `rows` | `{"list": {…}}` — the same changes inside every row of a list, and once more for a list inside a row. Each row keeps its `_key`. |
| `values` | `{"field": {"old": "new"}}` — a choice's value renamed, in a single value or in a list of them. Renaming an option's value is a migration, and this is it. |
| `drop` | `["field"]` — the field is gone. Its value goes to `_orphans`, which nothing serves and nothing loses. |
| `set` | `{"field": value}` — a new field's first value, written only where the block has none. |
There is no other change, and no code. The schema is your file, but the
platform runs nothing from it.
## The rules the judge holds a step to
`validate_schema` refuses a step with `JTK_E_UPCAST_INVALID` when:
- its `from` is not an older version of the type (1 up to `v - 1`), or two
steps share one;
- it names something that is not a field's name, renames a field to itself,
or renames two fields into one;
- it is the **last** step — the one from `v - 1` — and writes, renames into,
changes the rows of, or sets a field the type does not declare now, or
drops one it still declares. An earlier step's names belong to a version
nobody declares any more, and only their spelling is held.
**Every version content may still be at needs its step.** A version that
changed nothing stored content can feel — a field added, a bound widened —
still says it, empty: `{"from": 2}`. A block at a version with no step is
refused, never guessed at: `JTK_E_BLOCK_BEHIND`, naming the file, the block,
its `v` and the type's. A block whose `v` is newer than its type's is refused
the same way; that is a schema not pushed with its content.
## Where it happens
| when | what is brought up |
| --- | --- |
| an import (`import_branch`, a push, the panel's sync) | every block of every page, entry, the shared text and a module's settings, as the branch's files are read; then every stored copy the branch did not bring — the draft, the version and the live copy — so the three stages compare one shape with one shape |
| any write in the panel | the document being written, so a version restored from before the change is written at the current version |
| a save | the files it writes say the current `v` |
So the order of work is: change the type, raise `v`, add the step, push. You
do not have to rewrite the content files by hand. If you do, the steps leave
what is already in the new shape as it is — a rename moves a value only where
the new name says nothing, `set` writes only where nothing is, a value is
renamed only where it is the old one — so a tree half rewritten by hand and
half not is brought up all the same.
**An entry's own values.** An entry's `fields` carry no `v` of their own. They
are read as written against the schema the platform held when they were
written: when a push raises the version of a collection's type, the import
takes that collection's entries through the steps from the version the
platform had, and the next save writes them in the new shape.
**A translation** is not brought up: it holds only words, named by the
original's keys, and has no type of its own. When a step renames a field that
has words in other languages, rename it in the translation files
(`..json`) in the same commit; the import refuses a translation
that names a field the schema does not declare, and says which file.
## The template
Your template reads the content through the kit's door, and sees only the
current version: the build reads the files a save wrote. Until the first save
after the push, a build of the pushed commit reads the files as you pushed
them — so change the template and the content in one push, or push and then
`commit_and_build`, which saves before it builds.
---
# 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.
| stage | what it is | where it lives |
| --- | --- | --- |
| **draft** | what the client has typed. Every keystroke that survives a field blur | our database |
| **version** | what somebody deliberately kept, to come back to | **the site's git repository** |
| **live** | what the site actually serves | **the 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: at rev ` — 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/.json` for pages, `jtk/entries//.json`
for collection entries, each language's words in a translation beside
its original (`..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](../reference/jtk-files.md) 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 `_key`s; `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`](../reference/errors.md#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-panel.md#the-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`](../reference/errors.md#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`](../reference/errors.md#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.
---
# Working on a site locally
Change a template on your machine and see it in the panel — with the client's
real text in it — without pushing, building or importing.
---
## What this is, and the part everybody skips
Pushing a change feeds four things: the built artifact the preview reads, the
schema the panel draws forms from, **the schema the server validates every
edit against**, and the content that becomes the draft.
The third one is why pointing an iframe at a dev server is only half a feature.
You would see your new block immediately and be unable to type a word into it,
because the server checks every field against the schema pinned to the last
build, and that schema has no such field.
A **dev session** answers both halves: the page comes from your machine, and the
server accepts the shape your working copy declares.
## What a session is
A copy of the site — its draft as it stands right now, so you are working
against the client's real text rather than lorem ipsum — that lives for as long
as you are using it and is then thrown away.
- It is **not** the client's site. Nothing you do in it is visible to them.
- It **cannot publish.** A session shares the site's repository, and publishing
from one would push your working copy over what the client has been editing.
- It **expires** if nobody touches it for two hours. Your dev server holds it
open by saying hello; a laptop closed on Friday is not still holding one on
Monday.
- The way anything leaves it is a **commit** you make (below).
## Opening one
Your agent does this. In its own words: *open a dev session on natali-nails,
serving from http://localhost:4321*.
A session is opened **on a site**, because what it frames your page with is
that site's real text. For a template that has no site yet — a new client, a
fixture, a scaffold you are trying out — make one: `create_site` is a row, a
site that is not live costs nothing and draws on no plan, and it can be archived when the
template is done. Do not borrow another client's site as the frame; the text
in it is theirs.
The address is not free-form. It is `http://localhost:` or
`http://127.0.0.1:` and nothing else — whatever the panel is told to frame
is a page embedded in a signed-in browser, so the set is exactly what the
feature is for.
Leave the address out and the session shows a candidate build instead: slower by
a build, and the only option if your browser will not frame a local address.
## What your dev server has to do
One script tag, in dev only:
```html
```
That is the editor: it is what makes a heading tappable in the panel and what
carries the text you type into the page. It is the same file the hosted preview
gets — served from one place on purpose, because the page and the panel agree a
version number between them and two copies of a protocol are two versions of it.
The host is the preview's, and it has to be: the file is served by the edge
Worker, which holds `preview.jtakeit.com` (`preview.stg.jtakeit.com` on staging)
and no route on the bare domain.
A tag pointing anywhere else fails the quietest way this feature can fail —
the page renders, the panel frames it, and nothing is editable, with no error
anywhere to say why.
Nothing else changes. Your components already carry `data-jtk-path`; that is
what the annotation lint checks on every build.
## The page says where it is
The session's answer carries a `watch_key`, shown once. In the working tree:
```
npx jtkit session # --api https://api.stg.jtakeit.com on staging
```
It writes `jtk/session.json` (ignored by git), and from then on every page
the dev server serves carries a small card, bottom right: where the site is
— the brief, the layout, the writing, read off the files — and the
platform's half through the session: the judge's word, the repository, the
build, the preview, and the steps of the panel's *Setting up* the developer
can take meanwhile, with the way there. The same seven phases the panel's
«What the agent is doing» shows; the card is in the dev server only and
never in a build. The key reads this one session's progress and nothing
else, and dies with the session. `jtkit progress` prints the card's list in
the terminal; run it before saying a phase is done.
## Telling the session what the site is made of
When you change the schema, `jtk/schema.json` (`jtk/catalogue.json` on a
contract-2 site), the session has to be told, or the panel draws yesterday's
forms and refuses today's fields. Under `astro dev` the scaffold writes the
schema again on every save of `src/content/blocks.ts`; run
`npx @jtakeit/astro schema` before a commit, which also mints the `id`s and
`_key`s the files lack.
Your agent sends the file with `send_dev_schema`. The session then draws its forms from **your working
copy** — and the client's site keeps drawing forms from the template it is
actually built from, because a working copy's schema only ever reaches a
session. There is no state to clean up and nothing to switch back.
The file goes through the same validator the repository's own copy does, so a
schema that would fail a build fails here, in front of you, in seconds — and
it is the same judge `validate_schema` is, with the same findings, so under
a session there is no reason to validate first and send second. One paste.
A session takes the file of the contract its site is written in. Before the
site's first push it has none, and the session takes whichever the file says
— `jtk/schema.json` for contract 3. When an import moves the site to contract
3, its first or a later one, every open session follows it: the site's schema
and its pages are copied in again, and what was typed into the session before
the move goes with the old shape. Keep the session; there is no need to
close it and open another.
## A shop on localhost
A session frames your page, and the page's shop is not the session's: `astro dev`
answers the shop's four addresses (`/api/stock`, `/api/shipping`,
`/api/checkout`, `/api/order`) from **the site's own files** — the scaffold's
`jtakeit-meta.mjs` mounts `devShop` beside the diary's stand-in, and reads the
products and `jtk/modules/shop.json` fresh on every request. A storefront can be
walked end to end while it is written, the payment on a page of the dev server's
own that charges nothing. It is a stand-in: every variant on sale is in stock
with no count, there is no VAT and no own currency, and nothing reaches Stripe or
the platform. The platform's twin of a session answers those four addresses
`404`; only the site itself or a preview takes an order, and `preflight` with
`try_order` is the test of that one ([the shop on the
site](shop-on-the-site.md#on-localhost)).
## Seeing what the panel drew
A session is a site with its own id, and the reading tools work on it: ask
your agent to *read the content of the session* (`get_content` with the
session's id) and the answer is the pages, and per page the blocks and the
fields the panel draws forms for — which is how an agent that cannot see the
panel checks that the block it just declared is there, rather than inferring
it from the dev server's markup.
## Getting your work back out
Anything you type into a session's content lives in the session. To keep it, ask
your agent for the session's files: it writes them into your working copy at the
paths a publish would have used — `jtk/pages/.json`,
`jtk/entries//.json`, the translations beside them,
`jtk/shared.json`, `jtk/site.json` (`jtk/content/` on a contract-2 site) —
and you read the diff and commit.
That is deliberate rather than a limitation. The way out of the panel's database
and into a repository is a commit, everywhere in this product; a session is not
allowed a shortcut past the one place a person sees what they are about to
change before it changes.
## Closing one
Ask your agent to close it, or leave it and let it expire. Either way the copy
is deleted and the site is untouched — it never knew the session existed.
## When it does not work
**The panel shows an empty rectangle where the page should be.** Your browser is
refusing to embed a plain-http address in an https page. Chrome and Firefox
allow `localhost`; Safari is stricter. Either use one of the first two, or run
your dev server over https with a locally trusted certificate, or open the
session without an address and work against a candidate build.
**You can see the block and cannot type into it.** The session has not been told
about your schema yet. Ask your agent to send it.
**The panel says the session is gone.** It expired. Open another one — it takes
the client's draft as it stands now, which is what you wanted anyway.
---
# Every error code
Every refusal carries one of these. The set is closed, and a code is a promise
this page keeps: there is no failure that arrives without a name you can look up.
Two judges say them. The **schema** codes come from
`POST /v1/registry/validate` (`validate_schema`), from `npx @jtakeit/astro schema --judge`,
and from an import that reads a repository's schema. The **build** codes come
from the annotation lint inside the build container, and appear in a build log.
A code that came with contract 3 says so under it, and so does one only the
older contract 2 says — a site on `jtk/catalogue.json` and `jtk/content/`,
until it is moved; a new site never meets those.
The schema judge has a second voice: **advice**, with `JTK_W_` codes. A finding
there refuses nothing — the file is valid — and says what it is allowed to do and
would be wiser not to. `POST /v1/registry/validate` returns them under `advice`,
apart from the refusals, and only once nothing is refused. So has the build's
lint: what it advises is printed in the log and the build goes on.
## Reading the schema
What is wrong with the schema itself: `jtk/schema.json`, or on contract 2, the older contract, `jtk/catalogue.json`.
| code | means |
| --- | --- |
| [`JTK_E_CATALOGUE_UNREADABLE`](#jtk_e_catalogue_unreadable) | Contract 2's schema, `jtk/catalogue.json`, is not JSON, or carries a key that contract has no place for. Contract 3's `jtk/schema.json` says this as JTK_E_SCHEMA_UNREADABLE or JTK_E_SCHEMA_KEY_UNKNOWN. |
| [`JTK_E_CONTRACT_UNKNOWN`](#jtk_e_contract_unknown) | The schema names a contract number this service does not speak. |
| [`JTK_E_CATALOGUE_EMPTY`](#jtk_e_catalogue_empty) | Contract 2's schema, `jtk/catalogue.json`, declares no blocks, so it describes no site. Contract 3 says this as JTK_E_SCHEMA_EMPTY. |
| [`JTK_E_GENERATOR_INVALID`](#jtk_e_generator_invalid) | The `generator` string does not name a tool. |
| [`JTK_E_NAME_INVALID`](#jtk_e_name_invalid) | A block type, field key, view key or collection name is not spelled the way an identifier must be. |
| [`JTK_E_NAME_DUPLICATE`](#jtk_e_name_duplicate) | Two things in the same place are called the same thing. |
| [`JTK_E_LABEL_MISSING`](#jtk_e_label_missing) | A field, view or collection has no label. |
| [`JTK_E_TEXT_INVALID`](#jtk_e_text_invalid) | A label or hint is written both once and per language, names a language that is not one, is empty, or runs too long. |
| [`JTK_E_BLOCK_VERSION`](#jtk_e_block_version) | A block type has no version, or a version below one. |
| [`JTK_E_BLOCK_EMPTY`](#jtk_e_block_empty) | A block type declares no fields. |
| [`JTK_E_COLLECTS_UNKNOWN`](#jtk_e_collects_unknown) | A block says it collects something nothing knows about. |
| [`JTK_E_KIND_UNKNOWN`](#jtk_e_kind_unknown) | A field's kind is not one of the 19 — 17 on contract 2, which has neither `sku` nor `picks`. |
| [`JTK_E_BOUNDS_INVALID`](#jtk_e_bounds_invalid) | A `min` or `max` is negative, or the minimum is above the maximum. |
| [`JTK_E_SELECT_NO_OPTIONS`](#jtk_e_select_no_options) | A `select` field offers nothing to select. |
| [`JTK_E_LIST_INVALID`](#jtk_e_list_invalid) | A list nests lists deeper than its contract allows, declares no item fields, or `of` appears on a field that is not a list. |
| [`JTK_E_MEDIA_INVALID`](#jtk_e_media_invalid) | A media field's `accept`, `ratio` or `multiple` do not go together — or one of the three appears on a field that is not media. |
| [`JTK_E_BESIDE_INVALID`](#jtk_e_beside_invalid) | A field's `beside` names no field of the same block (or row), names the field itself, or names a field that is not on the page either — or the field carrying it is on the page. |
| [`JTK_E_TITLED_BY_INVALID`](#jtk_e_titled_by_invalid) | A field's `titled_by` names no field of the same block (or row), names the field itself, or names a field that is not a line of text. |
| [`JTK_E_VIEW_INVALID`](#jtk_e_view_invalid) | A block declares arrangements but has no gallery to arrange, sets its bounds in two places, or a view's own bounds do not make sense. |
| [`JTK_E_LOCALE_INVALID`](#jtk_e_locale_invalid) | A language is not a language, is declared twice, or the site's own language appears again among the others. |
| [`JTK_E_MODULE_UNKNOWN`](#jtk_e_module_unknown) | The schema turns on a module this service does not have. |
| [`JTK_E_MODULE_ROLE_INVALID`](#jtk_e_module_role_invalid) | A module is pointed at nothing, or at something that is not a collection of this schema. |
| [`JTK_E_MODULE_FILE_INVALID`](#jtk_e_module_file_invalid) | Contract 2 only, the older contract: its settings file `jtk/.json` is not a settings document — it is not JSON, it has no `blocks`, its one block is not the module's own config type, or a field holds what its kind refuses. |
| [`JTK_E_COLLECTION_INVALID`](#jtk_e_collection_invalid) | A collection's place, icon, entry type or `blocks` list is wrong — or, on contract 2, its prefix or pagination. |
| [`JTK_E_ENTRY_TYPE_INVALID`](#jtk_e_entry_type_invalid) | The block type a collection names cannot be used for entries. |
| [`JTK_E_ORDER_INVALID`](#jtk_e_order_invalid) | A collection is ordered by a field that will not order it. |
| [`JTK_E_SCHEMA_UNREADABLE`](#jtk_e_schema_unreadable) | `jtk/schema.json` is not JSON, or a value in it has the wrong shape — words where a number goes, a list where an object does. Nothing else in the file is read until it is. |
| [`JTK_E_SCHEMA_EMPTY`](#jtk_e_schema_empty) | The schema declares no block types. |
| [`JTK_E_SCHEMA_KEY_UNKNOWN`](#jtk_e_schema_key_unknown) | The schema says a key contract 3 does not have, at any depth: a typo, or a word of contract 2's that contract 3 replaced — `business_facts`, `deprecated`, a collection's `prefix` or `body`, `option_labels`, a view's `sample`. Every one is said at once, each at its place. |
| [`JTK_E_ROUTE_INVALID`](#jtk_e_route_invalid) | A collection says nowhere, or somewhere that cannot be, where its entries are: no `route`, a `detail` without `{slug}` or that is no address, a listing with a slug in it, `"none"` with no `shown_on`, a pattern for a language the site does not have, or two collections whose entries would share addresses. |
| [`JTK_E_REF_INVALID`](#jtk_e_ref_invalid) | A reference points nowhere, or where no reader follows it: a `ref` with no `to`, a collection named twice, an `on_delete` other than `restrict` and `nullify`, a ref written as contract 2 wrote it — or a group or a tree through a reference to several collections or several entries, which nothing groups by yet. |
| [`JTK_E_SHARED_INVALID`](#jtk_e_shared_invalid) | `shared` names a block type the schema does not declare, or names one twice; or a field says a `role` that is not one of the list, sits outside the shared text, or says a role another field says already. |
| [`JTK_E_ATTRIBUTE_INVALID`](#jtk_e_attribute_invalid) | A field says an attribute its kind does not take, or a value the attribute does not have: `localized` on a kind with no language, `integer` on anything but a number, `qualifiers` on anything but money or besides `from` and `on_request`, an `untranslated` that is neither `base` nor `hide`. |
| [`JTK_E_SKU_TAKEN`](#jtk_e_sku_taken) | Two variants on the site share a SKU, compared without regard to case, hidden products included. |
| [`JTK_E_PICKS_INVALID`](#jtk_e_picks_invalid) | A variant's `picks` do not name one value of each of its product's options, or two variants pick the same. |
| [`JTK_E_PRODUCT_INVALID`](#jtk_e_product_invalid) | A product is outside the shop's limits, or a customization lacks what its kind needs. |
| [`JTK_E_UPCAST_INVALID`](#jtk_e_upcast_invalid) | A block type's `upcast` says a step that cannot be one: `from` a version the type has not had (each step is from 1 up to one below the type's `v`), two steps from one version, a name that is not a field's, a rename of two fields into one, or a last step that writes, renames into or changes the rows of a field the type does not declare now — or drops one it still does. |
| [`JTK_E_PANEL_FORM_INVALID`](#jtk_e_panel_form_invalid) | An entry type's `form` — how the panel lays out its card and a new entry — cannot be drawn as written: it names a field the type does not declare, `body`, or one field twice; a row holds more than three fields, spans more than six columns, or shares what is left unevenly; a gallery, a list or a document shares a row; a paragraph, a gallery or a list stands in the aside; a widget is not one of its field's kind or does not fit it; a required field has no place (but for one a module's own card draws, which no form lays out); or `form` is on a block type that is no collection's `type`. The sentence says which, at its place. |
## Building the site
What is wrong between the schema, the content and the pages the build produced.
| code | means |
| --- | --- |
| [`JTK_E_UNANNOTATED_FIELD`](#jtk_e_unannotated_field) | A content field is on the page and carries no `data-jtk-path`. |
| [`JTK_E_PAGE_NOT_BUILT`](#jtk_e_page_not_built) | The content has a page and the build did not produce it — or a collection without pages of its own shows its entries on a page no build made: its `shown_on` page on contract 3, its prefix on contract 2. |
| [`JTK_E_ROBOTS_DISALLOW`](#jtk_e_robots_disallow) | The build ships a robots.txt that keeps every crawler out. |
| [`JTK_E_SITEMAP_EMPTY`](#jtk_e_sitemap_empty) | The build ships a sitemap with no pages, or pages on another host. |
| [`JTK_E_CANONICAL_ELSEWHERE`](#jtk_e_canonical_elsewhere) | The build says its canonical page is on another host. |
| [`JTK_E_NOINDEX`](#jtk_e_noindex) | The page tells search engines to go away. |
| [`JTK_E_SHARED_NOT_RENDERED`](#jtk_e_shared_not_rendered) | A shared field is rendered on no page at all. |
| [`JTK_E_ANNOTATION_UNKNOWN`](#jtk_e_annotation_unknown) | A `page:` annotation names a page this site has not got, or a field that page's document has not got. |
| [`JTK_E_CONTENT_VARIANT`](#jtk_e_content_variant) | The site's code fails to build, or loses an annotation, on content an owner can write: every optional field empty, or every one filled and long. |
| [`JTK_E_CATALOGUE_MISSING`](#jtk_e_catalogue_missing) | The repository has no schema: neither `jtk/schema.json` (contract 3) nor `jtk/catalogue.json` (contract 2, the older contract). |
| [`JTK_E_FORM_INCOMPLETE`](#jtk_e_form_incomplete) | A form posting to `/api/lead` is missing a control the enquiry's structure needs. |
| [`JTK_E_FORM_FIELD_UNDECLARED`](#jtk_e_form_field_undeclared) | A form posting to `/api/lead` has a control the schema does not declare. |
| [`JTK_E_FORM_UNDECLARED`](#jtk_e_form_undeclared) | A page has a form posting to `/api/lead` and no block on it says `collects: "enquiry"`. |
| [`JTK_E_UNNAMED`](#jtk_e_unnamed) | A page or an entry has no `id`, or a block, a row of a list or a gallery's picture has no `_key`, that an annotation can name — an id is a lowercase UUID, a key a lowercase letter and then lowercase letters, digits and hyphens. Nothing in it can be annotated, so the owner taps it and nothing opens. |
| [`JTK_E_META_INVALID`](#jtk_e_meta_invalid) | The build's `dist/_meta.json` says what the platform does not read: it is not a JSON object, it holds `drafts` — which contract 3 removed — or a key other than `redirects`, `immutable` and `cache`, or one of those in a shape the platform would pass over. |
## Refused while building
Not a fault in a file: what the runner would not do for the build while it ran — a host it may not reach. Printed into the build log by the runner, with the request and the list.
| code | means |
| --- | --- |
| [`JTK_E_BUILD_REACH`](#jtk_e_build_reach) | The build asked for a host it may not reach. A build runs with no network of its own: the repository on github.com, the npm and yarn registries, the platform's media host and Google Fonts are forwarded, and nothing else is — GET and HEAD, with POST only for the clone. |
## Refused once stored
Not a fault the lint can see: the build's files, compared with the build they would replace on a site with an address. The build fails, and a publish of it is refused, with the files named in the log.
| code | means |
| --- | --- |
| [`JTK_E_CACHED_FILE_CHANGED`](#jtk_e_cached_file_changed) | A name a public build let browsers keep — under `immutable` or a `cache` directory of `_meta.json` — has other contents in this build while it is still held. |
## Refused by the platform
Not a fault in a file — an operation that cannot be carried out in the state the site is in. These arrive as `details` on an API refusal, with the same code, meaning and remedy printed below.
| code | means |
| --- | --- |
| [`JTK_E_SLUG_TAKEN`](#jtk_e_slug_taken) | A site already answers to that slug. |
| [`JTK_E_BOOKING_FIELD_UNKNOWN`](#jtk_e_booking_field_unknown) | A booking page sent `/api/book` a field, or `/api/availability` a parameter, that the contract does not have — or one of the wrong shape, `"count": "4"` for `4`. Refused when it comes from somebody the site knows: the studio, its agent, a preview. From a stranger it is dropped, and the booking goes ahead without it. |
| [`JTK_E_SHOP_PROTOCOL`](#jtk_e_shop_protocol) | A shop page named a version of the shop protocol this platform does not answer — a page newer than the platform, or one so old its version has been retired. The answer says what the page said (`said`) and the versions the platform speaks (`supported`). |
| [`JTK_E_SHOP_FIELD_UNKNOWN`](#jtk_e_shop_field_unknown) | A shop page sent one of the shop protocol's addresses a field the contract does not have, at any depth of a cart — `coupon` at the top, `lines[0].colour` in a line — or one of the wrong shape, `"qty": "2"` for `2`. Refused when it comes from somebody the site knows: the studio, its agent, a preview. From a stranger it is dropped, and the cart is read without it. |
| [`JTK_E_ACCOUNT_PAUSED`](#jtk_e_account_paused) | The studio's account is paused by the platform: a report, a loop of builds, a scripted sign-up — something a person is looking at. Every request of its members and agents answers this; its sites answer 503 to visitors. Nothing is deleted. |
| [`JTK_E_DOCUMENTS_DUE`](#jtk_e_documents_due) | A new version of the terms, the data processing agreement or the privacy policy binds from a date that has passed, and it has not been accepted — by the person signed in, or, for an agent, by any owner or admin of its studio. Every call answers this until it is; nothing is lost meanwhile. |
| [`JTK_E_CROSS_ORIGIN`](#jtk_e_cross_origin) | A request that would change something was signed in with the panel's session cookie and came from a page that is not the panel — a demo, a site, another tab's script, a sandboxed frame. The cookie is sent by the browser on its own, so the API takes a change made with it only from the panel's origin. Nothing was changed. |
| [`JTK_E_OUT_OF_SYNC`](#jtk_e_out_of_sync) | The site's content has changed in its repository since the panel last read it, so publishing would delete work nobody has seen. |
| [`JTK_E_STUDIO_ONLY`](#jtk_e_studio_only) | A field the schema does not give the owner — `client_editable` not `true` on contract 3, `false` on contract 2 — was written by somebody who may change the site's words and not that field. The panel shows such a field read-only, with «the studio edits this one»; the server refuses the write as well, and its `details` name the `path`. |
| [`JTK_E_CONTENT_FILE_INVALID`](#jtk_e_content_file_invalid) | A content file under `jtk/` cannot be read as a document — it is not JSON, an entry is markdown, a show and a hide moment are the wrong way round — or a field in it holds what its kind refuses: text where a number is, a clock string for minutes, a select value that is not an option. |
| [`JTK_E_ENTRY_NO_COLLECTION`](#jtk_e_entry_no_collection) | Contract 2 only, the older contract: a content file under a collection's prefix in `jtk/content/` names no `collection`, or names one the schema does not have or whose prefix is not where the file sits — so it would be imported as a page, and no listing, no diary and no route would know it. |
| [`JTK_E_MEDIA_MISSING`](#jtk_e_media_missing) | The content names a picture or file that is not in this site's media library — a scaffold's example picture (`media/jtk-example/…`) never pushed, a key of another site, a file that was deleted, a key written by hand — so the build would fail downloading it. Said by a save (nothing committed; the message names the page and the field), by the import of a contract-3 tree (nothing imported; the message names the file and the key) and by the build's download. |
| [`JTK_E_ENTRY_INCOMPLETE`](#jtk_e_entry_incomplete) | An entry that is on the site and changed since the last version is not finished — a required value is missing, a value does not fit its field, or a reference names an entry that is not there — so it cannot become part of a version. The save did not happen and nothing was committed; the message names the first entry and field, and `details.unfinished` lists each entry once (`page_id`, `title`, `field`, and `live` where visitors see it now). An entry that is not on the site is not judged: a draft may be unfinished. |
| [`JTK_E_CODE_NOT_KEPT`](#jtk_e_code_not_kept) | This deployment keeps no code of its own, so a site's code cannot live on the platform here. |
| [`JTK_E_CODE_ELSEWHERE`](#jtk_e_code_elsewhere) | This site's code lives in a repository on GitHub, not on the platform, so push_code, pull_code, read_files and write_files do not apply to it. |
| [`JTK_E_CODE_TOKEN`](#jtk_e_code_token) | The URL `jtk push` or `jtk pull` was given has ended — used, expired after fifteen minutes, or never valid — or is for the other direction. |
| [`JTK_E_CODE_REFUSED`](#jtk_e_code_refused) | A path in the working copy cannot be part of a site's code: absolute, with `..`, `\` or a control character, inside `.git` in any case, `.gitmodules`, longer than 4096 bytes, a symlink or a submodule — or the archive did not carry exactly the files asked for, with the bytes the manifest named. Nothing was committed; the paths are named. |
| [`JTK_E_CODE_SECRET`](#jtk_e_code_secret) | A file looks like a secret: `.env`, an `.npmrc` with a token, a private key, an access key of GitHub, Stripe or AWS. Nothing was committed; the paths are named. |
| [`JTK_E_CODE_TOO_BIG`](#jtk_e_code_too_big) | The push is over a limit of code on the platform: 20 000 files, 50 MB a file, 200 MB a repository, 90 MB a part — or a write_files call over its own: 200 paths, 2 MB of text. |
| [`JTK_E_CODE_CONFLICT`](#jtk_e_code_conflict) | Something this commit changed was also changed on the branch since this copy's base — by a save in the panel (the person's edits, as a rule) or another machine — and the two differ. On a contract-3 site the content files under jtk/ are merged by field, so only one value both sides changed to two different values conflicts: `fields` names each, with the branch's value (`theirs`) and yours. A file is named whole where it is not such a file, or one side deleted it. Nothing was committed. |
| [`JTK_E_CODE_BASE`](#jtk_e_code_base) | The commit this working copy says it started from is not in the branch's history, so what it changed cannot be told. |
| [`JTK_E_CODE_TAKEN`](#jtk_e_code_taken) | The platform already holds a repository by this site's name that is not this site's, so its first push cannot create one. |
| [`JTK_E_CODE_RATE`](#jtk_e_code_rate) | This studio created more repositories on the platform in the last hour than it may. |
| [`JTK_E_CODE_COMMITS`](#jtk_e_code_commits) | More commits went into this site's code in the last hour than the platform takes: 60 a site, 120 a studio across its sites — pushes, and everything else that commits code. Nothing was committed; the message says when there is room again. |
| [`JTK_E_RATE_LIMITED`](#jtk_e_rate_limited) | More requests came from this caller in the window than the platform takes: 9 000 in 15 minutes from one account — its people in the panel and its agents together — 1 200 in 15 minutes from one address without a session, 300 uploads an hour to one site's library. Nothing was done; `retry_after` (and the Retry-After header) says in how many seconds there is room again. |
| [`JTK_E_THEIR_DRAFT`](#jtk_e_their_draft) | The panel holds unsaved changes a person made, and a save commits the whole draft — theirs with yours, half-done or not. Nothing was saved or built; the refusal names each change, the document and the field, and who made them. |
| [`JTK_E_KIT_RUNNING`](#jtk_e_kit_running) | A kit job of this site — the schema job after a `write_files`, a `create_site`'s create — is queued or running in the builder, and it commits on top of the branch when it is done. A build now would build the branch without it. Nothing was saved or built. |
| [`JTK_E_CODE_UNCHECKED`](#jtk_e_code_unchecked) | The build's code has not passed the platform's checks, so it cannot go live on a launched site. |
| [`JTK_E_PUBLISH_HELD`](#jtk_e_publish_held) | A person rolled the site back, and a rollback holds it on the version it chose: no build, publish or scheduled showing moves what visitors see until a person lifts the hold. |
| [`JTK_E_DRAFT_AHEAD`](#jtk_e_draft_ahead) | The panel holds unsaved changes that are in no commit, and the branch's content would write over them. On a contract-3 site only the documents where both changed one field wait — named, document → field — or one the person edited and the branch deleted; everything else came in. On a contract-2 site the whole import waits. |
| [`JTK_E_PLAN_SHORT`](#jtk_e_plan_short) | The studio's plan is short of a line of the kind named — a site, a diary or a shop — so the site cannot hold one. |
| [`JTK_E_NO_PLAN`](#jtk_e_no_plan) | The studio has no plan yet, so there is nothing to change, manage or draw a line from. |
| [`JTK_E_NOT_ON_SALE`](#jtk_e_not_on_sale) | No active Stripe price carries the lookup key the operation needs. |
| [`JTK_E_FROZEN`](#jtk_e_frozen) | The site is frozen: a subscription is fourteen days unpaid. Reading and export work; editing, publishing, new bookings and new orders do not. |
| [`JTK_E_DIARY_NOT_READY`](#jtk_e_diary_not_ready) | A visitor could not book: the diary is missing one of its two halves, and the sentence names which. |
| [`JTK_E_NO_DESTINATION`](#jtk_e_no_destination) | The site collects enquiries, takes bookings or takes orders and nothing verified is set up to receive them, so a visitor could send one into nothing. |
| [`JTK_E_BOOKING_PROTOCOL`](#jtk_e_booking_protocol) | The site's booking page named a version of the booking protocol this platform does not answer — a kit newer than the platform, or one so old its version has been retired. |
| [`JTK_E_MOVE_PRICE_CHANGES`](#jtk_e_move_price_changes) | A visitor tried to move, on their own link, a booking paid for online — or still to be paid — to a time the price table prices differently. The difference would be money nobody collected or owed back, so the link does not move it. |
| [`JTK_E_PROPOSAL_NO_CONTACT`](#jtk_e_proposal_no_contact) | Another time was offered for a request whose customer left only a telephone: no email and no Telegram chat, so the offer would reach nobody. Nothing was written. |
| [`JTK_E_VISITOR_CONTACT`](#jtk_e_visitor_contact) | A booking from the site was refused because the visitor cannot be reached by what they left: neither a telephone (seven to fifteen digits) nor an email address that is one, a field filled with something that is neither, or only one of the two where the business's booking settings ask for both (`contact`: `both`). |
| [`JTK_E_BOOKING_NOT_BEGUN`](#jtk_e_booking_not_begun) | A booking was marked as having taken place, or as one nobody came to, before its start. Neither can be said of a time still ahead. A booking already out with the customer is closed by coming back whenever it does, and is not refused. |
| [`JTK_E_PAYMENTS_OFF`](#jtk_e_payments_off) | This environment has no payment provider configured, so nothing that prices, charges or pays out can be answered here — the prices included, because they are read from the provider. |
| [`JTK_E_NO_BUSINESS`](#jtk_e_no_business) | Nobody is this site's business: no owner or admin has made the site theirs, and the studio has not taken it as its own. A launched site's enquiries, bookings and orders would be answered by nobody in particular. |
| [`JTK_E_PAYMENT_COUNTRY`](#jtk_e_payment_country) | The business's country is not set, or Stripe does not operate there, so no payment account can be made for it. |
| [`JTK_E_PAYMENT_ACCOUNT_NOT_READY`](#jtk_e_payment_account_not_ready) | The Stripe account this needs does not exist or may not charge yet: the studio's own under Reselling, on the Stripe account tab, or the business's under Payments. |
| [`JTK_E_HANDOVER_BLOCKED`](#jtk_e_handover_blocked) | The site cannot change hands as it stands. Every reason is in the sentence at once: not live, enquiries still going to the studio, the studio's Stripe account still attached, or the owner still paying the studio through us. |
| [`JTK_E_SUBSCRIPTION_RUNNING`](#jtk_e_subscription_running) | A running subscription's price, interval, method or address cannot be edited in place; a subscription sold at one price is not silently resold at another. |
| [`JTK_E_TERMS_FIRST`](#jtk_e_terms_first) | The owner's link was asked for before the studio said what the client pays. The terms travel on the link, so a link minted first would be an invitation with no price on it. |
| [`JTK_E_DOCUMENT_INVALID`](#jtk_e_document_invalid) | A document under `jtk/pages/`, `jtk/entries/` or `jtk/modules/` is not where it says it is, or not what contract 3 writes: a page without its `name`, a `path`, `collection` or `slug` that disagrees with the file's place, no `id` or a block, row or picture without a `_key`, a key a document does not have, `seo` on an entry with no page of its own, a `shown_on` page that is not there, a folder or a segment named `media`, a value in contract 2's shape (a price as a bare number, a picture as its key, a reference by slug), a reference naming an id no entry of its collections has, or a module's settings that are not `{v, settings}`. |
| [`JTK_E_BLOCK_BEHIND`](#jtk_e_block_behind) | A block in a document says a `v` its type's steps cannot bring to the type's own: an older version with no `upcast` step from it, or a version newer than the schema's type — content written against a schema that has not arrived. |
| [`JTK_E_CURRENCY_SET`](#jtk_e_currency_set) | A contract-3 tree's `jtk/site.json` says a new `currency`: neither the site's own nor the one the platform's last save wrote there. An import takes the currency from that file only while the site has none — as `create_site` takes it in `currency` — and once a site has its currency, a person changes it in the panel. A branch still carrying the last save's currency, from before a person changed or cleared it, is not refused: it is left, and the next save writes the site's. |
| [`JTK_E_SKU_ORDERED`](#jtk_e_sku_ordered) | A variant whose SKU a paid order named lost it, or the SKU was given to a variant it was not named for. Stock and orders are kept by the SKU, so a SKU an order named sits only on a variant it was named for, or on none, and a variant an order bought carries one of the SKUs orders named for it: the save, `import_branch` and `validate_schema` (by site and ref, or with the tree's files and the site in `site_id`) refuse the draft or the tree that moves it, naming the variant. A checkout never paid, one that lapsed and a test order name no SKU; an order gone at its retention names none either. |
| [`JTK_E_TRANSLATION_SHARED`](#jtk_e_translation_shared) | A translation — `..json` beside its original — says a value that is the same in every language: a price, a number, a date, a choice, a reference, a phone number, a link, a picture's file, focus or poster. A translation holds only the words; the translation of a shared value is the original's, everywhere, so a photograph changed in one language is changed in all of them. |
| [`JTK_E_TRANSLATION_RECORD`](#jtk_e_translation_record) | A translation's `translated` holds a record that is not one. A record is `{from, by, at}` under a value's path in the file — `from` the eight hex digits of the digest of the original's value the translation was made from, `by` `person`, `agent` or `machine`, `at` a moment in RFC 3339 — and nothing else. A record whose `from` is empty is read as none: a value whose original is empty has nothing it was made from. |
| [`JTK_E_MACHINE_OFF`](#jtk_e_machine_off) | Translate, in the panel's languages, asked a deployment that translates nothing by machine: it has no DeepL key — staging until a person sets one, production until DeepL is named in the data processing agreement — or the site's other languages are copies (contract 2) rather than translations of one original. |
| [`JTK_E_MACHINE_ALLOWANCE`](#jtk_e_machine_allowance) | The site's machine translation allowance is not enough for what was asked: a paid site's 30,000 characters of a calendar month, a demo's 10,000 once. What the cache already holds costs nothing and is not counted; everything sent to DeepL is. |
## Advice from the schema judge
Valid, and unwise. Nothing is refused on these; they come back under `advice` from `POST /v1/registry/validate` and from `validate_schema`, and an agent acts on them before the first build.
| code | means |
| --- | --- |
| [`JTK_W_MODULE_TWIN`](#jtk_w_module_twin) | A page block types again a fact the bookings module already holds — the opening hours the owner keeps in the diary, or the prices the services carry — so the site has two copies and one of them goes stale. |
| [`JTK_W_MODULE_POST`](#jtk_w_module_post) | An entry type the bookings module reads is shaped as a post — a `body`, or excerpt, cover and body together — or its services get a page each, so the panel draws a service or a table as an article with its own address. |
| [`JTK_W_KIND_UNKNOWN`](#jtk_w_kind_unknown) | `kind` in the bookings settings names a kind of business the platform has no dictionary for, so its bookings are spoken of in neutral words — «бронювання», «Забронювати». |
| [`JTK_W_KIND_MISSING`](#jtk_w_kind_missing) | The bookings settings say no `kind`, so the bookings are spoken of in the salon's words — «запис», «майстер» — which is what every site before kinds existed spoke, and nothing changes for it. Said so that a business that is not a salon is not given a salon's words by omission. |
| [`JTK_W_LOCALE_FALLBACK`](#jtk_w_locale_fallback) | The site takes bookings and its language (`locale`) is none of the eight the platform writes to customers in — `uk`, `en`, `de`, `ru`, `es`, `it`, `pt`, `fr` — so the letters to the customers and the messages to the owner go out in English. A region is read off first: `de-CH` is German, `pt-BR` Portuguese; `pl` or `ka` is English. |
| [`JTK_W_PAYMENT_UNCHECKED`](#jtk_w_payment_unchecked) | The site takes money online for its bookings, and the self-check (`preflight` with `self_check`) never pays: what needs the money paid — a booking confirmed by its payment, moved, offered another time — was not walked, and neither was the payment itself. |
| [`JTK_W_WORD_UNKNOWN`](#jtk_w_word_unknown) | A row of `words` in the bookings settings names a key the platform's dictionary does not have, so the word is said nowhere. |
| [`JTK_W_KIND_NO_DAYS`](#jtk_w_kind_no_days) | The bookings settings name the hours a stay goes out and comes back at (`hand_out`, `hand_back`), and not one of the services is sold by the day — the hours frame nothing, and it can only be booked by the hour, like a salon. |
| [`JTK_W_KIT_BEHIND`](#jtk_w_kit_behind) | `kit` and `kit_version` in a module's settings — the bookings' or the shop's — say which kit the site was laid out from and when, and the kit has changed since — a fix to it, or to a part it shares with other kits, that this site has not got. |
| [`JTK_W_UNPRICED_HOURS`](#jtk_w_unpriced_hours) | A service priced by the hour of the week (`rates` instead of `costs`) is open, by the hours in the bookings settings, at hours none of its rows prices — and an hour nobody priced is not sold: the form does not offer it for this service, and a page that asks for it is refused. |
| [`JTK_W_DIARY_UNSET`](#jtk_w_diary_unset) | The site takes bookings and its settings say no time zone (`zone`) or no opening hours (`hours`): until both are set the diary refuses every visitor — `/api/availability` and `preflight`'s try_booking answer JTK_E_DIARY_NOT_READY — and the form shows «nobody has said which timezone this business keeps». A draft may be unfinished, so nothing is refused; this is said so the gap is not found by a visitor. |
| [`JTK_W_SESSION_OUTSIDE_HOURS`](#jtk_w_session_outside_hours) | A bookable's own hours — a class's times in a sessions kit, a master's or a room's own week — reach outside the business's opening hours that day, and the diary offers only the part inside them (it clips one to the other, as the panel's diary shades): a class at 18:00–19:15 on a day the business closes at 18:00 is offered never, and nothing else says why. |
| [`JTK_W_ADDON_ALONE`](#jtk_w_addon_alone) | A service with no `takes` and a price is an add-on — shoes, a racket, a towel — taken only beside a timed service in one visit (wiki/70), and this site's bookings take one service per visit (`combine` off in the bookings settings), so nobody could take it. |
| [`JTK_W_OWNER_LOCKED`](#jtk_w_owner_locked) | A field holding a date, an hour or an amount of money is not `client_editable`, so the owner cannot change it: the next event's date, the hour the doors open, a price — facts of the business that change on its calendar, and that the studio is then asked to change every time. |
| [`JTK_W_HIDDEN_UNEXPLAINED`](#jtk_w_hidden_unexplained) | A field the owner edits is not on the page (`no_tap_target`) and names nothing it belongs to (`beside`) and says nothing about itself (`hint`): the panel shows it under More, at the foot of the editor of every field of its block, by its label alone, and the owner has to guess what it changes. |
| [`JTK_W_LINK_NOT_BESIDE`](#jtk_w_link_not_beside) | A link the page does not show (`no_tap_target`, a `url` or a key ending in `href`, `link` or `url`) names no field it belongs to (`beside`). The panel opens it under its button by the names alone — the words field named alike (`cta_href` with `cta_label`), or else the one field whose key says `cta` or `button` — and where that names one field, says which; where it names none or two, the link is under More with the block's other values, a step from the button it is about. |
| [`JTK_W_CONTENT_ORPHAN`](#jtk_w_content_orphan) | A content file carries a block type, or a field, that the schema does not describe — text the panel cannot show and the build cannot annotate. Or a whole file sits where the site's contract keeps nothing: in a tree whose schema is `jtk/schema.json`, a page in contract 2's places, under `jtk/content/`, or settings at contract 2's `jtk/.json`, which nothing reads. |
| [`JTK_W_CONTENT_BOUNDS`](#jtk_w_content_bounds) | A value in a content file is longer or shorter than its field allows, or a list has more or fewer rows than it may — the panel will refuse to save the field as it stands, though the build serves it. |
| [`JTK_W_NOT_LIVE`](#jtk_w_not_live) | The schema does not say `render: "live"`: the template does not draw a draft at request time, so the owner sees a change in the panel's preview only after a build, and an entry's card cannot be previewed before it is saved. |
| [`JTK_W_DATE_HIDES`](#jtk_w_date_hides) | The site's template compares an entry's date with the clock to choose what it shows — the next night, the ones left out, the ones marked past. A build freezes that comparison until the next build, a visitor sees what is over as ahead, and the panel, which cannot know, shows it as on the site. Said by the kit's `jtk schema`, from the site's code. |
| [`JTK_W_PANEL_FORM_GUESSED`](#jtk_w_panel_form_guessed) | The panel placed fields of an entry type by itself: a `form` places no row for some — they are drawn after its sections, under More — or a type of seven fields or more says no `form`, and the panel lays them out in their order, short ones two to a row and pictures aside. The fields a module's own card draws are the exception: no form lays them out and the count leaves them out, so the shop's product type is not advised for its eight — and a `form` that places one of them is, since the panel leaves it out of the form all the same. |
| [`JTK_W_FIRST_SCREEN`](#jtk_w_first_screen) | On the home page the heading or the first action ends below the first screen — a phone 390 × 844 or a desktop 1280 × 800 — so a visitor sees a picture and not what the business does or how to book it. Measured in a browser by `preflight` (the floor's F8). Advice, never a refusal. |
| [`JTK_W_ANCHOR_LANDING`](#jtk_w_anchor_landing) | A link in the home page — the header's `#angebot`, `#kontakt` — scrolls its target to where its first words land more than 96 px below the header, across the section's own top padding, or under the header. The visitor arrives at air, or at a cut heading, and scrolls again. Measured in a browser by `preflight` at a phone's and a desktop's width. Advice, never a refusal. |
| [`JTK_W_SCREEN_FIT`](#jtk_w_screen_fit) | On a desktop (1280 × 800) a section of the home page is a little taller than the screen under the header — by less than a third — so it is never seen whole; or a form, with its heading, is taller than that screen and its button is out of sight while it is filled. Measured in a browser by `preflight`. Advice, never a refusal. |
| [`JTK_W_RAGGED_GALLERY`](#jtk_w_ragged_gallery) | A wall of four or more pictures on the home page ends ragged: its columns end more than 24 px apart — a masonry of mixed proportions, or a last row left half empty. Measured in a browser by `preflight`. Advice, never a refusal. |
| [`JTK_W_BOOKING_LINK`](#jtk_w_booking_link) | A button on the home page — the header's «book» — opens another page of the site at its top, and that page's booking form starts more than half a screen down: the visitor who asked to book scrolls to find it. Measured in a browser by `preflight`. Advice, never a refusal. |
| [`JTK_W_TRANSLATION_ORPHAN`](#jtk_w_translation_orphan) | A translation gives words to a block, a row of a list or a gallery's picture by a `_key` its original has not got — removed in the original, or a key misspelt. Its words are shown nowhere, and the next save leaves them out of the file; the history keeps them. |
## Advice from the build
The build passes, and leaves the owner something they cannot tap, or the person a design that is not the one they were promised. Nothing is refused on these; the annotation lint and the design count print them in the build log with their `JTK_W_` code, after their own verdict.
| code | means |
| --- | --- |
| [`JTK_W_UNANNOTATED_FIELD`](#jtk_w_unannotated_field) | A value the owner edits — a phone, an email, a link, a choice, a date, an hour or a number — is on the page and carries no `data-jtk-path`: the owner taps it and nothing opens. Advice for now, for these kinds; a contract-3 build will refuse it as `JTK_E_UNANNOTATED_FIELD` once the kit's example draws them all. Advice too, of any kind, on contract 3, where a filled value's words are on no part of the built page: a field the template shows only on a condition — a label while another document has a value — is not refused on the build that hides it. |
| [`JTK_W_DRAWN_UNTAPPABLE`](#jtk_w_drawn_untappable) | A value the owner edits is drawn as text where nothing answers a tap: under `data-jtk-fixed`, or under no annotation at all — the business's name in a © line, a postcode joined to its city. Matched as the whole value, four characters or more, on the pages its document is drawn on; the shared text's on every page of its language. Advice, never a refusal. |
| [`JTK_W_TEMPLATE_DESIGN`](#jtk_w_template_design) | The site's design path is custom — the person gave their site or sites they like and wants a design of their own (`create_site`'s `design`) — and the site still wears the template's design: more than 60 % of the scaffold's design files (its components, styles and layouts, the forms and the kit's galleries, motion and helpers aside) are byte for byte the kit's, or its hero, header and footer all are. Recoloured tokens are not a custom design. Counted on every build (`design` in the build's answer: untouched, of, the files); said only where the path is custom. Advice, never a refusal. |
| [`JTK_W_DESIGN_AXES`](#jtk_w_design_axes) | The site's design path is custom and `jtk/design.json` chooses fewer than ten of the fourteen axes — a choice is a line of three words or more, what and from where; a tag like `split` or `linen` is not one — the hero, the ground, the measures, the shape, the header, the phone's menu, the overlap, the surfaces, the mark, the motion, the fonts, the hook, the proof, the contact — or no `mark`. Where the site shows directions, the first one's axes are counted. A design nobody chose on falls back on what a model reaches for first. Advice, never a refusal. |
| [`JTK_W_DIRECTIONS_ALIKE`](#jtk_w_directions_alike) | Two of the directions in `jtk/design.json`'s `directions` differ on fewer than three axes, or not on the hero: the person is shown one design in other colours and asked to choose. Advice, never a refusal. |
---
### JTK_E_SLUG_TAKEN
A site already answers to that slug.
**What to do:** If it is this account's, the refusal names its id — work with that site instead of making another. «That slug is taken» with no id is another account's site, which this one cannot see or claim: choose a different slug.
*Said by: the platform.*
### JTK_E_BOOKING_FIELD_UNKNOWN
A booking page sent `/api/book` a field, or `/api/availability` a parameter, that the contract does not have — or one of the wrong shape, `"count": "4"` for `4`. Refused when it comes from somebody the site knows: the studio, its agent, a preview. From a stranger it is dropped, and the booking goes ahead without it.
**What to do:** Send what [the booking protocol](booking-protocol.md#the-addresses) lists, with the names and shapes it gives: the answer's `fields` names what was wrong and `takes` everything that would have been read. A stay of several nights is `count`, never `units`, `nights` or `days`.
*Said by: the platform.*
### JTK_E_SHOP_PROTOCOL
A shop page named a version of the shop protocol this platform does not answer — a page newer than the platform, or one so old its version has been retired. The answer says what the page said (`said`) and the versions the platform speaks (`supported`).
**What to do:** Send a version the answer lists in `X-Jtk-Shop`, or none, which is version 1, and see [the shop protocol](shop-protocol.md#the-addresses) for what each address takes.
*Said by: the platform.*
### JTK_E_SHOP_FIELD_UNKNOWN
A shop page sent one of the shop protocol's addresses a field the contract does not have, at any depth of a cart — `coupon` at the top, `lines[0].colour` in a line — or one of the wrong shape, `"qty": "2"` for `2`. Refused when it comes from somebody the site knows: the studio, its agent, a preview. From a stranger it is dropped, and the cart is read without it.
**What to do:** Send what [the shop protocol](shop-protocol.md#the-addresses) lists, with the names and shapes it gives: the answer's `fields` names what was wrong, by path, and `takes` every name that would have been read.
*Said by: the platform.*
### JTK_E_ACCOUNT_PAUSED
The studio's account is paused by the platform: a report, a loop of builds, a scripted sign-up — something a person is looking at. Every request of its members and agents answers this; its sites answer 503 to visitors. Nothing is deleted.
**What to do:** Nothing an agent can do. The studio writes to the platform; a person resumes the account, and its sites come back in one step.
*Said by: the platform.*
### JTK_E_DOCUMENTS_DUE
A new version of the terms, the data processing agreement or the privacy policy binds from a date that has passed, and it has not been accepted — by the person signed in, or, for an agent, by any owner or admin of its studio. Every call answers this until it is; nothing is lost meanwhile.
**What to do:** Nothing an agent can do. Tell the developer: an owner or an admin of the studio opens the panel, reads the new version and accepts it, and the agent works again at once.
*Said by: the platform.*
### JTK_E_CROSS_ORIGIN
A request that would change something was signed in with the panel's session cookie and came from a page that is not the panel — a demo, a site, another tab's script, a sandboxed frame. The cookie is sent by the browser on its own, so the API takes a change made with it only from the panel's origin. Nothing was changed.
**What to do:** Make the change in the panel, or from a program with an agent's token (`Authorization: Bearer jtk_…`), which is not asked where it comes from. A script on a site or a demo cannot act with the session of whoever opened it.
*Said by: the platform.*
### JTK_E_OUT_OF_SYNC
The site's content has changed in its repository since the panel last read it, so publishing would delete work nobody has seen.
**What to do:** Run `import_branch` to bring the repository's content into the panel, then publish again. If the panel holds unsaved changes the import says so (JTK_E_DRAFT_AHEAD) rather than writing over them — read them with `get_content`, then import with `overwrite_draft` or carry them into the branch yourself.
*Said by: the platform.*
### JTK_E_STUDIO_ONLY
A field the schema does not give the owner — `client_editable` not `true` on contract 3, `false` on contract 2 — was written by somebody who may change the site's words and not that field. The panel shows such a field read-only, with «the studio edits this one»; the server refuses the write as well, and its `details` name the `path`.
**What to do:** Nothing an owner does: the studio changes it. If the owner should, the studio says `client_editable: true` on the field in the schema, commits it and imports it.
*Said by: the platform.*
### JTK_E_CONTENT_FILE_INVALID
A content file under `jtk/` cannot be read as a document — it is not JSON, an entry is markdown, a show and a hide moment are the wrong way round — or a field in it holds what its kind refuses: text where a number is, a clock string for minutes, a select value that is not an option.
**What to do:** Fix the file where the finding points: every value is what its field's kind says (`reference/field-kinds.md`), and a document is the shape `reference/jtk-files.md` gives — on contract 3 a page `jtk/pages/.json`, an entry `jtk/entries//.json`, the shared text `jtk/shared.json`; on contract 2, the older contract, `jtk/content/.json` as `{path, seo, blocks}`. `validate_schema` by site and ref says every such finding for the whole commit at once; `import_branch` refuses on the first.
*Said by: the platform.*
### JTK_E_ENTRY_NO_COLLECTION
Contract 2 only, the older contract: a content file under a collection's prefix in `jtk/content/` names no `collection`, or names one the schema does not have or whose prefix is not where the file sits — so it would be imported as a page, and no listing, no diary and no route would know it.
**What to do:** An entry says which collection it is an entry of: add `"collection": ""` (and `"visible": true`) to the file, the way publish writes it, then import again. A page that is not an entry lives outside every collection's prefix. Contract 3 has no prefix to mistake: an entry is `jtk/entries//.json`, its directory its collection.
*Said by: the platform, on contract 2 only — the older contract; a new site never meets it.*
### JTK_E_MEDIA_MISSING
The content names a picture or file that is not in this site's media library — a scaffold's example picture (`media/jtk-example/…`) never pushed, a key of another site, a file that was deleted, a key written by hand — so the build would fail downloading it. Said by a save (nothing committed; the message names the page and the field), by the import of a contract-3 tree (nothing imported; the message names the file and the key) and by the build's download.
**What to do:** From a working copy: `media_link`, then `npx @jtakeit/astro push '' --media ''` (the media push runs before the code) or `npx @jtakeit/astro media push ''` — it puts the pictures into this site's library and writes their keys into the content — then push or `import_branch` again. In the panel: choose the picture again, or upload it. A key of another site is never served here.
*Said by: the platform.*
### JTK_E_ENTRY_INCOMPLETE
An entry that is on the site and changed since the last version is not finished — a required value is missing, a value does not fit its field, or a reference names an entry that is not there — so it cannot become part of a version. The save did not happen and nothing was committed; the message names the first entry and field, and `details.unfinished` lists each entry once (`page_id`, `title`, `field`, and `live` where visitors see it now). An entry that is not on the site is not judged: a draft may be unfinished.
**What to do:** Finish the entry in the panel, or keep it off the site for now (its switch off, which a person does in the panel); then save again. From the repository: fill the field in the entry's file, commit, `import_branch`.
*Said by: the platform.*
### JTK_E_CODE_NOT_KEPT
This deployment keeps no code of its own, so a site's code cannot live on the platform here.
**What to do:** Use the GitHub path: a repository with our GitHub App installed by a person, `attach_repo`, `git push`, `import_branch`.
*Said by: the platform.*
### JTK_E_CODE_ELSEWHERE
This site's code lives in a repository on GitHub, not on the platform, so push_code, pull_code, read_files and write_files do not apply to it.
**What to do:** Work as with any GitHub repository: `git pull`, commit, `git push`, then `import_branch` and `commit_and_build`. `get_site` says where a site's code lives (`code`).
*Said by: the platform.*
### JTK_E_CODE_TOKEN
The URL `jtk push` or `jtk pull` was given has ended — used, expired after fifteen minutes, or never valid — or is for the other direction.
**What to do:** Ask for a new one: `push_code` or `pull_code`, then run the command it answers with, as it is.
*Said by: the platform.*
### JTK_E_CODE_REFUSED
A path in the working copy cannot be part of a site's code: absolute, with `..`, `\` or a control character, inside `.git` in any case, `.gitmodules`, longer than 4096 bytes, a symlink or a submodule — or the archive did not carry exactly the files asked for, with the bytes the manifest named. Nothing was committed; the paths are named.
**What to do:** Remove or rename what is named, or add it to `.gitignore` if it is not the site's code, and push again. A symlink is replaced by the file it points to. Through write_files: each path once a call, text with no NUL byte, a deletion only of a file the base has, never over a symlink.
*Said by: the platform.*
### JTK_E_CODE_SECRET
A file looks like a secret: `.env`, an `.npmrc` with a token, a private key, an access key of GitHub, Stripe or AWS. Nothing was committed; the paths are named.
**What to do:** A secret does not belong in a site's code. Remove it, add it to `.gitignore`, and if it was ever pushed anywhere, change it. Settings a build needs go through the site's settings, never through a file.
*Said by: the platform.*
### JTK_E_CODE_TOO_BIG
The push is over a limit of code on the platform: 20 000 files, 50 MB a file, 200 MB a repository, 90 MB a part — or a write_files call over its own: 200 paths, 2 MB of text.
**What to do:** Pictures and video belong in the site's media (upload them through the panel or the media endpoint), not in its code. Remove the large files from the working copy, or add them to `.gitignore`. A write_files over its call's limits goes in parts, each on the last one's `sha`.
*Said by: the platform.*
### JTK_E_CODE_CONFLICT
Something this commit changed was also changed on the branch since this copy's base — by a save in the panel (the person's edits, as a rule) or another machine — and the two differ. On a contract-3 site the content files under jtk/ are merged by field, so only one value both sides changed to two different values conflicts: `fields` names each, with the branch's value (`theirs`) and yours. A file is named whole where it is not such a file, or one side deleted it. Nothing was committed.
**What to do:** The person wins by default. Keep their value: tell them what they changed — the field and the value — and that you left it; then pull (`pull_code` and its `jtk pull` into a new, empty directory, or `git pull` where the code is on GitHub), carry your change over onto what the branch holds now — never over their value — and commit again — through write_files: read_files the named files at the tip, lay your change over what they hold now, and write on that tip. Write over their value only when the person says so in the chat. `jtk pull` writes nothing over a conflict, and its URL is spent on the try.
*Said by: the platform.*
### JTK_E_CODE_BASE
The commit this working copy says it started from is not in the branch's history, so what it changed cannot be told.
**What to do:** The copy came from somewhere else. `pull_code` and `jtk pull` into an empty directory, then bring your changes over and push from there. Through write_files: the base is the `tip` read_files answered with, or the last write's `sha` — read_files again and write on its tip.
*Said by: the platform.*
### JTK_E_CODE_TAKEN
The platform already holds a repository by this site's name that is not this site's, so its first push cannot create one.
**What to do:** Ask the platform's support: a repository by that name is being kept for a reason, and it is not overwritten.
*Said by: the platform.*
### JTK_E_CODE_RATE
This studio created more repositories on the platform in the last hour than it may.
**What to do:** Wait an hour. A site's repository is created once, on its first push; later pushes are not counted.
*Said by: the platform.*
### JTK_E_CODE_COMMITS
More commits went into this site's code in the last hour than the platform takes: 60 a site, 120 a studio across its sites — pushes, and everything else that commits code. Nothing was committed; the message says when there is room again.
**What to do:** Wait the minutes the message names (`Retry-After` says the seconds), then push again. A loop that pushes after every small change is the usual cause: change more, push once.
*Said by: the platform.*
### JTK_E_RATE_LIMITED
More requests came from this caller in the window than the platform takes: 9 000 in 15 minutes from one account — its people in the panel and its agents together — 1 200 in 15 minutes from one address without a session, 300 uploads an hour to one site's library. Nothing was done; `retry_after` (and the Retry-After header) says in how many seconds there is room again.
**What to do:** Wait the seconds `retry_after` names, then ask again — the same call will work. A loop that asks without a pause is the usual cause: wait a few seconds between `get_build` calls while a build runs, and read a site once rather than before every step.
*Said by: the platform.*
### JTK_E_THEIR_DRAFT
The panel holds unsaved changes a person made, and a save commits the whole draft — theirs with yours, half-done or not. Nothing was saved or built; the refusal names each change, the document and the field, and who made them.
**What to do:** Ask the person, naming their changes: are they ready to go with yours? On their yes, `commit_and_build` with `with_their_draft: true` saves and builds them with yours. Without it, `branch_only: true` builds the branch as it stands — your commits — and leaves their draft unsaved in the panel for them. Never pass with_their_draft on your own.
*Said by: the platform.*
### JTK_E_KIT_RUNNING
A kit job of this site — the schema job after a `write_files`, a `create_site`'s create — is queued or running in the builder, and it commits on top of the branch when it is done. A build now would build the branch without it. Nothing was saved or built.
**What to do:** Wait for it: `get_site`'s `kit_job` says `done` — usually within a minute — or `failed`, with why. Then `commit_and_build` again. The MCP's `commit_and_build` waits for it on its own for a while before it answers this.
*Said by: the platform.*
### JTK_E_CODE_UNCHECKED
The build's code has not passed the platform's checks, so it cannot go live on a launched site.
**What to do:** The checks judge code, not who started the build: the annotation lint — noindex, robots, the sitemap, the canonical, the enquiry form's contract — and the site built with every optional field empty and with every one filled and long. A person's build of new code goes on for the preview and says what failed in its log; fix that in the repository, push, and build again. A build of code that has passed goes live, and a save that changed only content keeps the verdict of the code it was made on.
*Said by: the platform.*
### JTK_E_PUBLISH_HELD
A person rolled the site back, and a rollback holds it on the version it chose: no build, publish or scheduled showing moves what visitors see until a person lifts the hold.
**What to do:** Nothing to retry. A build made meanwhile is kept as the candidate and shown in the preview; a person lifts the hold on the panel's builds card once the source is fixed, then publishes. Fix the source first — the rollback restored the artifact, not the repository.
*Said by: the platform.*
### JTK_E_DRAFT_AHEAD
The panel holds unsaved changes that are in no commit, and the branch's content would write over them. On a contract-3 site only the documents where both changed one field wait — named, document → field — or one the person edited and the branch deleted; everything else came in. On a contract-2 site the whole import waits.
**What to do:** The person has been editing in the panel. Tell them what waited, by the names the answer gives (`waited`), and keep their value: read it with `get_content` and build on it, or ask them; `import_branch` with `overwrite_draft: true` writes the branch over their edits on purpose, only on their word. Nothing is lost: the code has landed and what waits is in the branch; the panel's next save — `commit_and_build`, or theirs — brings it in first and lays their changes over it, theirs standing where both changed one field (`synced` in the answer), and `commit_and_build`'s `dry_run` says it is waiting (`pending`). Bring your copy to the branch first, always — every version is a commit on it: `git pull` where the code is on GitHub, `pull_code` and its `jtk pull` where it is on jtakeit (`get_site` says which, `code`).
*Said by: the platform.*
### JTK_E_PLAN_SHORT
The studio's plan is short of a line of the kind named — a site, a diary or a shop — so the site cannot hold one.
**What to do:** One more of that kind under Reselling, by the studio's owner or admin; `get_allowance` says what is held and where it went. A demo costs nothing until it goes live, which is when this arrives.
*Said by: the platform.*
### JTK_E_NO_PLAN
The studio has no plan yet, so there is nothing to change, manage or draw a line from.
**What to do:** Buy one under Reselling. Everything the studio holds today was granted rather than bought.
*Said by: the platform.*
### JTK_E_NOT_ON_SALE
No active Stripe price carries the lookup key the operation needs.
**What to do:** A deployment step, not a repository fix: `scripts/stripe-prices.sh` creates the prices, in test mode and in live mode separately.
*Said by: the platform.*
### JTK_E_FROZEN
The site is frozen: a subscription is fourteen days unpaid. Reading and export work; editing, publishing, new bookings and new orders do not.
**What to do:** Pay. Whose payment the sentence says — the studio's plan with us under Reselling, or the owner's invoice to the studio on the owner's Subscription screen. Paying thaws; nothing else does.
*Said by: the platform.*
### JTK_E_DIARY_NOT_READY
A visitor could not book: the diary is missing one of its two halves, and the sentence names which.
**What to do:** The schema's `modules.bookings` and its collections are the repository's — commit, `import_branch`, build. The time zone and the hours are the owner's — Diary → Opening hours, then save and publish. `preflight` reports this. One entry the diary cannot compute on — a resource with both `seats` and `spots`, a service with two prices or a `most` under its `fewest` — is left out of a visitor's diary while the rest stays open, and the launch's gate names it until it is fixed.
*Said by: the platform.*
### JTK_E_NO_DESTINATION
The site collects enquiries, takes bookings or takes orders and nothing verified is set up to receive them, so a visitor could send one into nothing.
**What to do:** A person adds a destination on The site → Notifications: a Telegram chat, an email address, or the panel alone. Telegram and email are confirmed before they count; the panel's own inbox needs no confirming and answers the gate on its own. It is the site's owner or admin, or the studio while it runs the site — never an agent, which `records.destinations` refuses. The gate is derived from the schema and cannot be switched off.
*Said by: the platform.*
### JTK_E_BOOKING_PROTOCOL
The site's booking page named a version of the booking protocol this platform does not answer — a kit newer than the platform, or one so old its version has been retired.
**What to do:** Update `@jtakeit/kit` in the site's repository to a release this platform supports (the answer lists the versions it speaks), build, and run `preflight` with `try_booking`. A visitor's booking is not refused for it; the studio's and its agent's are, so the mismatch is heard before it matters.
*Said by: the platform.*
### JTK_E_MOVE_PRICE_CHANGES
A visitor tried to move, on their own link, a booking paid for online — or still to be paid — to a time the price table prices differently. The difference would be money nobody collected or owed back, so the link does not move it.
**What to do:** Nothing to fix in the site. The visitor rings the business, and the business moves the booking in the diary and settles the difference with them. A move to a time at the same price goes through on the link as before.
*Said by: the platform.*
### JTK_E_PROPOSAL_NO_CONTACT
Another time was offered for a request whose customer left only a telephone: no email and no Telegram chat, so the offer would reach nobody. Nothing was written.
**What to do:** Ring the customer. Agree the time with them and move the request in the diary, or confirm it. An offer can be made once the booking has an email or a chat linked to it.
*Said by: the platform.*
### JTK_E_VISITOR_CONTACT
A booking from the site was refused because the visitor cannot be reached by what they left: neither a telephone (seven to fifteen digits) nor an email address that is one, a field filled with something that is neither, or only one of the two where the business's booking settings ask for both (`contact`: `both`).
**What to do:** Nothing to fix in the site for a visitor's typo: the form says which field to correct. If every booking is refused for this, the form does not send what the settings ask for — a form with no email field cannot book while `contact` is `both`; add the field (the kit's form has it) or set `contact` back to one is enough. A booking the business adds in the panel is never refused for it.
*Said by: the platform.*
### JTK_E_BOOKING_NOT_BEGUN
A booking was marked as having taken place, or as one nobody came to, before its start. Neither can be said of a time still ahead. A booking already out with the customer is closed by coming back whenever it does, and is not refused.
**What to do:** Wait until the booking's start has passed, then mark it. A booking that will not happen is cancelled instead; one moved to another time is moved.
*Said by: the platform.*
### JTK_E_PAYMENTS_OFF
This environment has no payment provider configured, so nothing that prices, charges or pays out can be answered here — the prices included, because they are read from the provider.
**What to do:** Nothing in the site or the account is wrong. Say so to whoever asked: there are no payments in this environment (staging and local development usually have none). The prices are on the production platform's own pricing page and in its panel.
*Said by: the platform.*
### JTK_E_NO_BUSINESS
Nobody is this site's business: no owner or admin has made the site theirs, and the studio has not taken it as its own. A launched site's enquiries, bookings and orders would be answered by nobody in particular.
**What to do:** Two doors, and the launch takes either: invite the owner from the site's People screen and let the client make the site theirs — a client who will never open the panel opens it once, and lets the studio at the records and the money from there — or press *This is our own site* on the site's screen.
*Said by: the platform.*
### JTK_E_PAYMENT_COUNTRY
The business's country is not set, or Stripe does not operate there, so no payment account can be made for it.
**What to do:** The country is set under The site → The business. A country Stripe does not serve cannot be paid through us today; there is no second provider yet.
*Said by: the platform.*
### JTK_E_PAYMENT_ACCOUNT_NOT_READY
The Stripe account this needs does not exist or may not charge yet: the studio's own under Reselling, on the Stripe account tab, or the business's under Payments.
**What to do:** Set it up on that screen and answer Stripe's questions; charges are allowed when Stripe says so, usually within a day or two. Nothing can be billed before that.
*Said by: the platform.*
### JTK_E_HANDOVER_BLOCKED
The site cannot change hands as it stands. Every reason is in the sentence at once: not live, enquiries still going to the studio, the studio's Stripe account still attached, or the owner still paying the studio through us.
**What to do:** Undo each named thing — launch, remove the studio's destinations, remove the payee, stop the client billing — then mint the offer again.
*Said by: the platform.*
### JTK_E_SUBSCRIPTION_RUNNING
A running subscription's price, interval, method or address cannot be edited in place; a subscription sold at one price is not silently resold at another.
**What to do:** Stop it and start a new one. The owner sees a new first invoice rather than a surprise on the next; what was paid stays paid.
*Said by: the platform.*
### JTK_E_TERMS_FIRST
The owner's link was asked for before the studio said what the client pays. The terms travel on the link, so a link minted first would be an invitation with no price on it.
**What to do:** Set what the client pays under the site's Subscription — zero is an answer — and mint the link from there.
*Said by: the platform.*
### JTK_E_CATALOGUE_UNREADABLE
Contract 2's schema, `jtk/catalogue.json`, is not JSON, or carries a key that contract has no place for. Contract 3's `jtk/schema.json` says this as JTK_E_SCHEMA_UNREADABLE or JTK_E_SCHEMA_KEY_UNKNOWN.
**What to do:** Read the error's own words: they name the offending key. A key that used to be valid means the toolkit is newer than the service.
*Said by: the schema, on contract 2 only — the older contract; a new site never meets it.*
### JTK_E_CONTRACT_UNKNOWN
The schema names a contract number this service does not speak.
**What to do:** A higher number than ours is a service to deploy, not a repository to fix. A lower one is upgraded silently and never reaches you.
*Said by: the schema.*
### JTK_E_CATALOGUE_EMPTY
Contract 2's schema, `jtk/catalogue.json`, declares no blocks, so it describes no site. Contract 3 says this as JTK_E_SCHEMA_EMPTY.
**What to do:** Declare at least one block type. A schema is the list of shapes a site's content comes in.
*Said by: the schema, on contract 2 only — the older contract; a new site never meets it.*
### JTK_E_GENERATOR_INVALID
The `generator` string does not name a tool.
**What to do:** Letters, digits and the punctuation a package name uses, up to eighty characters — or leave it out.
*Said by: the schema.*
### JTK_E_NAME_INVALID
A block type, field key, view key or collection name is not spelled the way an identifier must be.
**What to do:** Lowercase letters, digits and underscores, starting with a letter, up to forty characters. These strings become annotation paths and generated TypeScript names.
*Said by: the schema.*
### JTK_E_NAME_DUPLICATE
Two things in the same place are called the same thing.
**What to do:** Rename one of them. Which of the two wins would otherwise depend on the order of a slice.
*Said by: the schema.*
### JTK_E_LABEL_MISSING
A field, view or collection has no label.
**What to do:** Give it words. The label is what the owner reads in the admin, and a form of keys is not a form.
*Said by: the schema.*
### JTK_E_TEXT_INVALID
A label or hint is written both once and per language, names a language that is not one, is empty, or runs too long.
**What to do:** Write it once as a string, or per language as an object of language to words — never both. Three hundred characters is the ceiling.
*Said by: the schema.*
### JTK_E_BLOCK_VERSION
A block type has no version, or a version below one.
**What to do:** Give the block `"v": 1`. The version is how stored content knows which shape it was written against.
*Said by: the schema.*
### JTK_E_BLOCK_EMPTY
A block type declares no fields.
**What to do:** Declare at least one field, or remove the block. A block with no fields is a block nobody can edit.
*Said by: the schema.*
### JTK_E_COLLECTS_UNKNOWN
A block says it collects something nothing knows about.
**What to do:** The only thing a block may collect today is `"enquiry"`. A typo here would quietly exempt the site from the publishing gate that asks where enquiries go.
*Said by: the schema.*
### JTK_E_KIND_UNKNOWN
A field's kind is not one of the 19 — 17 on contract 2, which has neither `sku` nor `picks`.
**What to do:** Use a kind from the reference. The set is closed because each kind is a validator, a form control, a zod schema and an annotation rule.
*Said by: the schema.*
### JTK_E_BOUNDS_INVALID
A `min` or `max` is negative, or the minimum is above the maximum.
**What to do:** Bounds count characters for text, the value for a number, and items for a list or a gallery.
*Said by: the schema.*
### JTK_E_SELECT_NO_OPTIONS
A `select` field offers nothing to select.
**What to do:** Give it `options`. A select with no options is a control that cannot be used.
*Said by: the schema.*
### JTK_E_LIST_INVALID
A list nests lists deeper than its contract allows, declares no item fields, or `of` appears on a field that is not a list.
**What to do:** On contract 3 a row may hold one list of its own, whose rows are a flat set of fields; on contract 2 every row is flat. There is no form control and no annotation path deeper than that.
*Said by: the schema.*
### JTK_E_MEDIA_INVALID
A media field's `accept`, `ratio` or `multiple` do not go together — or one of the three appears on a field that is not media.
**What to do:** A video needs `multiple` because it is stored with its poster; so does a `ratio`, because the focus is stored beside the picture. Use `max: 1` when there is only one.
*Said by: the schema.*
### JTK_E_BESIDE_INVALID
A field's `beside` names no field of the same block (or row), names the field itself, or names a field that is not on the page either — or the field carrying it is on the page.
**What to do:** `beside` goes on a `no_tap_target` field and names the field the owner taps that this value belongs to: the hour beside the date, the address beside the button's words. The panel opens it under that field.
*Said by: the schema.*
### JTK_E_TITLED_BY_INVALID
A field's `titled_by` names no field of the same block (or row), names the field itself, or names a field that is not a line of text.
**What to do:** `titled_by` names the text field whose words stand over this value on the page — `age_label` over `night_age` — so the panel calls the value what the page calls it. Point it at a `text` field of the same block or row.
*Said by: the schema.*
### JTK_E_VIEW_INVALID
A block declares arrangements but has no gallery to arrange, sets its bounds in two places, or a view's own bounds do not make sense.
**What to do:** Views arrange one `multiple` media field, and the limits live on the views rather than on the field.
*Said by: the schema.*
### JTK_E_LOCALE_INVALID
A language is not a language, is declared twice, or the site's own language appears again among the others.
**What to do:** Two letters, or two and a region — `uk`, `en`, `de-CH`. The site's own language is `locale`, and it does not repeat in `locales`.
*Said by: the schema.*
### JTK_E_MODULE_UNKNOWN
The schema turns on a module this service does not have.
**What to do:** Modules are a closed set — see the reference for which ones exist. A module that is not there is not one you can enable by naming it.
*Said by: the schema.*
### JTK_E_MODULE_ROLE_INVALID
A module is pointed at nothing, or at something that is not a collection of this schema.
**What to do:** Every required role must name one of this schema's own collections: bookings needs `services` and `resources`.
*Said by: the schema.*
### JTK_E_MODULE_FILE_INVALID
Contract 2 only, the older contract: its settings file `jtk/.json` is not a settings document — it is not JSON, it has no `blocks`, its one block is not the module's own config type, or a field holds what its kind refuses.
**What to do:** On contract 2 the file has one shape — `{"blocks": [{"type": "bookings_config", "v": 1, "zone": …, "hours": […]}]}` — the same one publish writes; settings written as top-level keys are not read: put them inside the block. Import refuses rather than importing an empty diary, so nothing is silently lost. Contract 3 keeps a module's settings in `jtk/modules/.json` as `{"v": 1, "settings": {…}}` and says a fault in them as JTK_E_DOCUMENT_INVALID; `reference/jtk-files.md` shows both and the modules reference lists the fields.
*Said by: the schema, on contract 2 only — the older contract; a new site never meets it.*
### JTK_E_COLLECTION_INVALID
A collection's place, icon, entry type or `blocks` list is wrong — or, on contract 2, its prefix or pagination.
**What to do:** Give a collection an entry type that is a declared block, and a place and an icon the schema reference lists. On contract 3 where the entries live is the collection's `route`, judged as JTK_E_ROUTE_INVALID; on contract 2 a prefix is a path like `/blog` with no trailing slash, and no two collections may own the same addresses.
*Said by: the schema.*
### JTK_E_ENTRY_TYPE_INVALID
The block type a collection names cannot be used for entries.
**What to do:** An entry needs a required `title`, must not use a reserved key for something else, and must give the reserved keys their reserved kinds.
*Said by: the schema.*
### JTK_E_ORDER_INVALID
A collection is ordered by a field that will not order it.
**What to do:** Order by a required date or number, or arrange the entries by hand with `"by": "manual"`.
*Said by: the schema.*
### JTK_E_UNANNOTATED_FIELD
A content field is on the page and carries no `data-jtk-path`.
**What to do:** Annotate the element that renders the value. Without it the visual editor silently stops opening when the client taps that text.
*Said by: the build.*
### JTK_E_PAGE_NOT_BUILT
The content has a page and the build did not produce it — or a collection without pages of its own shows its entries on a page no build made: its `shown_on` page on contract 3, its prefix on contract 2.
**What to do:** Give the site a route for that path, or remove the page. A page nothing renders cannot be previewed or served. For a collection with `route: "none"`, name in `shown_on` the page that shows the entries, or build one there (on contract 2, a `pages: false` collection's prefix is that page).
*Said by: the build.*
### JTK_E_BUILD_REACH
The build asked for a host it may not reach. A build runs with no network of its own: the repository on github.com, the npm and yarn registries, the platform's media host and Google Fonts are forwarded, and nothing else is — GET and HEAD, with POST only for the clone.
**What to do:** Read the line in the build log: it names the request and the list. A dependency pinned to the registry needs nothing more; a dependency that downloads a binary from a release is one that is not on the registry, and the install fails on it by design. A font goes in the repository or through Google Fonts; anything fetched from a service at build time belongs in `jtk/` as content, or is not a site of this shape.
*Said by: the runner.*
### JTK_E_ROBOTS_DISALLOW
The build ships a robots.txt that keeps every crawler out.
**What to do:** `robots.txt` says `Disallow: /` for everybody. Every build is made for the site's address and serves it once the site is live; the preview is kept out of the index by the platform, not by this file. Allow crawlers and name the sitemap.
*Said by: the build.*
### JTK_E_SITEMAP_EMPTY
The build ships a sitemap with no pages, or pages on another host.
**What to do:** `sitemap.xml` lists nothing, or lists addresses on a host that is not the one the build was made for (`SITE_URL`). List every page on `SITE_URL`, always — there is no build that should ship an empty sitemap.
*Said by: the build.*
### JTK_E_CANONICAL_ELSEWHERE
The build says its canonical page is on another host.
**What to do:** The front page's ` ` names a host other than the one the build was made for (`SITE_URL`). Derive the canonical from `import.meta.env.SITE`, not from a constant: a canonical on another host hands the site's ranking to a page nobody can reach.
*Said by: the build.*
### JTK_E_NOINDEX
The page tells search engines to go away.
**What to do:** The front page carries a `noindex` robots tag. Nothing in a page decides whether it is indexed: every build is made for the site's address, a preview is kept out of the index by the platform's own header, and a launch is a pointer moved. Take the tag out — and take out the switch that wrote it, because a switch somebody flips at launch is a site quietly telling search engines to go away, the most expensive mistake a studio makes.
*Said by: the build.*
### JTK_E_SHARED_NOT_RENDERED
A shared field is rendered on no page at all.
**What to do:** Render it somewhere, or take it out of the shared document. A shared field nothing renders is a control that edits nothing.
*Said by: the build.*
### JTK_E_ANNOTATION_UNKNOWN
A `page:` annotation names a page this site has not got, or a field that page's document has not got.
**What to do:** Check the address and the field key. A mistyped cross-page annotation is a tile the owner taps and nothing opens.
*Said by: the build.*
### JTK_E_CONTENT_VARIANT
The site's code fails to build, or loses an annotation, on content an owner can write: every optional field empty, or every one filled and long.
**What to do:** Make the template take an optional field's absence — draw nothing, or a fallback — and a long value — let it wrap. The log says which of the two and what failed. An agent's build tries both because a save in the panel never fails a build: a person's build goes on and the studio reads the log, so the code has to be right before it is accepted.
*Said by: the build.*
### JTK_E_CATALOGUE_MISSING
The repository has no schema: neither `jtk/schema.json` (contract 3) nor `jtk/catalogue.json` (contract 2, the older contract).
**What to do:** Commit one: on a new site `npx @jtakeit/astro schema` writes `jtk/schema.json` from `src/content/blocks.ts`. Nothing can check that a site's content is annotated without knowing what fields it has.
*Said by: the build.*
### JTK_E_FORM_INCOMPLETE
A form posting to `/api/lead` is missing a control the enquiry's structure needs.
**What to do:** Every enquiry form has a `name` control, one of `contact`, `phone` or `email`, and the honeypot `website`. Without them the edge refuses every visitor as `anonymous` or `unreachable`, or every bot gets through.
*Said by: the build.*
### JTK_E_FORM_FIELD_UNDECLARED
A form posting to `/api/lead` has a control the schema does not declare.
**What to do:** Declare it in `asks` on the block that carries `collects: "enquiry"`, with a label — that is what lets the inbox, the notification and the export say what the value is.
*Said by: the build.*
### JTK_E_FORM_UNDECLARED
A page has a form posting to `/api/lead` and no block on it says `collects: "enquiry"`.
**What to do:** Put `collects: "enquiry"` on the block that carries the form. The launch gate that demands a destination for enquiries reads the schema, not the markup — a form nothing declares is one whose messages can go nowhere.
*Said by: the build.*
### JTK_W_UNANNOTATED_FIELD
A value the owner edits — a phone, an email, a link, a choice, a date, an hour or a number — is on the page and carries no `data-jtk-path`: the owner taps it and nothing opens. Advice for now, for these kinds; a contract-3 build will refuse it as `JTK_E_UNANNOTATED_FIELD` once the kit's example draws them all. Advice too, of any kind, on contract 3, where a filled value's words are on no part of the built page: a field the template shows only on a condition — a label while another document has a value — is not refused on the build that hides it.
**What to do:** Annotate the element that draws the value, as for a heading: `{...facts.at('phone')}` on the link that shows the number, a date or an hour formatted as the page likes, with the field's path on its element. A value the page does not show is `no_tap_target`, `beside` the field it belongs to. A value shown on a condition: annotate it where it is drawn, and check a build where it is; one the template never draws is a field the owner edits for nothing — draw it, or take it out of the schema.
*Said by: the build advice.*
### JTK_E_CACHED_FILE_CHANGED
A name a public build let browsers keep — under `immutable` or a `cache` directory of `_meta.json` — has other contents in this build while it is still held.
**What to do:** A browser cannot be purged: whoever has seen the site keeps the old file under that name for as long as the edge said, so the platform holds the name until the last of them may have let go — the served build's for as long as it is served and its lifetime after, and every earlier build's until its own hold runs out. The log names each file and when it is free; `get_build` and `preflight` list what is held. Give the new file a new name, with a version in it, and point the page at it. Lowering `maxAge`, dropping the file or rolling back frees nothing sooner: browsers already hold the old lifetime.
*Said by: the store.*
### JTK_W_MODULE_TWIN
A page block types again a fact the bookings module already holds — the opening hours the owner keeps in the diary, or the prices the services carry — so the site has two copies and one of them goes stale.
**What to do:** Read the fact from where it lives: the hours from the bookings settings — `jtk/modules/bookings.json`, or `jtk/bookings.json` on contract 2 — which a save writes from the owner's, and the prices from the services collection the booking form reads. Drop the text rows from the block.
*Said by: the advice.*
### JTK_W_MODULE_POST
An entry type the bookings module reads is shaped as a post — a `body`, or excerpt, cover and body together — or its services get a page each, so the panel draws a service or a table as an article with its own address.
**What to do:** A service is filled in, not written: short fields (a name, `takes`, `costs`, a line), no `body`, and `route: "none"` on the collection (`pages: false` on contract 2). A resource is a record the diary occupies — a name, its own `hours`, what it `does`, `seats` or `spots` — with a line and a photograph if the page wants them.
*Said by: the advice.*
### JTK_W_KIND_UNKNOWN
`kind` in the bookings settings names a kind of business the platform has no dictionary for, so its bookings are spoken of in neutral words — «бронювання», «Забронювати».
**What to do:** Name an existing kind — the nearest one the modules reference lists, `car_rental`, `hotel`, `restaurant` and the rest — and write over the words that do not fit in `words` beside it ([kits](kits.md#a-business-not-among-the-kits)). A word of the site's own goes in `words`, not in a kind nobody knows. No `kind` at all speaks a salon's words (`JTK_W_KIND_MISSING`).
*Said by: the advice.*
### JTK_W_KIND_MISSING
The bookings settings say no `kind`, so the bookings are spoken of in the salon's words — «запис», «майстер» — which is what every site before kinds existed spoke, and nothing changes for it. Said so that a business that is not a salon is not given a salon's words by omission.
**What to do:** Name the kind of business: one of the kinds the modules reference lists (`salon`, `clinic`, `car_rental` and the rest), the nearest one where none is exact, with the words that do not fit overridden in `words` ([kits](kits.md#a-business-not-among-the-kits)). A salon may say `salon`, or nothing. Nothing is refused.
*Said by: the advice.*
### JTK_W_LOCALE_FALLBACK
The site takes bookings and its language (`locale`) is none of the eight the platform writes to customers in — `uk`, `en`, `de`, `ru`, `es`, `it`, `pt`, `fr` — so the letters to the customers and the messages to the owner go out in English. A region is read off first: `de-CH` is German, `pt-BR` Portuguese; `pl` or `ka` is English.
**What to do:** Nothing is refused: a site may be written in any language, and its letters are English. Tell the developer, so the owner is not surprised; the panel says it too, under Working hours. If the business writes to its customers in one of the eight, name that language as the site's. A booking keeps no language of its own: every letter speaks the site's.
*Said by: the advice.*
### JTK_W_PAYMENT_UNCHECKED
The site takes money online for its bookings, and the self-check (`preflight` with `self_check`) never pays: what needs the money paid — a booking confirmed by its payment, moved, offered another time — was not walked, and neither was the payment itself.
**What to do:** Nothing is refused, and `ready` is not held back by it. Tell the owner the online payment was not checked, and check it by hand: a test booking paid with a test card on the preview, confirmed, then cancelled and refunded.
*Said by: the advice.*
### JTK_W_WORD_UNKNOWN
A row of `words` in the bookings settings names a key the platform's dictionary does not have, so the word is said nowhere.
**What to do:** The keys are the dictionary's — `letter.subjectConfirmed`, `diary.done`, `owner.new` and the rest, listed in the modules reference. A typo in a key is a word that silently never appears.
*Said by: the advice.*
### JTK_W_KIND_NO_DAYS
The bookings settings name the hours a stay goes out and comes back at (`hand_out`, `hand_back`), and not one of the services is sold by the day — the hours frame nothing, and it can only be booked by the hour, like a salon.
**What to do:** Give at least one service `scale: daily` — «Доба», «Ніч» — or leave its `scale` empty with the settings' `scale: daily`; the kit of the kind has them. Rates by the hour beside a daily one — a photo session and a day's hire of the same van — are the ordinary case and nothing is said about them. A business that hands a key over by the hour — a boat — says `hands_over: true` without the hours, and is not advised.
*Said by: the advice.*
### JTK_W_KIT_BEHIND
`kit` and `kit_version` in a module's settings — the bookings' or the shop's — say which kit the site was laid out from and when, and the kit has changed since — a fix to it, or to a part it shares with other kits, that this site has not got.
**What to do:** Read the kit's page (jtakeit:///kits/.md, or /v1/kits/; the shop's kit is `shop`) and carry over what this business needs of what changed — the finding names the changes the kit records; then set `kit_version` to the version the finding gives. The site is yours: nothing is changed in it for you, and nothing is refused on this.
*Said by: the advice.*
### JTK_W_UNPRICED_HOURS
A service priced by the hour of the week (`rates` instead of `costs`) is open, by the hours in the bookings settings, at hours none of its rows prices — and an hour nobody priced is not sold: the form does not offer it for this service, and a page that asks for it is refused.
**What to do:** Add a row for the hours the finding names, under the service's `rates`, or narrow the opening hours. A table copied from a website has a gap somewhere; this is where it is found rather than by a customer who could not book Tuesday noon. The panel says the same beside the rate, in the owner's language.
*Said by: the advice.*
### JTK_W_DIARY_UNSET
The site takes bookings and its settings say no time zone (`zone`) or no opening hours (`hours`): until both are set the diary refuses every visitor — `/api/availability` and `preflight`'s try_booking answer JTK_E_DIARY_NOT_READY — and the form shows «nobody has said which timezone this business keeps». A draft may be unfinished, so nothing is refused; this is said so the gap is not found by a visitor.
**What to do:** Set `zone` from the business's address — `Europe/Zurich` for Zürich — and `hours` from what the business publishes, in the bookings settings — `jtk/modules/bookings.json`, or `jtk/bookings.json` on contract 2; or leave them for the owner, under Diary → Opening hours, and say so. Then `preflight` with `try_booking`.
*Said by: the advice.*
### JTK_W_SESSION_OUTSIDE_HOURS
A bookable's own hours — a class's times in a sessions kit, a master's or a room's own week — reach outside the business's opening hours that day, and the diary offers only the part inside them (it clips one to the other, as the panel's diary shades): a class at 18:00–19:15 on a day the business closes at 18:00 is offered never, and nothing else says why.
**What to do:** Widen the opening hours in the bookings settings — `jtk/modules/bookings.json`, or `jtk/bookings.json` on contract 2 — to hold the row, or move the row inside them. The finding names the row and the hours it meets. Advice, not a refusal: the hours are the owner's and the panel may already say otherwise.
*Said by: the advice.*
### JTK_W_ADDON_ALONE
A service with no `takes` and a price is an add-on — shoes, a racket, a towel — taken only beside a timed service in one visit (wiki/70), and this site's bookings take one service per visit (`combine` off in the bookings settings), so nobody could take it.
**What to do:** Turn `combine` on in the booking settings, so a visitor picks the lane and the shoes together; or give the service a `takes` if it is a service of its own.
*Said by: the advice.*
### JTK_W_OWNER_LOCKED
A field holding a date, an hour or an amount of money is not `client_editable`, so the owner cannot change it: the next event's date, the hour the doors open, a price — facts of the business that change on its calendar, and that the studio is then asked to change every time.
**What to do:** Make it `client_editable: true`. If it is not on the page — an hour a countdown counts to — give it `no_tap_target: true` and `beside` the field it belongs to. Leave it the studio's only when it really is the design's, and say so to the developer.
*Said by: the advice.*
### JTK_W_HIDDEN_UNEXPLAINED
A field the owner edits is not on the page (`no_tap_target`) and names nothing it belongs to (`beside`) and says nothing about itself (`hint`): the panel shows it under More, at the foot of the editor of every field of its block, by its label alone, and the owner has to guess what it changes.
**What to do:** Put it `beside` the field the owner taps that it belongs to — a photograph's description beside the photograph, the hour beside the date — or give it a `hint` that says what it does on the page: «The countdown on the ticket counts to this hour».
*Said by: the advice.*
### JTK_W_LINK_NOT_BESIDE
A link the page does not show (`no_tap_target`, a `url` or a key ending in `href`, `link` or `url`) names no field it belongs to (`beside`). The panel opens it under its button by the names alone — the words field named alike (`cta_href` with `cta_label`), or else the one field whose key says `cta` or `button` — and where that names one field, says which; where it names none or two, the link is under More with the block's other values, a step from the button it is about.
**What to do:** Say `beside` the key of the button's words: `"cta_href": {"kind": "url", "no_tap_target": true, "beside": "cta_label"}`. The finding names the field the panel would pick, or that it cannot.
*Said by: the advice.*
### JTK_W_CONTENT_ORPHAN
A content file carries a block type, or a field, that the schema does not describe — text the panel cannot show and the build cannot annotate. Or a whole file sits where the site's contract keeps nothing: in a tree whose schema is `jtk/schema.json`, a page in contract 2's places, under `jtk/content/`, or settings at contract 2's `jtk/.json`, which nothing reads.
**What to do:** Either the schema lost a block or a field the content still has (declare it again, or rename the content's key to the new one), or the content names a type this site never had. Import keeps it rather than dropping it; `validate_schema` by ref says it so the commit is not the first to find out. A file nothing reads: move what it says to where the contract keeps it — `jtk/pages/`, `jtk/entries//`, `jtk/modules/` — or delete it.
*Said by: the advice.*
### JTK_W_CONTENT_BOUNDS
A value in a content file is longer or shorter than its field allows, or a list has more or fewer rows than it may — the panel will refuse to save the field as it stands, though the build serves it.
**What to do:** Shorten or lengthen the value to the field's `min`/`max` (the finding names the path), or widen the bound in the schema if the content is right and the bound is not. Nothing is refused on this; the owner meets it on the first edit.
*Said by: the advice.*
### JTK_E_SCHEMA_UNREADABLE
`jtk/schema.json` is not JSON, or a value in it has the wrong shape — words where a number goes, a list where an object does. Nothing else in the file is read until it is.
**What to do:** Fix what the finding names: it says where, and what that place takes. The file is read as contract 3 because it says `"contract": 3`.
*Said by: the schema, since contract 3.*
### JTK_E_SCHEMA_EMPTY
The schema declares no block types.
**What to do:** Declare the block types the site's pages are made of. A schema with no blocks describes nothing an owner could edit.
*Said by: the schema, since contract 3.*
### JTK_E_SCHEMA_KEY_UNKNOWN
The schema says a key contract 3 does not have, at any depth: a typo, or a word of contract 2's that contract 3 replaced — `business_facts`, `deprecated`, a collection's `prefix` or `body`, `option_labels`, a view's `sample`. Every one is said at once, each at its place.
**What to do:** Remove it, or say it in contract 3's words: a collection's `prefix`, `pages`, `listing` and `per_page` are its `route`, its `body` is `blocks`, an option's words are its `label` in `options: [{value, label}]`, a field is retired by removing it, and the business's facts are shared text with roles. A key is refused rather than dropped, so nothing is lost by being told.
*Said by: the schema, since contract 3.*
### JTK_E_ROUTE_INVALID
A collection says nowhere, or somewhere that cannot be, where its entries are: no `route`, a `detail` without `{slug}` or that is no address, a listing with a slug in it, `"none"` with no `shown_on`, a pattern for a language the site does not have, or two collections whose entries would share addresses.
**What to do:** Give each collection a `route`: `{"detail": "/works/{slug}"}`, with `"listing": "/works"` and `per_page` where a page lists them — or `"none"` with `"shown_on": ["/prices#{slug}"]` for entries shown only on another page. A pattern written per language names the site's own languages and says what follows the language's prefix.
*Said by: the schema, since contract 3.*
### JTK_E_REF_INVALID
A reference points nowhere, or where no reader follows it: a `ref` with no `to`, a collection named twice, an `on_delete` other than `restrict` and `nullify`, a ref written as contract 2 wrote it — or a group or a tree through a reference to several collections or several entries, which nothing groups by yet.
**What to do:** Write `"ref": {"to": ["categories"]}`, with `"many": true` for several entries. A group is a reference to one other collection, one entry each; a tree is a `parent` that is `{"to": []}` and nothing more.
*Said by: the schema, since contract 3.*
### JTK_E_SHARED_INVALID
`shared` names a block type the schema does not declare, or names one twice; or a field says a `role` that is not one of the list, sits outside the shared text, or says a role another field says already.
**What to do:** List in `shared` the block types the shared document holds. Give a `role` — name, phone, email, street, postal_code, city, region, country, maps, social, price_range, business_type, hours — only to a field of one of those types, and each role to one field: the business's structured data is built from them.
*Said by: the schema, since contract 3.*
### JTK_E_ATTRIBUTE_INVALID
A field says an attribute its kind does not take, or a value the attribute does not have: `localized` on a kind with no language, `integer` on anything but a number, `qualifiers` on anything but money or besides `from` and `on_request`, an `untranslated` that is neither `base` nor `hide`.
**What to do:** Say `localized` on text, a picture, a link or a list; `integer` on a number; `qualifiers` of `from` and `on_request` on money; a collection's `untranslated` as `"base"` or `"hide"`. Each may be left out, and then the kind's own answer stands.
*Said by: the schema, since contract 3.*
### JTK_E_SKU_TAKEN
Two variants on the site share a SKU, compared without regard to case, hidden products included.
**What to do:** A SKU names one variant on the whole site: stock and orders are kept by it. Give the later variant its own SKU; `FOX-S-RED` and `fox-s-red` are one.
*Said by: the schema, since contract 3.*
### JTK_E_PICKS_INVALID
A variant's `picks` do not name one value of each of its product's options, or two variants pick the same.
**What to do:** Name every option once, by its `_key`, with the `_key` of one of that option's values; a product without options picks nothing (leave `picks` out or `{}`). Two variants cannot pick the same values.
*Said by: the schema, since contract 3.*
### JTK_E_PRODUCT_INVALID
A product is outside the shop's limits, or a customization lacks what its kind needs.
**What to do:** A product has 1 to 2,000 variants, and a value in each option. A `choice` customization has at least one choice, a `text` one a `max` of 1 to 500 characters, and `choices` belong to a `choice` alone; a `yes_no` is ticked or not, so it is never `required` — a buyer who must answer is asked a `choice`.
*Said by: the schema, since contract 3.*
### JTK_E_UPCAST_INVALID
A block type's `upcast` says a step that cannot be one: `from` a version the type has not had (each step is from 1 up to one below the type's `v`), two steps from one version, a name that is not a field's, a rename of two fields into one, or a last step that writes, renames into or changes the rows of a field the type does not declare now — or drops one it still does.
**What to do:** One step for each older version content may still be written at, `{"from": 1, "rename": {"heading": "title"}}`, each making that version the next; the last one makes the block the type as it is declared now, so every name it writes is one of its fields. A version that changed nothing stored content feels still says its step, empty: `{"from": 2}`.
*Said by: the schema, since contract 3.*
### JTK_E_PANEL_FORM_INVALID
An entry type's `form` — how the panel lays out its card and a new entry — cannot be drawn as written: it names a field the type does not declare, `body`, or one field twice; a row holds more than three fields, spans more than six columns, or shares what is left unevenly; a gallery, a list or a document shares a row; a paragraph, a gallery or a list stands in the aside; a widget is not one of its field's kind or does not fit it; a required field has no place (but for one a module's own card draws, which no form lays out); or `form` is on a block type that is no collection's `type`. The sentence says which, at its place.
**What to do:** A form is `{"sections": [{"title": …, "note": …, "rows": [["title"], ["takes", "costs"]]}], "aside": ["photo"], "widgets": {"category": "segmented"}}`, every key optional. A row is one to three keys, or `{"field": "title", "span": 4}` on a grid of six; a cell without a span shares what is left. Place every required field — all but the ones a module's own card draws, as the shop's product card draws `variants` and the rest of a product's options and *Advanced*; leave `body` out — it is written beside the page. The [schema reference](catalogue.md#a-form) lists each kind's widgets.
*Said by: the schema, since contract 3.*
### JTK_W_NOT_LIVE
The schema does not say `render: "live"`: the template does not draw a draft at request time, so the owner sees a change in the panel's preview only after a build, and an entry's card cannot be previewed before it is saved.
**What to do:** Keep the scaffold's `src/live/` and `RENDER = 'live'`, and write every page so a server can draw it: content read through the door (`site.*`), pictures through the kit's helpers and the library, nothing in a page that only a build can do. Leave it out only where a page does at build what a server cannot and cannot be rewritten — and say why in `BRIEF.md` (the kit's docs/live.md).
*Said by: the advice, since contract 3.*
### JTK_W_DATE_HIDES
The site's template compares an entry's date with the clock to choose what it shows — the next night, the ones left out, the ones marked past. A build freezes that comparison until the next build, a visitor sees what is over as ahead, and the panel, which cannot know, shows it as on the site. Said by the kit's `jtk schema`, from the site's code.
**What to do:** Declare `ends_by` on the collection — `then: keep` to keep past entries as an archive, `hide` to take them off — and read `ended` from the entries the door gives (`site.entries(…)`): the platform says when each is over and rebuilds the site then. A countdown in the visitor's browser is drawing, and may stay.
*Said by: the advice, since contract 3.*
### JTK_W_PANEL_FORM_GUESSED
The panel placed fields of an entry type by itself: a `form` places no row for some — they are drawn after its sections, under More — or a type of seven fields or more says no `form`, and the panel lays them out in their order, short ones two to a row and pictures aside. The fields a module's own card draws are the exception: no form lays them out and the count leaves them out, so the shop's product type is not advised for its eight — and a `form` that places one of them is, since the panel leaves it out of the form all the same.
**What to do:** Say where each field stands: put the ones under More in a section's rows or the aside, or write a `form` that groups what belongs together — the price beside the length, the portrait aside, the words for the page under a title of their own.
*Said by: the advice, since contract 3.*
### JTK_E_UNNAMED
A page or an entry has no `id`, or a block, a row of a list or a gallery's picture has no `_key`, that an annotation can name — an id is a lowercase UUID, a key a lowercase letter and then lowercase letters, digits and hyphens. Nothing in it can be annotated, so the owner taps it and nothing opens.
**What to do:** Run `jtk schema` (`jtkit schema` on another generator), which mints every name that is missing. One that is misspelt is renamed by hand, here and in every file that names it. The platform's own saves mint them, so only a file written by hand lacks one.
*Said by: the build, since contract 3.*
### JTK_E_META_INVALID
The build's `dist/_meta.json` says what the platform does not read: it is not a JSON object, it holds `drafts` — which contract 3 removed — or a key other than `redirects`, `immutable` and `cache`, or one of those in a shape the platform would pass over.
**What to do:** Write `redirects` as `[{"from": "/old", "to": "/new", "status": 301}]`, `immutable` as the directories whose files are named by their contents, and `cache` as `[{"prefix": "/clips/", "maxAge": 86400}]`, and nothing else. Leave `drafts` out: which entries a visitor may not see is the platform's to say, from each entry's `visible` and its moments.
*Said by: the build, since contract 3.*
### JTK_W_DRAWN_UNTAPPABLE
A value the owner edits is drawn as text where nothing answers a tap: under `data-jtk-fixed`, or under no annotation at all — the business's name in a © line, a postcode joined to its city. Matched as the whole value, four characters or more, on the pages its document is drawn on; the shared text's on every page of its language. Advice, never a refusal.
**What to do:** Draw it with its path (`{...facts.at('postal_code')}`), each value in an element of its own where two were joined; where it cannot be told apart, put the element in a region that names its source, `data-jtk-from` (`{...facts.from()}`), so a tap opens the source. Words that only look like the value — the design's — are left as they are.
*Said by: the build advice, since contract 3.*
### JTK_W_TEMPLATE_DESIGN
The site's design path is custom — the person gave their site or sites they like and wants a design of their own (`create_site`'s `design`) — and the site still wears the template's design: more than 60 % of the scaffold's design files (its components, styles and layouts, the forms and the kit's galleries, motion and helpers aside) are byte for byte the kit's, or its hero, header and footer all are. Recoloured tokens are not a custom design. Counted on every build (`design` in the build's answer: untouched, of, the files); said only where the path is custom. Advice, never a refusal.
**What to do:** Rewrite the hero, the header, the footer, the sections and their composition from `DESIGN.md` — the short design brief at the site's root, written from the person's site and the references: palette, type pairing, grid and spacing, how photographs are treated, the sections' rhythm, motion (the kit's docs/compositions.md is the vocabulary) — and delete the template's files the site no longer draws. Or, if the person accepts the quick template adapted, tell them exactly that: never call a recoloured template custom.
*Said by: the build advice, since contract 3.*
### JTK_W_DESIGN_AXES
The site's design path is custom and `jtk/design.json` chooses fewer than ten of the fourteen axes — a choice is a line of three words or more, what and from where; a tag like `split` or `linen` is not one — the hero, the ground, the measures, the shape, the header, the phone's menu, the overlap, the surfaces, the mark, the motion, the fonts, the hook, the proof, the contact — or no `mark`. Where the site shows directions, the first one's axes are counted. A design nobody chose on falls back on what a model reaches for first. Advice, never a refusal.
**What to do:** Choose on every axis of the design guide (`docs/guides/design.md`, «The axes») from the business's own material — the mark first: a motif from their material, repeated in the interface — one short line per key under `axes`, and the reasons in `DESIGN.md`.
*Said by: the build advice, since contract 3.*
### JTK_W_DIRECTIONS_ALIKE
Two of the directions in `jtk/design.json`'s `directions` differ on fewer than three axes, or not on the hero: the person is shown one design in other colours and asked to choose. Advice, never a refusal.
**What to do:** Make each direction a design of its own — another hero, another shape, other surfaces, another mark — at least three axes apart, the hero among them; write each direction's choices under its `axes`.
*Said by: the build advice, since contract 3.*
### JTK_W_FIRST_SCREEN
On the home page the heading or the first action ends below the first screen — a phone 390 × 844 or a desktop 1280 × 800 — so a visitor sees a picture and not what the business does or how to book it. Measured in a browser by `preflight` (the floor's F8). Advice, never a refusal.
**What to do:** Bring the heading and the one action onto the first screen at both widths: a shorter picture above them, the words over the photograph, or the photograph beside the words; `get_built_page` with `shot` shows the fold.
*Said by: the advice, since contract 3.*
### JTK_W_ANCHOR_LANDING
A link in the home page — the header's `#angebot`, `#kontakt` — scrolls its target to where its first words land more than 96 px below the header, across the section's own top padding, or under the header. The visitor arrives at air, or at a cut heading, and scrolls again. Measured in a browser by `preflight` at a phone's and a desktop's width. Advice, never a refusal.
**What to do:** Give each target `scroll-margin-block-start`: the header's height and a little air, less the section's top padding — the kit's layout writes `--header-h` — so the first words land just under the header; or put the `id` on the section's heading instead of the section.
*Said by: the advice, since contract 3.*
### JTK_W_SCREEN_FIT
On a desktop (1280 × 800) a section of the home page is a little taller than the screen under the header — by less than a third — so it is never seen whole; or a form, with its heading, is taller than that screen and its button is out of sight while it is filled. Measured in a browser by `preflight`. Advice, never a refusal.
**What to do:** Tighten the section to a screen: a shorter picture, less padding, two columns. A form: fields side by side, a shorter message box, the lead beside the form rather than above it. A section long on purpose — a price list, a journal — is left as it is.
*Said by: the advice, since contract 3.*
### JTK_W_RAGGED_GALLERY
A wall of four or more pictures on the home page ends ragged: its columns end more than 24 px apart — a masonry of mixed proportions, or a last row left half empty. Measured in a browser by `preflight`. Advice, never a refusal.
**What to do:** End the wall on one line: rows of one height (each picture its own width), one proportion for every picture, or one picture spanning two cells to fill the gap; or fewer pictures, a count the columns divide.
*Said by: the advice, since contract 3.*
### JTK_W_BOOKING_LINK
A button on the home page — the header's «book» — opens another page of the site at its top, and that page's booking form starts more than half a screen down: the visitor who asked to book scrolls to find it. Measured in a browser by `preflight`. Advice, never a refusal.
**What to do:** Link the button to the form itself: the page and the form section's anchor — `/services/#book` on the kit's price page; give the section an `id` where it has none.
*Said by: the advice, since contract 3.*
### JTK_E_DOCUMENT_INVALID
A document under `jtk/pages/`, `jtk/entries/` or `jtk/modules/` is not where it says it is, or not what contract 3 writes: a page without its `name`, a `path`, `collection` or `slug` that disagrees with the file's place, no `id` or a block, row or picture without a `_key`, a key a document does not have, `seo` on an entry with no page of its own, a `shown_on` page that is not there, a folder or a segment named `media`, a value in contract 2's shape (a price as a bare number, a picture as its key, a reference by slug), a reference naming an id no entry of its collections has, or a module's settings that are not `{v, settings}`.
**What to do:** Fix the file where the finding points; a reference to an entry that is not in the tree is refused (`on_delete` is `restrict`), so put the entry back or take its id out. An entry deleted in the panel is taken out of every reference to it by the deletion itself, and the files that named it come with the next save — pull before you push; an entry deleted in the tree leaves them to you. A page is `{id, path, name, seo?, blocks}` at `jtk/pages/.json`, an entry `{id, collection, slug, visible, fields, blocks?}` at `jtk/entries//.json`, a module's settings `{v, settings}` at `jtk/modules/.json`; every block, row and picture has a `_key`, a price is `{"minor": 4500}`, a picture `{"src": …}`, a reference the entry's `id`. `jtk schema` (`jtkit schema` on another generator) mints the ids and keys a file lacks.
*Said by: the platform, since contract 3.*
### JTK_E_BLOCK_BEHIND
A block in a document says a `v` its type's steps cannot bring to the type's own: an older version with no `upcast` step from it, or a version newer than the schema's type — content written against a schema that has not arrived.
**What to do:** Declare the step from that version in the type's `upcast` (the finding names the block, its `v` and the type's), and the platform brings the block up when it reads it and the next save writes the current `v` — or rewrite the block in the current shape and give it the type's `v`. A block newer than its type is a schema that was not pushed with its content: push them together.
*Said by: the platform, since contract 3.*
### JTK_E_CURRENCY_SET
A contract-3 tree's `jtk/site.json` says a new `currency`: neither the site's own nor the one the platform's last save wrote there. An import takes the currency from that file only while the site has none — as `create_site` takes it in `currency` — and once a site has its currency, a person changes it in the panel. A branch still carrying the last save's currency, from before a person changed or cleared it, is not refused: it is left, and the next save writes the site's.
**What to do:** Write the site's currency there (`get_site` says it), or leave `currency` out of `jtk/site.json`. If the prices really are in another currency, ask a person to change it in the panel — The site → The business, the currency — which asks first on a site with prices; the next save writes it into the file. `validate_schema` says this before the import does, in both its forms: by site and ref, or with the tree as text — `schema`, and `files` with `jtk/site.json` — and the site in `site_id`. Where the site's code is on jtakeit, `push_code`'s push is the import, so send the text with `site_id` before it: without a site there is no currency to hold the file to, and nothing is said.
*Said by: the platform, since contract 3.*
### JTK_E_SKU_ORDERED
A variant whose SKU a paid order named lost it, or the SKU was given to a variant it was not named for. Stock and orders are kept by the SKU, so a SKU an order named sits only on a variant it was named for, or on none, and a variant an order bought carries one of the SKUs orders named for it: the save, `import_branch` and `validate_schema` (by site and ref, or with the tree's files and the site in `site_id`) refuse the draft or the tree that moves it, naming the variant. A checkout never paid, one that lapsed and a test order name no SKU; an order gone at its retention names none either.
**What to do:** Keep the SKU on its variant — or, where orders named the variant under more than one SKU, any one of them — and give any other variant that has it a SKU of its own; a variant that is not to be sold is taken off sale (`on_sale: false`). A variant or a product may be removed, and a product hidden, and their SKUs are never given to another variant. No tool reads orders, so the finding is how an agent learns which SKUs an order named; a variant no order has bought may be changed freely.
*Said by: the platform, since contract 3.*
### JTK_E_TRANSLATION_SHARED
A translation — `..json` beside its original — says a value that is the same in every language: a price, a number, a date, a choice, a reference, a phone number, a link, a picture's file, focus or poster. A translation holds only the words; the translation of a shared value is the original's, everywhere, so a photograph changed in one language is changed in all of them.
**What to do:** Take the value out of the translation and keep it in the original. If the value really differs per language — a photograph with words on it, a link to a page in that language — say `localized: true` on the field in `jtk/schema.json`; a text that is a name and never translated says `localized: false`.
*Said by: the platform, since contract 3.*
### JTK_E_TRANSLATION_RECORD
A translation's `translated` holds a record that is not one. A record is `{from, by, at}` under a value's path in the file — `from` the eight hex digits of the digest of the original's value the translation was made from, `by` `person`, `agent` or `machine`, `at` a moment in RFC 3339 — and nothing else. A record whose `from` is empty is read as none: a value whose original is empty has nothing it was made from.
**What to do:** Leave the record out — or `translated` whole: the import records each value the translation gives as made from the original as it stands, by the agent, and keeps the record it wrote for a value you did not change, which is how an outdated value stays outdated until it is translated again. Write a record yourself only to say who made a value, with the digest the platform wrote.
*Said by: the platform, since contract 3.*
### JTK_W_TRANSLATION_ORPHAN
A translation gives words to a block, a row of a list or a gallery's picture by a `_key` its original has not got — removed in the original, or a key misspelt. Its words are shown nowhere, and the next save leaves them out of the file; the history keeps them.
**What to do:** If the original lost the block, the row or the picture on purpose, take its words out of the translation. If the key is misspelt, write the original's: a translation names what it translates by its `_key`, never by its place.
*Said by: the advice, since contract 3.*
### JTK_E_MACHINE_OFF
Translate, in the panel's languages, asked a deployment that translates nothing by machine: it has no DeepL key — staging until a person sets one, production until DeepL is named in the data processing agreement — or the site's other languages are copies (contract 2) rather than translations of one original.
**What to do:** Nothing an agent does: the machine is a person's, in the panel, and an agent is a translator in its own right — write the translation into `..json` beside its original, and the import records it. A person in the panel translates by hand meanwhile.
*Said by: the platform, since contract 3.*
### JTK_E_MACHINE_ALLOWANCE
The site's machine translation allowance is not enough for what was asked: a paid site's 30,000 characters of a calendar month, a demo's 10,000 once. What the cache already holds costs nothing and is not counted; everything sent to DeepL is.
**What to do:** Translate fewer texts at a time, or by hand — the line's own field — which costs nothing; a paid site's allowance starts again on the first of the month. An agent translates in the files and never through the machine.
*Said by: the platform, since contract 3.*
---
# When something is wrong
By symptom. Every refusal also carries a code, and
[the error reference](../reference/errors.md) has a section per code with what to
do about it — go there first if you have one.
## The client taps a heading and nothing opens
The element rendering that value has no `data-jtk-path`, or it has the wrong one.
This is the failure the whole annotation apparatus exists to prevent, because it
is silent: the page looks right, and only the editing is broken. A build should
have caught it with
[`JTK_E_UNANNOTATED_FIELD`](../reference/errors.md#jtk_e_unannotated_field) — if
it did not, the field is probably one the lint does not require an annotation
for, and the reason is one of:
- its kind is one the lint advises on for now — a phone, an email, a link, a
choice, a date, an hour, a number: the build log says
[`JTK_W_UNANNOTATED_FIELD`](../reference/errors.md#jtk_w_unannotated_field)
and goes on — or is not tapped at all, a list or a switch (see
[field kinds](../reference/field-kinds.md));
- the field is `client_editable: false`, so there is no tap to break;
- it is `no_tap_target` and drawn anyway — the log says
[`JTK_W_DRAWN_UNTAPPABLE`](../reference/errors.md#jtk_w_drawn_untappable)
where it finds the value as text;
- the value is empty, and the lint only looks for annotations on values that
exist.
## The build fails and the log is about the schema
The schema in the repository is not the one you judged. Two common causes: it
was not committed, or it was committed on another branch. Read the build log for
the code and look it up.
A build with **no** schema at all fails with
[`JTK_E_CATALOGUE_MISSING`](../reference/errors.md#jtk_e_catalogue_missing) — the
lint refuses rather than skipping, because a lint that quietly passes when it
cannot find its schema is worse than no lint.
## The schema was fine yesterday and is refused today
Check the contract number in the finding. A schema written for a **higher**
contract than the service speaks is refused deliberately and completely —
the service is behind, and this is a deploy rather than a repository to fix. A
schema written for a lower one is upgraded silently and never produces this.
## A translation is refused, or a language shows the original's words
A translation (`..json` beside its original) holds only words.
A price, a photograph's file, a date or a link in it is refused with
[`JTK_E_TRANSLATION_SHARED`](../reference/errors.md#jtk_e_translation_shared):
change it in the original, or say `localized: true` on the field if it really
differs per language. A record in `translated` the import cannot read is
[`JTK_E_TRANSLATION_RECORD`](../reference/errors.md#jtk_e_translation_record):
leave the record out, and the import writes one. Words for a block or a row
the original no longer has are advice,
[`JTK_W_TRANSLATION_ORPHAN`](../reference/errors.md#jtk_w_translation_orphan),
shown nowhere: the key is misspelt, or the original lost the row.
A page in another language that shows the original's words is a value nobody
translated yet, and the page says so with the original's `lang`. `get_site`
lists each one with its file and path ([a site in several
languages](languages.md)). A service or a master shown in the original's words
in every language is the rule, not a fault: what is booked is never held back.
## A field exists in the schema and the admin does not draw it
The site is being served a different schema than the one in your working tree.
The stored schema is a **replica, pinned to the last publish** — the admin
draws what was published, not what is on your branch. `get_registry` returns the
one actually in force; compare it against your file.
A site that has never published, and is not the studio's own, has no schema at
all and is an error rather than a default. That is on purpose: falling back to
our eleven scaffold blocks would describe a stranger's site not at all.
## Publishing is refused because of enquiries
A block declares `"collects": "enquiry"` and the site has no verified
destination. Add one — a Telegram chat, an email address, or the admin's inbox —
and verify it.
The gate is derived from the schema rather than configured, so it cannot be
switched off; the way out is to name a destination, or to stop collecting.
## A test enquiry does not arrive
In order:
1. Does a block actually declare `"collects": "enquiry"`?
2. Is a destination **verified**, not merely added?
3. Is the form posting to `/api/lead` on the site's own host?
4. Is the honeypot field being filled by something? A form that fills its own
hidden field is silently discarded, which is exactly what it is for.
`preflight` walks the whole path with a probe the edge accepts and drops;
with `send_real_enquiry` it sends a real one the client will see, and says
where it arrived.
## The preview link does not work
Preview links are capability URLs with a short life. They expire, and they are
credentials while they live — anybody holding one can see the preview. Mint a
fresh one rather than debugging an old one.
## The build log says a host was refused
`JTK_E_BUILD_REACH`, with the request and the list. A build has no network of
its own; the platform forwards the clone, the npm and yarn registries, the
media host and Google Fonts, and refuses everything else
([the network](connecting-a-site.md#the-network)). Find what asked: a
dependency whose install downloads a binary from a release (pin one that
ships its binaries as packages — sharp since 0.33, esbuild, lightningcss all
do), a font fetched from a CDN (put the file in the repository, or use Google
Fonts), a fetch to a service at build time (that content belongs in `jtk/`).
The build is not retried on its own: fix the source and commit.
## The build log says GitHub asked us to slow down
Many builds asked GitHub for repositories at once, and it answered 429. The
build waits and asks again — after 5, 15 and 40 seconds, or as long as
GitHub's `Retry-After` asks, up to a minute — and a log that goes on past
those lines is a build that got its commit. One that GitHub turned away every
time fails with a sentence saying so: nothing in the site is wrong, build
again in a few minutes. A 5xx from GitHub is waited out the same way. A
refusal (401, 403, 404) is not: check that our GitHub App is still installed
on the repository.
## A tool says "too many requests"
`JTK_E_RATE_LIMITED`, a 429 with `retry_after` — the seconds until there is
room again, the `Retry-After` header too. The platform takes 9 000 requests a
quarter of an hour from one account, its people in the panel and its agents
together, and 1 200 from one address without a session
([the error reference](../reference/errors.md#jtk_e_rate_limited)). Nothing
was done; wait the seconds it names and the same call works. A loop is the
usual cause: a `get_build` asked again the moment it answers, a `get_site`
before every step. Wait a few seconds between polls.
## The build says a file was not published
`not published: .env, …` in the log, `withheld` on `get_build`, and preflight
failing *nothing in the build that is never published*. A path with a part
that starts with a dot — `.env`, `.env.backup`, `.git/`, `img/.DS_Store` — is
never served, `.well-known/` at the root aside: the upload leaves it out and
the address answers 404. The build still succeeds. But the file came from the
repository, usually from `public/`, so it is in the repository's history.
Remove it there and commit; if it held a key, a token or a password, change
that secret too, because deleting the file does not take it out of the history.
## A rollback keeps undoing itself
It does not: the rollback holds the site on the build it chose, and only a
person lifting the hold in the panel, and then publishing, moves it on. A
build of a newer commit lands as the candidate meanwhile, with
`JTK_E_PUBLISH_HELD` in its log. The artefact and the repository disagree
until the source is fixed — see
[draft, version, live](the-three-stages.md#rolling-back).
## The site answers 503 and the panel says it is switched off
Either the studio switched it off (**The site → Switch off**, with a reason
only the studio sees) or the lapse ladder did, on day 30 of an unpaid
subscription — the reason then reads `lapsed: …`. The first comes back with a
press; the second the moment the subscription is paid, within the minute.
[The panel](the-panel.md#when-a-subscription-is-not-paid) has both ladders.
## Editing is refused with "this site is frozen"
Day 14 of the lapse ladder: reading and export work, writing does not. Two
sentences, two payers. *Its subscription has not been paid* is the studio's
plan with us, under **Reselling**. *The payment to the studio that runs it
is overdue* is the owner's invoice to the studio, paid from the owner's
**Subscription** screen. Paying thaws; nothing else does.
## Launching is refused: "needs one site in this studio's plan"
The plan is short by one line of the kind named — a site, a diary or a shop.
**Reselling** sells one more; a site costs nothing until
then, so this arrives on the day the site goes live rather than before. The
same sentence refuses turning the diary or the shop on for one more site and
billing one more client.
## A visitor cannot book, and the diary says what is missing
Two halves, and the sentence names which. *This site's schema does not turn
bookings on* is the repository's — `modules.bookings` and its two collections,
then commit, import, build. *Nobody has said which timezone this business
keeps* / *when this business is open* is the owner's — **Diary → Opening
hours**, then *save and publish*. *Nothing in the services collection says how
long it takes* is an entry without `takes`; *the resources collection has
nothing published in it* is nobody to book with. `preflight` says all of them.
## A buyer cannot buy, and the shop says what is missing
Two halves again, and what a buyer is told names which. A product **sold out that
never sold** is a counted product nobody stocked: `set_stock` sets the count, or
the product says `tracked: false` where it is made to order. **No way to send it** is
the shop's settings — a country no zone names (`sends` is false in the shipping
answer), a method no parcel of this size or weight fits (`cannot_send`), or a method
with no price yet, which is a draft that `preflight` names; a pick-up is offered
whatever the country. **A checkout refused with `424 no_payee`** is the business
without a Stripe account to be paid into, which a person connects under
*Payments* — or, on a launched site, a studio's plan that holds no shop line for
it, which **Reselling** sells and the site's next publish takes; the cart is still
priced and an order already made still answered, and only a new order waits;
**`422 address`** is Stripe unable to work out the VAT for the
delivery's address, and the buyer checks it. **A page whose button does nothing**
has lost a hook — the element says in the browser's console which — and a cart or a
checkout field the page sent that the contract has not got is dropped for a
stranger and listed in `get_site`'s `shop_drops`
([`JTK_E_SHOP_FIELD_UNKNOWN`](../reference/errors.md#jtk_e_shop_field_unknown) to a
preview). `preflight` with `try_order` walks the shop's addresses as a buyer does,
not the page's hooks, which the element and `jtk a11y` find
([the shop on the site](shop-on-the-site.md#proving-it)).
## Payments cannot be set up: "say what country this business is in"
The country lives on **The site → The business** and is the first thing a
Stripe account needs. A country Stripe does not serve is refused by name, and
there is no second provider today. The same is true of a studio's own account
under **Reselling**, for billing its clients.
## Client billing refuses to start
*The studio's own payment account is not ready yet* — set it up under
**Reselling → Stripe account**, then wait for Stripe to say it may
charge. *The price… belong to the running subscription* — stop it and start
a new one; a running subscription is never silently resold.
## The handover is refused
Every reason at once, in one sentence. *The enquiries still go to an address somebody set up here* —
the owner adds their own destination and the studio's is removed. *The money
from this site still lands in the account somebody set up here* — the site's
Stripe account for bookings is the studio's; remove it. *The owner still pays
this studio for the site through us* — stop that subscription first, or the
client is billed twice. Fix each, then mint the link again.
## Still stuck
Get the code. Every judge in the system — the schema validator, the annotation
lint, `jtakeit doctor` — says the same code for the same fault, and
[the reference](../reference/errors.md) has one line of what to do for every one
of them. A symptom without a code is worth reporting as a gap.
---
# Driving it from an agent
jtakeit is built to be driven from here: the agent is the expected author of a
site, and the MCP server is how it reaches the platform from the session it is
already building in — judge the schema, attach the repository, build it, read
why the build failed, hand the client a link — without opening the admin.
Nobody is meant to hand-write the schema, the pages or the content; the
platform's job is to run what the agent wrote.
> The server is hosted and answers nothing without a token, and a token is only
> ever given when a person signed in to their account — a studio's, or a
> business's own — approves the connection.
## What the agent needs
A terminal and git beside the chat: Claude Code, Cursor, Codex CLI, or any
client that can run `npx @jtakeit/astro create`, write files and push a
repository. A site here *is* a repository the agent writes; its code reaches
the platform with `push_code`, or — for a site whose code is on GitHub — with
git and our GitHub App, which a person installs. An agent in a
browser tab alone — the Claude app with this server connected — has no
terminal: it reads and writes the site's code on jtakeit with `read_files`
and `write_files` instead, a few files a call
([Connecting a site](connecting-a-site.md#without-a-terminal)).
## Connecting
Two lines, and nothing is copied. The first writes the server down; the second
is the one that opens a browser, on the panel's own page, where you approve it:
```
claude mcp add --transport http jtakeit https://mcp.jtakeit.com/mcp
claude mcp login jtakeit
```
Inside a running Claude Code session, `/mcp` does what the second line does.
Any client that speaks MCP works the same way — give it the address and it finds
the rest; where the approval is started differs by client, and is usually a
button beside the server. Most configuration files take this shape:
```jsonc
{
"mcpServers": {
"jtakeit": { "type": "http", "url": "https://mcp.jtakeit.com/mcp" }
}
}
```
The first call comes back `401` with a `WWW-Authenticate` header naming a
discovery document; the client reads it, registers itself, and when it is told
to authenticate opens a browser, where you approve on a page that says what is
asking and where the answer goes. That is the whole of it — there is no key on
any screen, because there is no endpoint that issues one to a person.
**Somebody with an account approves.** The consent screen is in the admin and
needs the session you already sign in with: a studio's member, or a business
that signed up for its own site («My business has a site, or wants one») — its
agent works in that business's own account. Signing up in the middle of it is
fine: the authorization waits thirty minutes, and the sign-in email carries a
six-digit code to type on the same page, for a phone whose mail app opens links
in another browser.
### From claude.ai, the Claude apps, or ChatGPT
- **Claude** (claude.ai, the desktop app and the phone apps share connectors):
Settings → Connectors → Add custom connector, name `jtakeit`, address
`https://mcp.jtakeit.com/mcp`, then Connect and approve. The panel's first
screen for a business does this in one click.
- **ChatGPT**: until jtakeit is in ChatGPT's directory, only on the web and on
the Business, Enterprise and Edu plans (Pro can read, not write) — Plugins,
`+`, *Add custom MCP server*, the address under Connection, OAuth, *Create as a
plugin*, approve; in a chat, `@jtakeit`.
### What you end up holding
An access token that works in the account you approved it for — your studio's,
or your business's own — and belongs to **you**, the person who approved it:
when you leave a studio, your agents stop with
you, and a machine that has to outlive its installer is not what this is for —
and a refresh token that renews it. The access token
lasts an hour; the refresh token is rotated on every use, which means presenting
a used one is a copy in somebody's hands and disconnects the agent on the spot.
Your client does all of that without being asked.
`Settings → Agents` lists what is connected, when each was last used, and has a
revoke beside each one. Revoking takes effect on the next call.
## The tools
The [reference](../reference/mcp-tools.md) has each one with its parameters.
Grouped by what you are doing:
| | |
| --- | --- |
| writing a schema | `validate_schema`, `get_registry` |
| setting a site up | `list_sites`, `get_site`, `create_site`, `attach_repo` |
| building | `trigger_build`, `get_build`, `get_build_log` |
| shipping | `commit_and_build` — serving an earlier build is a person's, in the panel |
| showing somebody | `get_preview_link` |
| checking what is there | `get_content`, `list_entries`, `import_branch` |
| stocking a shop | `set_stock` |
| before a handover | `preflight` |
| working on this machine | `open_dev_session`, `send_dev_schema`, `get_dev_files`, `close_dev_session` |
Three of them take a second look before they act: `commit_and_build` with `dry_run`
says what it would add, rewrite and delete (`changed` when any of the three
names a file; `unpublished` when the draft holds what the published version
does not; `pending` when the branch holds content the panel has not taken —
a push over unsaved changes — which the save brings in under the draft first); `trigger_build` with
`kind: "candidate"` builds into the preview and not in front of visitors; and
`preflight` sends a real enquiry only when asked (`send_real_enquiry`),
walks the booking chain only when asked (`self_check`) — on rows the business
never sees, told to nobody — and places a test
order only when asked (`try_order`): on Stripe's sandbox, under your session, so the business
never sees it, and given back by Stripe's own message before it answers. With VAT on, the
parcel goes to the business's own address, and the test payment is taxed on the sandbox as a
live one would be.
`set_stock` sets the starting stock of SKUs that have not sold, one a line
(`FOX-S-RED 3`). Once a SKU has sold, its stock is the owner's, in the panel
(**Shop → Stock**): the tool leaves it as it is and names it. Nor can a push
move the SKU itself: one an order named stays its variant's, and the save,
`import_branch` and `validate_schema` refuse a draft that changes it or gives
it to another variant
([`JTK_E_SKU_ORDERED`](../reference/errors.md#jtk_e_sku_ordered)). A variant
that is not to be sold is taken off sale (`on_sale: false`); one removed, like
a product deleted, keeps its SKUs from every other variant.
`jtk import products` writes the stock of a catalogue it brings in to
`.jtakeit/stock.txt` (and `stock-2.txt` beyond 5,000 lines), one SKU and its count
a line, for this tool: send the text of each file as `stock` with the site's id,
and set it before anybody looks at the site, since a counted product is sold out
until its stock is set ([the shop on the site](shop-on-the-site.md#stock)).
`get_site` says what a stranger's shop page sent that the platform does not read,
in `shop_drops` — each name, where it was sent, how many times this month — as
`booking_drops` does for the booking page: fix the page, and try the checkout on
the preview with `preflight`'s `try_order` before anybody else uses it.
## What it will not do
> **An agent builds the machine. It does not read what the machine collected.**
Enquiries, the diary, the orders and the members are the client's own customers
and the people who can reach them. A credential living in a config file does
not carry them; open the panel as yourself.
**It does not write content.** No field writes, no page writes, no block writes.
Editing belongs to the client in the admin and to you in the repository, and a
tool that patched a field would be a third way of changing a site that nothing
else knows about.
What it does instead is the other direction. Write the content in the repository
where it belongs — versioned, diffable, reviewed with the code — and then
`import_branch` so the panel and the branch agree. **Do that before the next
save or publish**, or the draft is copied outward and writes over the commit.
**It cannot launch a site on its own domain**, and it cannot hand anybody a way
into a site. Both are decisions about people, and nothing in a config file makes
those.
**It has no studio verbs.** Suspending, promoting, archiving, the money, and
everything about how clients are found are not here and will not be. They are
all in the panel, and [the panel, by hand](the-panel.md) says which screen,
which person, and what has to be true first — so when somebody asks how to
launch a site, hand it over, or bill a client, the answer is *where*, not *no*.
**It cannot connect another agent.** A credential that can make its own
successor cannot be revoked: the one you kill has already made the next.
## A session that works
Judge, attach, build, look, show:
1. `validate_schema` with the schema `npx @jtakeit/astro schema` just wrote,
`jtk/schema.json` — as text, with the `jtk/` files (the translations
among them) and the site in `site_id`, or once it is pushed, by site and
ref, and nothing is pasted. Both forms hold the tree to the site as its
import does (a new currency is `JTK_E_CURRENCY_SET`); where the code is on
jtakeit, `push_code`'s push is the import, so judge the text before it.
Fix everything it says: it returns all findings at once, so this is one pass.
2. The code, as `get_site`'s `code_says` has it: `push_code` and the `jtk
push` it answers with, or — for a GitHub remote, our App installed by a
person — `attach_repo` once the repository is pushed.
3. `commit_and_build`, then `get_build` until it settles. It commits the draft as a
version and builds it, and says which files the commit changed (`files`);
nothing goes public, and on a launched site the build is a candidate a person
publishes. While the panel holds a person's unsaved changes it is refused
(`JTK_E_THEIR_DRAFT`, naming them): ask them, then `with_their_draft`, or
`branch_only` to build your commits and leave their draft. `trigger_build`
is for rebuilding after that.
4. `get_build_log` if it did not. Failures carry `JTK_E_` codes; look them up in
[the error reference](../reference/errors.md) rather than reading the prose.
5. `import_branch` if you committed content or changed the schema on a
GitHub repository, so the panel shows what the branch says (a `push_code`
push imports by itself). **You will be told if you forget**: a
publish whose draft has not seen the branch's content is refused with
`JTK_E_OUT_OF_SYNC` rather than overwriting it. The order is enforced, not
remembered.
6. `get_preview_link` and give the person the URL, with `label` saying whom it
is for. It works for seven days (`days`, up to thirty), shows the preview
and a test booking and nothing else, and never hands the site over — the
owner's link does that, from the panel. The studio sees it in the panel's
links and can reset it. Give it from the start — a person in a chat has no
localhost. Until something of yours is on the site — only the kit's
example is, `get_site`'s `look.shown_ready` is false — and before the
first build, it shows a screen saying their agent is writing the site,
with a build's step while one runs. After that it shows the draft drawn
live where `look.draws_live` holds: what you write into `jtk/` is there at
once, without a build, and a build is needed only when code changed
(`src/`, styles, components, packages). Kept open, it follows the draft
and each build by itself. After the first build, `get_site`'s
`panel.links` are the panel's screens this site has, to give the person
once.
7. `preflight` before you tell anybody it is done. It says what a person
would otherwise check by hand: a build is served, enquiries, bookings and
orders have somewhere to go and the diary can take a booking, the address
answers, nothing tells search engines to stay away, and the form delivers;
with `try_order`, that a shop takes an order and gives it back. On a
site that takes bookings, run it with `self_check: true`: the server walks
a booking through the whole chain on the build published now — booked as
a visitor, confirmed, refused, moved, another time offered and accepted,
«it suits», moved and cancelled by the customer, cancelled by the owner —
and reads every letter of it, on rows nobody sees or is told of. Fix what
a step names, publish, run it again; the site is not `ready` until the
walk has passed on the build published now. It does not check the form's
script (`try_booking` does), a letter's delivery, or the payment
(`JTK_W_PAYMENT_UNCHECKED`: tell the owner) —
[the brief](the-brief.md#before-it-is-handed-over-the-self-check).
Working on the template on this machine is a different loop —
`open_dev_session`, then `send_dev_schema` whenever the schema changes,
`get_dev_files` to commit what was typed, `close_dev_session` when done — and
[working locally](working-locally.md) has it in full.
On a site in several languages, `get_site` says per language what is still to
translate and what is outdated, document by document, with the file each
translation is in. You translate in those files and push them like any
content; no tool translates for you, and the machine translation the panel
will offer the owner is not yours to call
([a site in several languages](languages.md)).
Every result carries the contract number, so a transcript is still diagnosable
after the format moves.
---
# The panel, by hand
Everything the tools do not do, and where it is done instead. An agent that is
asked *how do I launch this, bill this, hand this over* should answer with a
screen and a person, not with *I can't* — and this page is that answer, one
section per thing.
Two people use the panel, and they see different screens at the same address:
- **the studio** — whoever's account the site belongs to; the people who build
and sell it. The studio's own screens are *Sites*, *Agents*, *People*,
*Reselling*, *Referrals* and *Account*.
- **the owner** — the business the site is for; a client of the studio, with a
role on that one site (owner, admin or editor). Their screens are the site's:
*Overview*, *Pages*, *Media library*, *Numbers*, *Enquiries*, *Diary*,
*The site*, *Subscription*, *Payments*, *People* — and *Shop* (*Products*,
*Orders*, *Stock*, *Shipping*) on a site that sells.
Which role may do which thing is one generated table:
[who can do what](../reference/who-can-do-what.md). The rule it comes from is
one sentence — *an editor touches the content and sees the numbers; an owner or
an admin touches the money, the domain and the people; the studio does what
"not a builder" means: structure, address, repository, launch.*
A studio member who wants to see a site as its owner does presses **View as
client** on the site's screen. The same screens draw with everything only the
studio can do taken out, which is how a studio finds out what the owner will be
asked before the owner is.
---
## The preview, drawn live
On a site whose template says it is ready — `render: "live"` in
`jtk/schema.json`, which a site laid out by `npx @jtakeit/astro create` says
from its first commit — the preview in the panel shows the draft as it is
written into the draft, before a version is saved: a field the owner types is
in the frame, drawn by the site's own code, within about a second of being
written, and so is what the overlay cannot draw — an entry just added, a new
order, a post in its listing, a post's whole text. Everywhere else
the preview shows the last build with the draft's words laid over it: a
write into the draft builds nothing, and an entry added appears in the frame
once *Save a version* has made a version and its build is done, ten to twenty
seconds later.
- **Who sees it.** The site's own people editing it in the panel, and the
same people opening *Preview* in a tab, which shows the draft as a visitor
will see it (below), and the link an agent gives the person it works for
(`get_preview_link`): it shows the draft as a visitor will, follows it as
the agent writes, and says *Draft, live* or *Latest version* on its badge in
the page's language. Until the agent has written anything of its own it
shows a screen saying so instead of the kit's example. A preview link a
studio hands a client, the version, the candidate, the showcase and the
site's own address all show the build.
- **What is checked.** The platform does not take the word for it: every
preview build makes the site once more for a server and draws a few of its
pages with it; where one differs from the built page beyond the names of the
files it links and the size of its pictures, the build's log says which page
and where (`live: not drawn live — …`), and the preview shows the build until
the code changes. Nothing fails because of it.
- **When it is the build anyway.** The first page after a while is the build:
the site's renderer starts on it and draws the next. A renderer that is slow,
busy or wrong is the build too. The frame says nothing about which it was; a
tab opened with *Preview* waits longer for the draft, and where it is shown
the version instead its badge says so — *Preview · Version*, the draft could
not be drawn just now — and a reload asks again.
- **Pictures** uploaded since the last build are shown as uploaded, at full
size and at their own proportions (the library tells the renderer each
one's width and height); the build optimises them.
- **What is published** is always the build. Drawn live is only how the panel
shows the draft; *Publish* puts the build of the saved version live, as
before.
**Preview** is one control wherever the panel offers a page as a visitor sees
it — the site's head, a page's screen, the editor: the button opens the
**draft** in a new tab, as a visitor will get it, with every change in it,
saved or not, and says *Draft* on itself; its chevron offers the **version**
(the last save, as built) and, once the site is published, the **live** site
at its own address. On the site's head the same menu keeps *Open the editor*
and *Open as the client* below them. On a site whose draft is not drawn — the
older contract, or a template that does not say `render: "live"` — the button
is the version and says *Version*. The tab's badge names what it shows:
*Preview · Draft*, *Preview · Version* or *Preview · Live*. For somebody who
may edit the site — its studio, a studio it is shared with, its own people —
the badge carries **Edit in the panel** beside it, in the page's language
where the panel has it: it opens the editor on the same page, and the first
time on a site a line beside it says texts and photographs are changed there.
The link `get_preview_link` gives an agent is for the person it works for, and
carries the button too, with a line that says to sign in first: the panel asks
whoever opened it for a real sign-in and comes back to that page in the editor;
the link itself still only shows the site. Any other preview link — the ones a
studio makes in the panel for its client — an agent and a studio looking at
the showcase see the badge alone, and the panel's own frame shows neither.
- **Preview over an entry's card.** On a site drawn live, *Preview* on an
entry's card opens the entry where it is seen — its own page, or the page
that lists it, with a chip for each where there are several — scrolled to it
and outlined, read-only, over the card, which keeps everything on it. What
the card holds and has not put into the draft yet is drawn there too, for
the person looking and nobody else: it is a short-lived preview layer over
the draft, which a version, a build, another member and a visitor never
see. It says when it was shown the last build instead, and on a site not
drawn live, or for an entry shown nowhere, the button says why it is off.
The site's renderer runs the site's code in a container of its own, one site
to an instance, with no network but the platform's draft of that site and its
build cache, and no key of ours; it is stopped after ten minutes nobody asks
for a page. How a template is made ready: `docs/live.md` of `@jtakeit/astro`.
On a page, a change goes into the draft as it is made: the frame is the
preview. On an entry's card it goes in with **Done**. What is typed on the
card — its fields, each language's lines under them, a language held back, the
post's writing, the search fields — is held on the card, and a bar at the foot
says *3 changes · Cancel · Done*, a dot beside each field held. **Done** puts
all of it into the draft in one step: one change in *N unsaved changes* under
the header and in Compare, taken back by the toast's *Undo* for a few seconds
and by Compare after. It writes everything or nothing: a value its field
refuses, or one somebody changed meanwhile — another person's card, a tap in
the editor, an agent's import — is marked on its field, and nothing is
written. A field changed meanwhile says by whom and when, with *Keep mine* and
*Take this*. **Cancel** forgets what is held. Leaving with something held asks
*Apply · Discard · Stay*; closing the tab asks the browser's question, and the
card offers what it held back the next time it is opened in that browser
(*Bring back · Discard*), for a week. Cmd/Ctrl+Enter is **Done**; Escape never
discards. *Save a version* and *Publish* in the bar under the header, pressed
while a card holds changes, ask first: *Apply and save*, *Save without them*,
or *Cancel*. Showing or hiding the entry, its dates and its address still act
at once, as before. A post's writing held for ten minutes says since when it
has not been in the draft. **Preview** — in the card's head with nothing held,
in its bar while something is — opens the preview over it (above) where the
site is drawn live: the draft, with *Open in the editor* beside it, or the
draft with what the card holds and **Done** (**Add** for a new entry) beside
it, which applies it from there. Elsewhere, with nothing held, it opens the
editor on the entry's page, in the language the card is read in; with
something held it is off and says why: the changes are in the draft after
**Done**, and a new entry is there once a version is saved and built.
Where the entry stands is one line under the card's head, told apart by the
three stages — the draft, a saved version, the published site — from what
the site visitors are served has and what this entry's changes a save or a
publish has not carried yet: *In the draft* (no version holds it shown yet:
save a version, then publish); *Saved in a version* (it goes on the site
with the publish); *On the site*, saying beside it when its latest changes
are still in the draft or saved and not published; *Appears on …* (a date to
appear, and whether a save or a publish still has to carry it); *Still on
the site* (hidden in the draft only, where the switch could not act on the
site — it leaves with the publish); *Taken off the site* or *Not on the
site* (switched off, on a site that carries it or not yet); *Taken off on …*
(its date to go has passed) — with the date it goes, where one is set. On a
site never published — still being set up — nothing is on a site: what the
preview serves is the version, not a site visitors have, so the line says
*Saved in a version* or *In the draft*, and that the site's first publish
puts it on the site; a hidden entry is *Not on the site*, never *taken off*
one, and one past its end date is left out of the first publish. Beside
**Preview** is one control for it: the act the state
calls for — **Show it on the site**, **Take it off the site**, **Change when
it appears**, or **Show it again** past its end — joined to a menu of what
else makes sense in that state, each item with a line saying what it does:
a shown entry is offered a date to go, never a date to appear; a hidden one
a date to appear (setting it shows the entry), never a date to go; a date
already set is offered as changed or taken away, not set a second time; an
entry waiting for its date can be shown without waiting or kept off the site.
**Delete** is the last item of that menu; its question says that the entry
leaves the draft now and the site with the next version published, which
languages go with it, what points at it, and that the list can bring it back
until the next save. The address under the title follows the same stages:
the live link while visitors find the entry there — on a published site
only, never on one being set up; saved in a version and
not yet on the site, the address it *will be at* as text, with *See it in
the version* beside it, which opens that version's preview — never the live
address; only in the draft, the address it will be at, as text; off the
site, the address it is *not shown at*, as text.
On a site in several languages the card's languages are one panel: the
language it is read in, and **On the site in each language** — a row for the
original, shown wherever the entry is shown, and one for each other
language with a switch and a sentence saying what it does: visitors reading
the site in that language see this entry, or it is left out of that
language's site. The switch is held with the rest of the card until
**Done**. An entry the bookings book has no such rows: it is in every
language, always.
How the card lays its fields out is the schema's to say, on a contract-3 site:
an entry type's `form` ([the schema](../reference/catalogue.md#a-form)) puts
its fields in sections with a heading and a line under each, in rows of up to
three on a laptop, with a column beside them for what the entry is at a glance
— its photograph, its category — and chooses each field's control from its
kind's few: a row of buttons for three categories, quick lengths for a
duration, a stepper for seats. A phone shows every row as one column, the
aside after the sections, in the same order the keyboard goes. A field's other
languages hang under it as in the editor: each a row with its code, its state
and the same box, open while there are fewer than three, folded from three; the
language the card is read in only says which row is on top. A photograph keeps
its words and their languages under *More*. A new entry is the same card,
held from the first keystroke: what is written in it — a photograph, a price,
an English line — goes into the draft with **Add**, as one change, and the
screen is its card. What it still needs is said beside **Add**, which puts the
caret there. **Cancel**, or leaving with *Discard*, makes nothing; a
photograph already uploaded stays in the media library. Without a `form`, the card puts the title first (a post's date beside
it), the pictures aside and short values two to a row; a field a `form` leaves
out is shown under *More*, never hidden — but for the fields a module's own card
draws, which no form lays out: the shop's product card draws a product's
options, variants and *Advanced* itself ([the shop](#the-shop)), so a form lays
out the rest of a product, its title, description and pictures, and needs no
row for the card's. A form that places one is advised
([`JTK_W_PANEL_FORM_GUESSED`](../reference/errors.md#jtk_w_panel_form_guessed)),
and the panel leaves the field out of it all the same.
## Launching a site, and its domain
**Who:** the studio (owner or admin of its account) — and, on a client's
site, the client themselves once they have taken it on the terms the studio
set. **Where:** the site's screen, the last row of **Setting up**.
What has to be true first, and each one refuses in its own words:
- somebody is responsible for the site — the client took it through the
owner's link, or the studio took it as its own (*nobody is this site's
business yet*);
- the site holds a line of the plan — *launching a site needs one site in this
studio's plan* is the plan being short, see [reselling](#reselling);
- the site has a build repository;
- if the site collects enquiries, takes bookings or takes orders, a **verified
destination** exists for each, or *nothing is set up to receive…* — see
[where enquiries, bookings and orders go](#where-enquiries-bookings-and-orders-go).
Launching revokes every preview link and serves the chosen build on a public
address. Every site gets a handle of ours
(`-.jtakeit.site`) that keeps working for ever. The client's own
domain is optional, attached at launch or later under **The site → Domain**:
type it without `https://` and without `www`, then set the DNS records the
screen prints where the domain was bought. The screen says *waiting* until the
records answer, which is up to half an hour. Until then the handle keeps
serving the site as before — the domain usually still points at the old
hosting while the records travel — and the moment Cloudflare serves
`www.` with its certificate, the handle redirects there and the panel
frames the domain. A domain of the client's is put into a Turnstile widget by
the platform the moment it is attached. Nothing in the repository changes for
a domain: no rebuild, no setting, no file.
`preflight` reports all of this after the fact; the launch button is the
studio's and, once the terms are accepted, the owner's. **The domain is the
business's name**: the site's owner or admin attaches it, the studio does so
only on its own site, and on a client's site it reads the DNS status to help.
## Going back to an earlier build
**Who:** a person with the publish right — never an agent on a launched site.
**Where:** **The site → Builds**, *Serve this build again* on any finished
build.
A rollback puts the older build in front of visitors at once and **holds the
site there**. While the hold stands nothing of another commit goes live: a
build that lands — a save, a rebuild, an agent's `commit_and_build` — waits as
*Built, not published*, the publish buttons give way to a line saying why, and
a publish asked of the API is refused with `JTK_E_PUBLISH_HELD`. An entry's
scheduled moment and an entry switched on or off still reach the site: they
build the held version again, which undoes nothing. The rollback restored the
files, not the repository: fix the source, press **Lift the hold** on the same
card, then publish the version that carries the fix. Lifting publishes nothing
by itself.
## The editor
**Who:** whoever may write the site's words — the owner, an admin, an editor,
the studio. **Where:** **Pages**, a page opened to edit.
The frame is a build of the site — the saved version's, or the live one — with
the draft laid over it: the page's own words, the text on every page, and the
words and pictures of the entries the page shows, so a service renamed on its
card reads as renamed on the services page at once. What only a build can
draw — a price or a length the site's code writes out, an entry added,
deleted, moved or hidden — waits for the next version, and a line over the
frame says how many entries and leads to the comparison. The first
open says it in one sentence: what is changed is kept in the draft; *Save a
version*, then *Publish*, and visitors see it. *Save a version* and *See the
changes* are in the bar under the header, as on every screen of the site —
the one way to save, on a phone as on a laptop. On a laptop the rail beside
the frame has one head, as a field's does: the language the page is read in,
one chip that opens every language with what each has left and what that
means for the save, and undo and redo — with how many steps each holds — at
the right, where a field keeps them; *Drop the draft* is behind its ⋯, and
asks first. Under it, the screen the frame is (a laptop, a tablet, a phone)
and *Preview*, the page the frame is on as a visitor sees it — the draft,
with the version and the live site under its chevron (above); then the
versions, a line each on one line from the draft to what is live, with when
and *Publish* on the version once nothing is unsaved — no commit is named in
the editor; the builds keep those. On a phone and a tablet the
same are in the toolbar over the page and its sheet. Every publish asks
first, the first one above all — it gives the site its public address and
ends the preview links — on a phone as on a laptop. Its **Pages** list walks
the site: its pages, and under each collection whose entries have pages of
their own its list (where the site has one, at its address in the frame's
language) and its entries — those only in the draft too, marked *new* — a
few at a time, with a search where there are more.
The frame is a real device's screen, chosen over it: a laptop (1440 × 900),
a tablet (820 × 1180, an iPad Air) or a phone (393 × 852, an iPhone 15). It
is the device's whole screen in its own shape, scaled alike both ways to fit
the room and never above life size, and the page scrolls inside it; on a
phone the phone's page takes the screen.
The comparison (*See the changes*) is laid out the same way, and opens on
one of those windows: what the move puts out — the draft on the draft's
pair, the version on the site's — on the device chosen with the same
switch, with what changed outlined and tinted in the colour of what
happened: amber changed, green added, red removed, blue moved. *Compare
with the version* (*Compare with live* on the site's pair) puts the older
beside it on the left, and scrolling one scrolls both. The page in each
answers the pointer — a hover, a tab, a slider, an accordion — and stays
the page compared: a link to another page of the site takes both windows
to that page, and to the place on it the link names (*Write to us* on any
page goes to the form); a link to a place on the page takes both windows
there; the site's own language switch switches the comparison's language;
a link that leaves the site is not followed — where it leads is said over
the window, with *Open in a new tab*; a form is not sent. A row
taken out is outlined only on the left, one put in only on the right; the
choice is remembered. Over them, which two are compared, each pair with how many
changes it holds, the language both windows show — on a site in more than
one, the editor's choice, kept while walking the pages — and the move it
leads to — *Save a version* or *Publish*. The list of what changed is grouped by page, beside the windows
or under them on a laptop, where it opens wide to be read down whole, and
in a sheet on a phone; the page on screen is opened onto its changes under
the block each is in — a heading per block with how many changed in it, the
page's own (its name, its address, what search engines read) under the
page's. Each change is a sentence with names in it — *Added item “Title”*,
*Item “Quality” moved from place 3 to place 1*, *Price of item “Haircut”* —
its old value struck on red, an arrow, the new one on green, as a picture
is; where the page does not show it, it says what it is: a link's address,
a hidden field, what search engines read. Its dot is in its colour; *Go to
the change* takes the windows to it and pulses it — and
brings the older window beside the newer for what only the older shows —
and on the draft's pair a change can be undone from its row. An entry with
no page of its own is shown on the page that lists it, its tile outlined;
one the site shows on no page is said to be nowhere.
A text or a button tapped on the page is edited where it is. On a laptop the
rail turns into that field — which page it is on, in which language (the
page's own language menu, so the field is opened in another from there), its
words with how long they may be inside the box, its other languages hung from
it as one field — each its code, its state and its words — and undo and redo
beside the way back —
and the element stays outlined on the page; the way back at the rail's head,
or Escape, returns the rail to the page's state, with what was typed kept at
once — and so does a tap on the page beside every field, except where the
words cannot be written, when the field stays open and says why. Tapping another field switches the rail to it. One picture opens in
the rail too: the photograph and *Change the photograph* — the picture
itself does the same — which opens the library, to choose a file the site
has or *Upload new* (a file dropped on it too), which goes into the library
and is chosen at once. One photograph is changed, never taken away: the
block is drawn around it. Its words, with their *Other languages*, are under
**More**. A list opens in the rail as well: its rows, a line each — what the
row says, a handle to carry it by (the arrow keys move it), and a ⋯ with
*Move up*, *Move down*, *Duplicate* and *Remove row* — and *Add a row* at the
foot, as far as the list's `min` and `max` allow, saying so where they do
not. A row opens one step deeper: its fields, each with its control, its
verdict and its *Other languages*; one the same in every language
(`localized: false`) says so; the row's values the page does not show are
under **More**, and *All rows* goes back. Tapping a row's words on the page
opens the list at that row. The *Add* under a list on the page opens the new
row the same way, every field of it at once; it is written once it has words
and the fields it needs, and is taken away again if it is left empty. Read in another language, the list opens the
same way: each row's words are that language's, written into its
translation, with the original's words under each field before anything is
typed — a word not yet translated says so, and is not a fault of the row.
The rows themselves — which, and in which order — are one for every
language, and are moved, added, duplicated and removed from there all the
same: in the original, which a line by the handles says once. A row added
there is made in the original's language, every field of it, and says so;
the other languages then have it to translate. A gallery read in another
language keeps its pictures and their order the original's. Every change is written into the draft as typing
is; a row added, moved, duplicated or removed is a step of undo of its own.
A gallery opens over the page: its pictures in an even, numbered grid, carried
into order — the one carried lifts and the others step aside, as a list's rows
do (Alt and an arrow on a tile, or the arrows by the picture) — with *Add
photos* always at its head and a «+» at the end of the grid: the library,
several marked at once and added together, *Upload new* inside it, as far as
the field's `max`, which it says; files dropped anywhere on the gallery are
added at once, each a tile while it uploads. The picture selected has its
panel beside the grid, the single photograph's own editor — the picture,
*Change the photograph*, and its words with their languages under **More** —
and *Remove from the gallery* at its foot, which the draft's undo takes back;
on a phone the panel is a step of its own. Its head is the rail's — the
title, how many of how many, *Add photos*, the draft's undo and redo, and
close; *Done* or Escape closes it too. A post's body opens over the page too, as on a tablet,
where every field opens beside what was tapped — a list there in a column
beside the page, the same rows and the same row; on a phone the field comes
up from the bottom of the screen. A button opens as a text does — its
words, and under them where it leads, where the site made that the owner's —
with *Follow the link* (or *Press the button* on a form) at the top, which
does what a tap on the site would, inside the frame. Where it leads is
chosen, not typed: *A page of the site*, found by its name in the site's
list, and a section of that page from a list of the same kind — *The top of
the page* first, then each element of the built page with an `id` and a
heading, named by the heading, searched where there are many — or *Another
site*, an address checked as it is typed (`example.ch` is written
`https://example.ch`). Switching between the two writes nothing: each keeps
what it last held while the field is open, the link says where it still
leads, and only a page or a section picked, or an address typed, changes it.
The value is the same `url` string either way. Give the sections a link may
point at an `id` and a heading of their own, or the owner can only send
visitors to the top of the page. There is no button to
keep it: what is typed goes into the draft after a short pause, and the
editor says so — trimmed at its ends: a space typed at the end is not a
change, and nothing is written for it.
What a block keeps that the page does not show is offered with what it does
(`no_tap_target`). A field that names the one it belongs to (`beside`) opens
under that field — the hour under the date. A link that names nothing opens
under its button where the block has one button it can belong to: the words
field named alike (`cta_href` with `cta_label`, a row's `href` with its
`label`), or else the one field whose key says it is a button's (`cta`,
`button`); where two could be it, it is with the rest of the block. Name a
link's button with `beside` rather than leave it to the names. Read in
another language, the button's link is still under its words — one address
in every language, written to the original, and said so.
### Every tap, one way
On a page a change goes in as it is made; on an entry's card it goes in with
**Done** (above). Whatever is tapped opens the same rail (the tablet's popover, the phone's
sheet), in the same parts. A line above the field's name says where it
lives: *This page · Hero*; *Shared text · Contacts · on every page* (on
every page in that language, where each language is a page of its own); an
entry shown here, *Team · Maria Muster* — with *wherever it is shown* where
its collection is shown in more than one place; a module's settings, *Diary ·
Working hours* or *Shop · Shipping*. The field is written in place whenever
this person may write it, to the document it lives in — the shared text, the
entry's draft, an entry's price, length, hour and reference too — and under a
fact the bookings read (`costs`, `takes`, `rates`, a master's `hours`) one
line says *Bookings read this from here, once published*, and under one the
shop reads of a product, a variant's price among them, *The shop reads this from
here, once published*: the draft changes, undo takes it back, and the module
reads it after **Publish**. Right under the field comes what belongs to it,
before anything else: where a button leads, the fields beside it, and its own
lines without a heading — the button an address is beside, a field named alike
(`image` and `image_alt`, `cta_label` and `cta_href`), a row's other fields.
Then *Also in «…»* is the rest of the same source, in the schema's order, a
line each — its name, its value as a list says it, and *not on the page* where
the page draws no element for it (`no_tap_target`, or nothing on this page). A
line opens as a tap on it would: the page brings the value into view where it
draws it. At the foot, *Open «…»* goes to the source's own screen: an entry's
card, the diary's working hours, the shop's shipping. Shared text has no
screen; it is under **On every page** in the Pages list, each block opening
as its source. On a tablet the lines wait behind *Also in «…» (N)*. Read in
another language, an entry's words tapped on another page are that
language's, written into the entry's own translation.
What cannot be written here opens the same way, read-only, with its reason
and nothing to type into. Every field a tap opens is outlined alike, a
read-only one too; what is no field of its own — a region, the design's
words — is not:
- **a field the studio keeps**, for a client — *The studio edits this one*,
as on the entry's card;
- **a module's settings** — the diary's week, the shop's shipping — with
*Open «Working hours»* or *Open «Shipping»*;
- **what the site works out** — «Open now», a postcode and a city drawn as
one — *The site works this out itself, from «…»*, with that source's lines
under it (the site names it with `data-jtk-from`, the kit's `from()`);
- **the site's design words** (`data-jtk-fixed`) — *This is the site's
design: the same for everyone, changed by the studio.*
The design's words inside a field are that field's: a day's name in the
hours, annotated as their list, opens the hours' rows — a day, when it
opens, when it closes, each row open in place. A tap on a link's or a
button's own furniture — an arrow, the padding — opens the one field it
holds, and a link whose address is a field (`data-jtk-href`) and whose words
are none opens that address — on contract 3 another document's too, named by its id
(`data-jtk-href="entry::ticket_link"`), as a tile names it. A link or a button among them is offered with
*Follow the link* and is never followed by the tap itself. On a contract-3 site an entry's own page — a
post, a master with a page of their own — is edited by tapping like any
page, its header and footer too; the body opens the writing.
## The history
**Who:** whoever may read the site — the owner, an admin, an editor, the
studio; never a preview link. **Where:** **Changes history** in the site's
menu, and on every entry's card, under its fields.
What was changed on the site and by whom, newest first, ninety days of it:
- **Edits, not keystrokes.** One person's writes on one site with less than
thirty minutes between them are one edit, whatever pages they are on. An
import or a push is one edit, *from the code*, named by the first line of
its commit's message — so write that line for the owner, who reads it here:
*spring prices*, not *wip*. A saved version and a publish are lines between
edits.
- **Folded to one line** — *Anna changed 3 things on Prices and Team* — and
opened into what it changed, per page or entry, by name and never by
address, each field by the schema's label with what it was and what it is:
a text word by word, a choice by its option's words, a reference by the
entry's title, a price in the site's currency, a body by its words. A change
made in a translation says its language.
- **An entry's own history** is the same timeline narrowed to the entry and
its translations.
It is read-only: nothing brings a version back. A changed field of an entry
offers **Copy the old value**, which puts the old value into the field on the
entry's card as if it were typed — on the site's history it opens the card
with the value in place. It is held on the card as a word typed there is,
goes into the draft with **Done**, and through the three stages like any
edit. A page's words are edited on the page, and the
history shows them without a copy. No tool reads the history; `get_site`
says what the draft holds unsaved.
## Reselling
**Who:** the studio's owner or admin. **Where:** **Reselling** — *Usage* for
what the studio buys and what it covers, *Stripe account* for the studio's
own, which only charging a client through us needs — and each site's
**Ownership** for what that client pays. The screen explains itself until
*Got it*; after that the explanation is the *i* beside its title.
A studio here is a reseller, and the panel says so. It **buys** a line on its
plan for every live site, at a wholesale price that falls with the number of
sites. It **sells** its client a subscription of its own — its price, its
invoice — set per site under Ownership, zero included. It **keeps** the
difference, all of it: we take a price per site and never a share of what a
client pays. The two prices stand side by side where the client's is typed;
we never subtract one from the other, because the studio's is tax included in
its own currency and ours is before VAT.
The studio buys a **plan**: so many sites, so many diaries, so many shops,
monthly or yearly. Nothing is charged before the launch — a site
starts drawing on the plan the day it goes live and gives its lines back when
it is archived. A site holds one `base` line always, a `bookings` line if its
schema turns the diary on, and a `commerce` line if it turns the shop on; the
buy form offers the shop's line once it is on sale, and never more diaries or
shops than sites. Every publish of a live site asks for the lines its modules
need, so a shop turned on after the launch is refused its publish without one,
and a line bought for a shop that took no orders is taken by the next publish,
which opens it again.
How the client is charged is the studio's choice. It may invoice them itself,
which needs nothing from us; or bill them through us, on its own Stripe
account, which is part of every site and costs nothing more —
[below](#billing-the-client-through-us). A client who would rather pay us
directly is a [handover](#handing-the-site-over-to-the-client), and the site
leaves the studio's plan. Prices are before VAT; Stripe adds it at checkout
by country.
Buying is one form and a Stripe Checkout; changing the plan afterwards is the
same form and is charged as the difference. The card, the invoices and ending
the plan are in Stripe's portal (**Reselling → Manage plan**). Monthly
becomes yearly, and back, on the same screen.
What refuses when the plan is short: launching (*needs one site in this
studio's plan, and there is none*), turning bookings on for one more site,
setting the terms of one more client's site. The sentence names the kind; the
remedy is one more of it under **Reselling**.
A **promo code** — typed when the studio was named, or under **Reselling →
Usage** until the first payment — may give free site lines for a time, and a
discount on the plan for its first months. The lines say *free until* their
date on the table of what is held, and a launch on one says what follows it.
They are the studio's like any other line: its own sites and its clients'.
A business with its own account takes a code the same way. The code a link
carried is applied when it signs up and chooses its business; otherwise it is
typed on the site's launch or on **Subscription**, until the first payment.
Free site lines cover the site line only, and a diary or a shop on such a site
is bought beside them. A business's **Subscription** screen is the site's
price list until there is a plan: what the site costs, monthly or yearly, and
the button to Stripe. Once there is a plan, it shows the plan and what one more
site or a module adds to it.
## Referrals
**Who:** the studio's owner or admin. **Where:** **Referrals**. A blogger's
studio makes a code per video there and reads each one's funnel — clicks,
sign-ups, studios that launched, studios that pay — without the studios
named — and *What you earned*, by month and currency: a share of what each
studio it brought pays us, for three years from that studio's first payment,
payable thirty days after it was earned and paid each month by transfer. A
programme is turned on by us, on application in our Discord; a studio
without one sees only how to apply. An agent cannot make codes.
## The diary
**Who:** the owner (or admin), and the studio for the schema half.
**Where:** **Diary**, and **Diary → Opening hours**.
Two halves, and both have to be there before a visitor can book:
1. **The repository** declares the module — `modules.bookings` in the schema
binding two collections, the services (entries with `takes`, minutes, and
`costs` to be payable) and the resources (the people or rooms; one entry is
a solo business). This is the studio's, committed and imported.
[Bookings on the site](bookings-on-the-site.md) has the shape.
2. **The owner publishes the hours.** Under **Diary → Opening hours**: the time
zone, the week's hours, days off, slot length, how far ahead, how a booking
is confirmed (at once, or after the owner says yes), how long a paid slot is
held, until when a customer may cancel. *Save and publish* — a draft offers
nothing.
Until both are true the diary says what is missing, and so does `preflight`:
*this site's schema does not turn bookings on*, *nobody has said which
timezone this business keeps*, *nobody has said when this business is open*,
*nothing in the services collection says how long it takes*, *the resources
collection has nothing published in it*. Each names the half that is missing.
The owner books people in by hand, confirms, cancels, moves, marks who did not
come, and exports the whole diary. A booking carries how many it is for when
the site takes a party — a table, a class — and a class that is full says so
by the count, *3 of 3 places taken*, when one more is booked by hand. The customer gets a page of their own to
cancel or move from, reminders a day and two hours before, and a calendar file
— none of that is set up; it is what a booking is.
When the owner moves a confirmed booking and the customer is told, the move
stands at once and the customer is asked whether it suits — *That works*,
*Another time*, *Cancel* — by email and, where a chat is linked, in Telegram.
The booking says what they answered: *change agreed by the customer*, or *no
answer from the customer yet*; each new move asks again.
A request from the site still waiting for an answer is not moved in the
panel: it is offered another time. Its row, its side sheet, its card and
*Waiting* say **Offer** where a confirmed booking says *Move*, and the window
is the move's — the same free times and the same check — with a line saying
the request will not change until the customer accepts, the owner's reason
(one line, 200 characters at most, shown to the customer), until when the
customer may answer, and the letter word for word; *Offer* sends it, and the
customer is always told. The customer may answer until the business's hold
for a request (two days where it sets none), and never past the offered start;
a time already begun is not offered. A second offer replaces the first, and
the window says so. Accepted, the request is confirmed at the offered time —
the place is checked again at that moment, and taken meanwhile the offer is
over, the request stays as it was and the owner is told; declined, the request
is withdrawn by the customer; not answered in time, it lapses. Whatever the
owner does to the request meanwhile — a yes, a no, a move — takes the offer
back, and **Withdraw the offer** on the side sheet and the card takes it back
on its own, the customer told unless the owner switches that off.
A request with an offer open says *Offered* and until when wherever it is
listed, the time offered on its card, and sits below the ones *Waiting* still
needs an answer to; the list of all bookings narrows by *Offer*. *Offer* is
drawn off, with why on it, where none may be made: the request is waiting for
its online payment (it is moved once paid, or settled on the telephone), it is
a visit of several bookings, or the customer left only a telephone
(`JTK_E_PROPOSAL_NO_CONTACT` — ring them). A request the business wrote down
itself is moved as before. Dragging a request from the site on the diary's
grid opens the *Offer* window on the place it was let go at (on its own
place, saying why, where that has already begun); one that may be offered
nothing goes back, and a note says why. Moving a request directly, without an
offer, stays where it was for an agent and the API
(`POST /v1/sites/:siteID/bookings/:bookingID/move`), and the customer is told
of the move as before.
## The shop
**Who:** the owner and an administrator, and the studio for the stock. The
studio sees the orders in shape — numbers, totals and states, never a buyer —
until the owner opens a window on *Orders* (or while it runs the site for the
client), and never the money; an editor edits the products and sees neither the
stock nor the orders. **Where:** **Shop** in the menu, on a site whose schema
turns the shop on: **Products**, **Orders**, **Stock**, **Shipping**.
**Payments** stays where it is, under the business.
Two halves, as the diary has: **the repository** declares the module and the
products (`modules.shop` in the schema, `jtk/entries//.json`,
[the shop on the site](shop-on-the-site.md), [the module](../reference/modules.md#shop)),
and **the owner runs the shop** in the panel — what is below. The counts are in no file, and a buyer can
pay only once the Stripe account under *Payments* is ready.
- **A product's card.** The card draws the product's options, variants and
*Advanced* itself; the schema's `form` lays out the rest — the title, the
description, the pictures — and needs no row for the card's. *Products* lists
each product. To whoever reads the
stock — the owner and the studio — it shows each one's **price** (*from* the
lowest) and its **stock** in two columns: what is left, *sold out*, *no stock
set* where a count was never given, or *made to order*. Under the name it
names what the owner is to put right — *no price*, and *no weight* where a
method prices by weight — and *not on sale*. A product
over by its own date and kept on show is *over since* that date, and sold no
more, whatever its stock says. A simple
product is its price, SKU, stock and *on sale* in the card, with the weight
when a method prices by weight. **The stock in the card is the ledger's**,
written at once and not with the draft, and the card says so; whoever may not
read the stock sees a sentence that says so and no box. Everything else the
card changes of the product is held with the card's other changes and goes
in with **Done**, the variants and the options too — a row removed, a value
set for the selected rows (*take off sale* among them), *Add options* — each
list one change on the bar, made to the product as the draft holds it, and
forgotten by **Cancel**; *take off sale* offered for a variant an order bought
is a change for each variant, or one with the list where the list is held
already; a list somebody changed meanwhile is said over the table, with *Keep
mine* and *Take this*, and a list the save refused is said there too, and
either way nothing is written. *Add options* (sizes,
colours…) asks the options and their values and makes a variant of every
combination — each with a SKU made for it and the product's price and weight
(the product needs its price first); at most 2,000, and past that it says so
and makes none. The variants are a table, drawn as it is scrolled and one
card a row on a phone; each edit is one row's field, a price, a weight or *on
sale* can be set for the selected rows at once, a value added adds its
combinations and one removed removes its variants. *Advanced*, folded, holds
what buyers are asked besides the variant (a choice, a yes or no, a short
text), whether the stock is counted or the product is made to order, the
shipping size, the tax code, the customs tariff number and where it is made.
**The tax code** is Stripe's, picked from a short list named by what the thing
is — *ordinary goods* first, which is what a product with none is taxed as,
then printed books, children's books, newspapers, magazines, food and
groceries not eaten on the premises, clothing and footwear, and children's
clothing and footwear — or *another code*, typed in Stripe's shape (`txcd_`
and eight digits) and written only once it has that shape. It decides the VAT only
where the business charges it, as [Payments](#payments-for-bookings-and-orders)
says.
- **A SKU is made for the product** — from its slug for one added in the panel
(`T-SHIRT-FOX`), with its values' keys for a variant made from options
(`T-SHIRT-FOX-M-RED`), a number added where the site has it already — and a
copy of a product gets new ones. The owner may change a SKU until an order
names it. **A SKU an order named stays its variant's:** the save refuses a
draft that changes it or gives it to another variant
([`JTK_E_SKU_ORDERED`](../reference/errors.md#jtk_e_sku_ordered)), and an
agent's push is held to the same. The card draws it read-only; a variant
bought under a SKU it no longer carries offers *Put back* with that SKU, and
a SKU an order bought as another variant, typed on this one, is said beside
its box to be changed. A variant an order bought offers *take off sale* where
its row would be removed; one that leaves the draft all the same — by a push,
or bought after it was removed — is no fault, and its SKUs, like a deleted
product's, are never given to another variant. *Add options* on a product
that has sold keeps its sold variant, with its SKU and its stock, as the
first combination. The whole product may still be hidden or deleted; its SKUs
are never given again.
- **The stock.** *Stock* is one table of every SKU of the products, by product
and variant, with what is **on hand**, what is **held** — kept by checkouts
now — and what has **sold** in three columns. A count is corrected in its box, sent with the count
it replaces: when a sale or another person's correction came first it is
refused, the box shows the count now and keeps what was typed, and nothing is
overwritten unseen. A count below zero is drawn as *oversold by N*, a product
made to order says it is not counted, and what the ledger holds for a SKU no
product shows is listed apart. It is the owner's, an administrator's and the
studio's, and closed on the sample site every studio sees.
- **The shipping.** *Shipping* is the zones (a name and their countries; a
country is in one zone) and the methods of each: a flat price, or prices by
weight for each size (a letter, a parcel, bulky goods), or a pick-up, and
*free above* an amount — with whether it covers bulky goods. Each change goes
into the draft and is published with the rest, as the opening hours are;
buyers are offered what is published. What the save would refuse is said
beside its field before it is pressed, and each method buyers are not offered
because of it, or because it has no price yet, is named at the top. A site
whose repository has no `jtk/modules/shop.json` is told the studio adds it
(`jtk add shop` lays it with a zone and two methods to price): the screen
does not make the file. Like the opening hours, it is closed on
the sample site.
- **The orders.** *Orders* opens on what is **to fulfil**, newest paid first,
with *Fulfilled*, *Cancelled* and *All* beside it, a search by number, name
or email, and each order's state, a refund beside it (*refunded CHF 20*,
*refunded in full*) and a dispute marked. An order is listed from the moment
it is paid; a checkout never paid is not an order. Test orders — placed from
the preview, paid in Stripe's test mode — are behind the switch that holds
the diary's tests. The order shows everything to pack: the lines with their
variant's values and the answers to the customizations, the buyer's name,
email and phone, the address or the pick-up, the method, the subtotal,
shipping and total, and — to the owner and administrators — the payment's
reference, to find it in Stripe's dashboard, and each refund with its amount,
what went back in stock and whether it is done, waiting for Stripe or failed.
On an order taken with VAT on, the VAT Stripe charged is under the total,
one line for each rate (*including VAT 8.1%: CHF 2.91*): the total alone
(*including VAT: CHF 3.52*) where Stripe's rates could not be read in time,
*No VAT was charged on this order.* where none was, and *not known* where
nothing of it was read. Where the buyer paid in a currency of their own, the
order says what they paid (*paid as EUR 41.20*); its total, its refunds and
the export stay in the site's currency. An order taken with VAT off says
nothing of VAT, not even *VAT 0*; a refund is shown as its amount and is
never split into its VAT.
- ***Fulfilled*** is one button for the whole order, on an order to fulfil. It
takes a tracking number and its carrier (Swiss Post, DHL, DPD, GLS, UPS, or
another, with its link typed), both optional, and asks once more: the buyer
gets an email now, in the site's language — *on its way* with the tracking
link, or, for a pick-up, *ready for pick-up* with the business's address.
*Fulfilled* is final; the tracking number may be corrected afterwards, and no
second email goes. A part-refunded order can be fulfilled; a cancelled one
cannot, and the owner and administrators are offered none while a refund of
all that is left waits for Stripe.
- ***Refund*** and ***Cancel the order*** are the owner's and an
administrator's alone. A refund is an amount — all that is left unless less
is typed — with how many of each line go back in stock (*put back in stock*:
never more than the order sold, less what earlier refunds put back) and a
reason Stripe shows beside it. *Cancel the order*, on an order still to
fulfil, refunds all that is left, puts every item back and leaves the order
*Cancelled*. The button is off while a refund is sent, and pressing it again
in the same window is the same refund, never a second. A refund Stripe has
not answered is shown as waiting and asked about every hour; one that failed
is marked, and its amount is the order's again. A refund of all that is left
on an order to fulfil cancels it; any other order keeps its state, with the
refund beside it.
- **The orders as CSV** are a button on *Orders*: one row an order, with the
buyer, the lines, the totals, when it was fulfilled and its tracking number,
and the VAT and its rates when the shop charges VAT.
The live file is the business's, or the studio's through a window ([your
client's data](your-clients-data.md)).
An agent sets a shop up and does none of this: no tool reads an order, fulfils
one or refunds one, and `set_stock` sets the starting stock of a SKU that has
not sold. It lays the kit with `jtk add shop`, brings a catalogue in with `jtk
import products`, writes a product's tax code in the entry, in Stripe's shape,
and sets neither of [Payments](#payments-for-bookings-and-orders)'s two switches.
## Payments for bookings and orders
**Who:** the site's owner or an administrator — and never the studio.
**Where:** the site's **Payments**.
Letting customers pay: for an appointment when they book it, and for an order
in a shop — every order is paid online. The money goes to the business's own
Stripe account, which the owner opens from this screen — person or company,
then Stripe's own questions inside our panel. It is one account for both.
Nothing can be charged until Stripe says the account may (*the account exists
and the questions have not been answered yet*, then *being checked*, then
*ready*). The setup list asks for it as soon as the site takes money — a diary
that charges when it books, or a shop — and a buyer who comes before it is
ready has nowhere to pay: `preflight` says *customers can pay* until it is.
**The studio does not see this screen's contents.** Payments are the
business's books, and the account holding the site is not the business. The
studio's Payments says who has to set it up and, while the site has no owner
yet, offers the owner's link that brings one in (**People**, where the setting
up's door mints it on arrival). Refunds are the owner's too — a booking's, from
the diary, and an order's, from the order's screen (**Shop → Orders**, the
order's *Refund*); the studio's diary has no refund button, and neither has
its order.
**Unless the studio runs the site for the client.** A site's screen asks *who
is responsible for the site* before it can go live, and the answer is one of
two arrangements. *We build the site; the client's data is theirs*: the
studio says what the client pays it for the site — zero is an answer — and
the owner's link goes to the client with those terms on it. That answer is
given the moment the terms are set — the site's line is held from the
studio's plan from then on, and the notifications and the rest of the setting
up no longer wait on the client; only the first publish does, until they take
the site. Once they do, the enquiries and the money are theirs — and on their People screen,
under Maintainers, they
decide what the studio may see or touch: the records in full, and the money
(the payee's form, sent to the client's own email, and refunds from the diary;
never payouts, which are in Stripe's own dashboard). A client who will never
open the panel opens it once, through the link, and grants both. *This is our
own site*: the studio's owner and admins are the business by their role.
*This is our studio's own site*: the studio member pressing it becomes the
owner, and the enquiries and the money are the studio's — never the
arrangement for a client's site.
What has to be true first: the site says what **country** the business is in
(**The site → The business**, which the screen links to), and Stripe operates
there. A service is payable only if its entry names a price as an amount; a
price written in words is for the page, not for a card. A shop's prices are
always amounts: a variant's price is one.
**Two switches, beside the account.** On a site that sells, once the account
can take money, a card under it holds two switches. They are the business's
like the rest of this screen, each is off until it is turned on, and each says
what it costs. Today both act on the shop's orders and on nothing else: a
booking's payment is neither taxed by them nor shown in another currency, and a
site whose schema does not turn the shop on is not shown them, and sees this
screen as it always was. A change acts from the next checkout: an order keeps
what applied when its buyer went to pay.
- **VAT.** *Stripe Tax calculates the VAT on each sale. Stripe charges 0.5% of
every sale it calculates VAT on, billed to your own Stripe account.* The
prices include VAT, so a buyer pays the price shown, and each product's tax
code (*Advanced*, on its card) decides its rate.
VAT is turned on only once Stripe says the account is ready for it — its
tax settings made, the head office known, a VAT registration active — which
the screen asks Stripe every time it is drawn. Until then the switch is held
off and says what is missing, and **Set up VAT** opens Stripe's own forms on
the screen, for the head office and for where the business is registered:
brought into view, with a **Close**, shut of themselves once Stripe says the
account is ready, and saying so when Stripe could not load them; they are
offered too when Stripe could not be asked. A registration that lapses later
leaves the switch on, and the screen says Stripe charges no VAT until one is
active; an order taken meanwhile says that no VAT was charged on it. Where
Stripe says more than a registration is missing — the tax settings, the head
office — the screen says Stripe cannot tax a sale yet, so orders may not be
paid until it can, and offers to turn VAT off. A change of the Stripe account
— the account taken off the site, or another put on in its place — turns VAT
off, and it is turned on again once Stripe says the new account is ready.
**The price is the same for everyone.** Stripe charges VAT where the goods go
— the delivery's address, or the shop's own for a pick-up — and only where the
business is registered. A buyer abroad from a shop registered at home is
charged none, pays the price shown and may owe import VAT at the door; the
shop keeps its price whole. An address Stripe cannot tax opens no payment:
the checkout answers `422 address` and the order is given up, its stock given
back ([the shop protocol](../reference/shop-protocol.md)).
- **The buyer's own currency.** *A visitor from abroad sees the price in their
currency and pays 2–4% more for it, or pays in* the site's currency, which the
sentence names. Stripe's page may show that buyer the price in theirs; the
order, its refunds and the export stay in the site's currency, and the order
page says what the buyer paid in their own.
No agent sets either: no tool, no file and no commit reaches them. The site's
pages are told what is on, whether the prices include VAT and whether a buyer
may pay in their own currency, by the shop's answers ([the shop
protocol](../reference/shop-protocol.md)).
We take nothing from these payments. Stripe's own card fee is the business's,
as the seller — and so, on a shop's orders with VAT on, is Stripe Tax's, which
Stripe bills to the business's own account.
## Where enquiries, bookings and orders go
**Who:** the owner or admin — and the studio only while it runs the site for
the client, by its own declaration on the site's screen. **Where:** **The
site → Notifications**; the enquiries themselves are under **Enquiries**, the
bookings in the **Diary** and the orders under **Shop → Orders**.
Every enquiry, every booking and every paid order is kept in the panel
regardless, each on a screen of its own. What this screen decides is who is
*told*: Telegram (a personal chat or a group, through the bot's deep link) or
email (a code is sent to the address and typed back — nothing is ever sent to
an address nobody proved they hold). The panel itself is not a channel.
The setup list asks it as one question, in the words of what the site takes —
*do you want your enquiries and bookings sent to your email or Telegram as
they come in?*, a shop's orders named with them. **Yes** opens this screen,
which asks *where*: Telegram or email, then that channel's one step; once a
channel is connected the screen says where they are sent, with a way to remove
each and to add another. **No** is a real answer — *the panel only*, also
offered on this screen while nothing is connected — and it counts for the
launch exactly as a channel does; the screen then says nobody is notified, on
a shop as on a site with a form. Connect a channel and that answer lifts on
its own; remove the last channel and the question is open again. A site that
gains a kind after it chose the panel alone — it starts taking bookings, or
selling — is asked again, and the same **No** answers it: the panel then hears
every kind the site has.
Test submissions — what a studio sends itself from the preview or *try the
form* — can have channels of their own, under *Also send test submissions
somewhere?* at the bottom of the same screen. They never hear a real
customer, and the launch does not wait on them.
A channel is an address; **what flies to it is its setting**. A new channel
hears everything the site collects — on a shop, its paid orders too — and on a
site that collects several kinds each channel has a switch for each: enquiries,
bookings, orders. So the bookings can go to the receptionist's chat and the
enquiries to the owner's, or everything everywhere, and a shop's orders go
wherever *Orders* is on. On a site with one kind a channel has no switch — until
it does not hear that kind (a channel linked for enquiries, on a shop), and
then it has that one. Every kind the site collects, orders among them, must be
heard by at least one verified channel before the site can launch — *this site
takes orders and nothing is set to receive them* is that refusal; it is the
gate `preflight` reports, and the setup list's *Notifications* row names the
kind still heard nowhere.
Before a handover the destinations must be the owner's, not the studio's:
*the enquiries still go to an address somebody set up here* is that refusal.
## People, roles and letting a studio in
**Who:** the owner or admin of a site; the owner or admin of a studio.
**Where:** the site's **People**; the studio's **People**.
A site's people are invited by link: one use, seven days, with a role in it —
owner, admin or editor. A studio's people the same way, into the studio —
admin or developer; becoming the studio's owner is a transfer, not an
invitation. The links are shown once; only their hash is kept.
An owner who wants a studio to work on their site does not invite its people
one by one: they **let the studio in**, by its id (which the studio finds on
its own **People** screen), and take it back with one action. The studio then
reaches the site as a guest with the role it was given.
No tool invites anybody or lets anybody in. Those are decisions about people.
## Handing the site over to the client
**Who:** the studio's owner or admin starts it; the client finishes it.
**Where:** the site's screen → **Hand the site over to the client**; the
client's link at `/take-over/`.
The client gets an account of their own, pays us directly at the direct
price, and the site — its lines, its repository (mirrored, so nobody is left
who changes how the page is built), its people — moves to them. The line it
held on the studio's plan is freed. The studio stays on the site as a
maintainer, live or not, with the owner's four switches — records, money,
domain, publishing — off until the owner turns them, and until the owner
takes it off from People. On a site still being built — **the client pays
jtakeit directly** under *whom does the client pay*, the other answer to the
terms — the client's account becomes the site's business and the client pays
from the moment they accept.
The card mints a link, shown once, good for fourteen days. Before it will:
no Stripe account of the studio's is attached for the site's bookings, and
the client is not being billed by the studio through us. Each refusal is a
sentence naming what to undo. The enquiry channels stay as they are: the
client confirms each one and takes any off from People.
The client opens the link, reads whose site and at what price *before*
signing in, signs in through any door, presses **Take the site over** (this
makes their account), pays at a Stripe Checkout, and the site moves the moment
the money lands — the page waits for it, and the platform tries hourly for a
tab closed at the bank. A client whose account already holds a free line is not
sent to the bank at all.
If the client wants the studio back afterwards, they let it in from **People**.
## Billing the client through us
**Who:** the studio's owner or admin. **Where:** each site's **Ownership** →
**Bill the client through us**; **Reselling → Stripe account** once,
before the first amount above zero. This is the *sell* half of
[reselling](#reselling).
The terms of a client's site: what the client pays the studio for it, set
before the client exists and carried on the owner's link, which is where the
client reads them before signing in. Zero is a price — the studio invoices
the client in its own way, or not at all — and needs no Stripe account.
Above zero, the owner pays the studio *through* us, on the studio's own
Stripe account, with the studio's invoice: we create the subscription, send
the invoices and reminders, and show both sides where it stands. It costs
the studio nothing beyond the site itself — no line on the plan, and never a
percentage of what the client pays. The site's line is held from the
studio's plan the moment the terms are set, and given back only by the
studio's own hand: withdrawing terms nobody took, or ending the billing —
which, on a live site, takes the site off its address.
The client's money goes to the studio's Stripe whole; what Stripe keeps is the
studio's as the seller: the card fee, and Stripe Billing's fee on subscription
volume.
First, once: the studio's own payment account under **Reselling**, by country
(named, in the reader's language; a country not in the list is one Stripe does
not serve, and Stripe is the only provider today) and person or company, then
Stripe's questions. Then per site: what the client pays, in which currency,
monthly or yearly, **by card** (the owner enters one once) or **by invoice**
(Stripe emails it with a page to pay on, fourteen days), the client's email,
and whether to freeze the site after fourteen days unpaid — off by default.
The owner's **Subscription** screen then says what they pay the studio and
offers the two buttons that pay it, and Stripe's portal for cards and invoices.
The price and the interval belong to the running subscription: to change them,
stop and start again, so the owner sees a new first invoice and never a
surprise on the next.
## When a subscription is not paid
Two ladders, and each freezes only what is its own.
**The studio stops paying us.** Day 0 a letter; day 14 the **freeze** —
editing, publishing and new enquiries, bookings and orders stop, the site stays up,
reading and export still work; day 23 a final notice; day 30 the **dark** — the
site answers 503 with a maintenance page. Paying brings the freeze off at once
and the site back within the minute. The owner's Overview says so in plain
words, and every refusal in the frozen state says *this site is frozen: its
subscription has not been paid*.
**The owner stops paying the studio through us.** Only if the studio asked for
it: an invoice fourteen days overdue freezes the site — never the dark. The
refusal says *the payment to the studio that runs it is overdue*, the owner's
Subscription screen has the button that pays it, and paying thaws on the next
tick.
Neither ladder archives anything or deletes anything.
## Giving a site to another studio
**Who:** an owner or an admin of the studio. **Where:** the row menu on
**Sites** — *Give to another studio*, on a site nobody pays for yet: never
launched, not handed to a client, no client terms on it.
It makes a link that works for seven days and is shown once. Whoever opens it
in another studio they own or run takes the site whole: pages, versions,
pictures, its address. Your studio loses it — its preview links stop working
and the enquiries the demo collected are deleted. Your repository stays yours;
the site builds from the platform's copy of its code until the other studio
attaches a repository, and an empty one is given the code. A launched site
does not move this way: its client decides who works on it, from People.
Between two studios **you** run, the same sheet moves the site at once, with
everything — its enquiries, channels, guests and repository — and a launched
site may go too: it takes a place in the other studio's plan, which must
have one.
## Switching a site off, archiving it, and the data
**Who:** the studio. **Where:** **The site**, and the row menu on **Sites**.
**Switch off** gives visitors a maintenance page instead of the site, keeps
search rankings, and comes back in a moment; the reason is for the studio and
never shown. **Archive** takes the site off the internet, revokes its links,
gives its lines back to the plan, and keeps the content and the builds, so it
can be undone. What happens to the enquiries, bookings and orders afterwards is
[your client's data](your-clients-data.md).
**Bring back** — on the archived row's menu, and on the archived site's own
screen — undoes it, as far as it goes: the site comes back as a **draft**, off
the internet, with its pages and its last build behind the preview, and it
takes one of the studio's places for sites that are not live again. It does not go live by itself.
Launching it is the same **Go live** it was the first time, which asks the
same questions — where the enquiries go, whether the plan has a site left —
and puts the addresses it had back. While a site is archived nothing is built
and nothing is served: **Publish**, a rebuild and *Serve this build again* are
all refused until it is brought back.
## What the site reaches
**Who:** the owner and the studio. **Where:** **The site → Outside
services**, the last tab (it was a place in the menu until 13 November 2026;
the old address leads to the tab).
The addresses the published site loads something from while somebody is on
it — fonts, analytics, a map — read off the files it was built from, so the
list changes with a publish. What could not be read (an address put together
as the page runs) is said as such, never as *nothing*.
## A collection's entries
A collection — the services, the masters, the works, the posts — is a list the
owner adds to, and its screen is where they work through it. **Who:** the
owner, an admin or an editor, and the studio. **Where:** the collection's own
item in the menu.
- **Finding.** A search box (the title in either language, the slug and the
entry's text, without case or accents); **Filters** to narrow by whether the
entry is on the site, by any choice or reference its type has, and by how
far a language has got (*to translate*, *outdated*, *translated*, *held
back*); **Sort**, a way to view the list that never changes the site —
*as on the site* (the collection's own order: by hand, by a date or by a
field; on a dated collection it says which way it runs and offers the
other), *by title*, *recently changed*; and on a site in several languages, the
language switch above the list, which says the list in that language and
what is left to translate there. The list is
answered by the server a page at a time, with *Show more*, and what was
asked stays in the address, so coming back from an entry lands on the same
list. Each row says its title, what is unusual about it (hidden, appearing
later, going on a date), a few of its values, a mark per language, and who
last edited it and when — an edit to the entry or a translation; saving a
version or publishing is not one.
- **A new entry is on the site in the draft** — a post from *New post*, a
service or a master from its form, a copy of a shown entry, a row of an
import: in its listing in the preview at once, and visitors see it after
*Save a version* and *Publish*, like any change. The form of a record makes
the entry with **Add**, every field and every language's line in at once, or
makes nothing and says which field it refused. **Save a version** first names each entry the
version would put on the site for the first time — new, or shown again —
with **Keep off the site** beside it (its switch off, in the draft), and
asks nothing when there is none; **Publish** names those its version would
put up, and one kept off there is left for the next version, which the ask
then offers to save. A save refused because an entry on the site is not
finished names each one, with **Open it** and **Keep it off the site for
now**, which switches it off and saves again; one visitors already see is
only opened, to be finished. Nothing is ever switched off without being
asked.
- **The order on the site.** On a collection ordered by hand — services with
the signature one first, the team with the owner first, questions,
galleries, rates — *Change the order on the site* shows the list in the
order visitors see it, and the booking form where the bookings read the
collection; search, filters and sorting are off meanwhile, and *Done*
brings them back. On a laptop a row is dragged by its handle, or the handle
is focused and moved with the arrow keys; on a phone or a tablet each row
has up and down. Each move goes into the draft at once, like any edit, and
where the list is grouped an entry moves within its group. A collection the
site orders by a date or a field has no such button: it orders itself.
- **Several at once.** Tick entries and the bar at the foot of the screen
shows, hides, sets a choice or a reference, or deletes them.
It is one change, all or nothing, saved and published like any other; a
deletion asks first what names the entries, and refuses those with bookings
ahead.
- **Duplicate**, in a row's menu: a copy with its translations, at a new
address with *copy* in it in each language, right after the original where
the collection is ordered by hand, shown or hidden as the original is.
Nothing that named the original names the copy.
- **Where an old address goes.** Deleting or hiding an entry that has a page
of its own — from its row, the bar or its card — asks where a visitor who
has its address is sent: the collection's list (the default), the home
page, another entry, an address on the site, or nowhere. The platform
redirects it once the deletion or the hiding is on the site: a deleted
entry's address for good (301), a hidden one's for now (302), and showing
the entry again takes it back. **The site → Old addresses** lists every
address the site has left — moved, deleted or hidden — with where it goes;
the owner changes the place or removes the redirect there.
- **Bring back.** Under the list, the entries deleted in the draft —
from the list or from an entry's card, which says so as it closes — each
with its translations and who deleted it, and **Bring back**. It is
refused, with nothing moved, where another entry has taken the address
since. After a save a deletion is a commit, and the entry is in the site's
history.
An agent does none of this through a tool: it reads a collection with
`list_entries`, every entry with its values, and changes entries in the
files and a commit. Redirects for addresses a site's files no longer have are
the platform's; an agent writes none of its own for them.
## Languages
A site has its own languages, declared in the schema (`locales`). The panel
itself is read in the reader's language — their choice, in the menu under
their name — and every label the schema carries has a word in each. A site's
language and the panel's language are two different settings.
On a contract-2 site a page exists per language the repository says it does,
and each is edited as a page of its own.
On a contract-3 site every page, entry and the text on every page is **one
document in the site's own language — the original — and each other language
holds only its words** (a translation, `..json` beside the
original). The owner edits them as one. **Who:** the owner (an editor too),
and the studio. **Where:**
- **A switch of languages** in the editor's rail (on a phone in the toolbar
over the page, with undo and the widths), on a page's own screen, on an
entry's card and on a collection — in the rail, on the card and on the
collection one chip with the language read now, which opens every
language. The site's own language is named as the
original; each other language carries a mark — nothing when it is
complete, otherwise how many of its words are still to translate and how
many are outdated (translated from an original that has changed since).
In the editor the chip's menu lists them, on this page and its shared
text, each named as it reads — *Values · Calm · Title* — and a tap opens
that one in its language, outlined on the page; *Next to translate*, in
the menu and under a field read in that language, walks them. On
a collection, beside the chip, the screen says in words how many entries
wait for a translation in each other language — *DE-CH: 1 entry waits for
translation*, a press away — or that every entry is translated; choosing a
language lists the entries with something left in it. The language chosen in the editor, on a page's screen or on an entry's
card is remembered for the site while the tab is open, so the next page
opens in it.
- **A page's own screen and an entry's card in a language** show the page in
that language — the picture at its address there, `/en/…` — and *Search
results* holds that language's title and description, written into its
translation with the card's button. A field the language leaves empty shows
the original's words under it, marked as the original's; the share picture
is the original's and changed there.
- **The preview in a language** shows the page as that language does. A value
still in the original's words is outlined in dots and counted in the rail,
never passed off as translated. A text tapped there holds that language's
words and is written into its translation.
- **A photograph, a gallery's pictures, a price, a date, a link** are the same
in every language: edited from any of them, they change all of them, and
the editor says so.
- **Other languages**, under every text being edited: a line per language
with its words and where they stand — *original*, *current*, *outdated*,
*not translated*, *machine, unchecked* — opened and edited in place, the
original's line too. A line saves the way the field above it does: in the
editor after the same short pause, said at its foot and taken back by the
same undo; on an entry's card held with the field above it, and into the
draft with the card's **Done**. There
is no button to keep a line, and none to take it out: a line emptied and
left is taken out, and the language shows the original's words again, *not
translated*. A
line offers *Checked* on a machine's words (read, kept as they are). One or
two other languages are open at once, a field each; from three the block
folds — on a phone to one line until tapped, in the rail by its heading,
each line opened in place. A picture's description is per picture.
- **Editing the original** — in its own field or on its line — says under it
which languages still show the earlier text; nothing asks first.
- **An entry's card** has *Show every language* — every text with a row per
language, to translate a whole entry in one pass — and a switch per
language to **hold the entry back** there. A master, a service or anything
else the bookings book is in every language, always, and has no such switch:
a missing translation shows the original's words. A post's writing is whole
per language; the card says where it stands and copies the original's as a
start.
- **Before a version is saved**, the rail says what is behind — *12 texts are
not yet in EN, 3 are outdated*. It never stops the save.
- **The Languages screen**, *The site → Languages*: each language's coverage,
and what is left to translate grouped by page and collection, each a way to
where it is edited in that language.
Every change in a language is a change to the draft like any other: counted,
saved with the next version and published with it. What the panel writes is
recorded as a person's (`by: person`) and what an agent writes in the files as
the agent's; `get_site` says per language what is still to translate.
### Machine translation
Where the platform has a DeepL key, a person in the panel can have the
machine draft a language's words. **Who:** whoever may write those words —
the owner, an editor, the studio. Never an agent: an agent is a translator in
its own right and writes `..json` in the files; no tool sends
anything to DeepL. **Where:**
- **Translate** on a line of *Other languages*: that text, that language.
- **Translate all** above the lines: every language where that text is not
translated or outdated.
- **Translate all** on an entry's card: the whole entry, every language.
- **Translate now · Later** under an original whose words changed: what has
changed in that page or entry so far, in every language.
- **Translate all (about 3,400 characters)** on the rail before a version is
saved, and **Translate all** per language on the Languages screen.
What the machine writes is a draft like a person's words, recorded as the
machine's (`by: machine`) and marked *machine, unchecked* until somebody
presses *Checked*. It reaches visitors only with a version and a
publish. Only words are sent: never a price, a picture's file, a reference or
a link's address, and markdown's and rich text's markup is kept as it was.
A post's writing is translated whole.
**How it speaks**, on the Languages screen: formal or informal per language
(formal unless somebody says otherwise — *Sie*, *vous*, *Lei*), and the words
it never translates, one per line. The business's name is always kept, and
the names of what the bookings book are kept as each language already says
them.
**What it costs:** a paid site has 30,000 characters of machine translation a
calendar month, not carried over; a demo 10,000 once. The Languages screen
shows what is used. Text translated before costs nothing again. Past the
allowance the buttons say why and are not pressed; translating by hand works
as always.
**Off** is the default: with no key the panel shows none of this, and nothing
else changes. A person sets the key (`DEEPL_API_KEY` on the host; staging uses
DeepL API Free). Production stays off until the processing list and the data
processing agreement name DeepL as a sub-processor; then the owner sets its
key.
## The business's facts
**Who:** the owner (an editor too), and the studio. **Where:** **The site →
The business**.
Name, address, telephone, opening line, and — the two that other things wait
on — the **country** and the **currency**. Payments, for bookings and for
orders, need the country — and a shop's checkout needs it to say when a buyer
abroad pays the duties at the door; prices need the currency; the diary needs
its own time zone, which is set with the hours. The schema declares the facts
the pages print; the country and the currency are the platform's and are on
this screen whether or not the schema names them, as selects — a country in
the reader's language, never a code typed by hand. An agent building a site from a brief knows all
three on day one; the panel is where they are written down. The currency the
agent may give once: `create_site`'s `currency`, or `currency` in
`jtk/site.json` while the site has none, which the import takes. Once the
site has its currency it is changed here, by a person — the select asks
first on a site with prices — and a contract-3 import that brings a new one
is refused (`JTK_E_CURRENCY_SET`). A branch still saying the currency the
last save wrote, from before a change here, is left alone, and the next save
writes this one. `preflight` fails a site whose pages show prices while it
has none, naming this screen.
On a contract-3 site this screen holds the country and the currency, each
saved on its own; *Payments* sends the owner here for the country, and offers
it itself. The business's
name, address, telephone and the rest are the shared text's `contacts`
(`jtk/shared.json`), each field with its role: the owner edits them on the
page like any other words, through the three stages, and the site builds its
structured data from them. `preflight` checks that every value filled in
there is drawn on the pages.
## The media library
**Who:** the owner (an editor too), and the studio. **Where:** **Media
library**, beside the pages; and **From the library** under every picture
and gallery field — *Change the photograph* on one tapped on the page.
Wherever it opens to choose from, *Upload new* (or a file dropped on it)
puts a new file into the library and chooses it at once.
Every picture and clip the site has uploaded, newest first, each with its
size, when it came, and **where it is used**: every page, entry, the shared
text and a module's settings that names it, at its place by key
(`blocks[hero].image`, an entry's `cover`), in which stage — the draft, the
version, live — and every translation that gives it words in its language.
An agent reads it through `media_link` and `npx @jtakeit/astro media pull
''` ([the pictures, into the library](connecting-a-site.md#the-pictures-into-the-library)),
or, without a shell, through `get_site`'s `library` — the newest files and
whether a field names each yet;
the same answer is `GET /v1/sites/:siteID/media` for a person's session, each file with its
`name`, its `width` and `height` as drawn, its `origin` (`person`, `agent`)
and its `thumbs`.
**The photo page** (`/drop`) is the library's door for somebody who is not
signed in here: the agent's `media_link` hands it out, the person opens it on
their phone, sees the site's name, and chooses or drops photographs; each
shows its progress and its result. In a chat that renders MCP Apps, the
same page is a box under the agent's answer instead. The link is good for an hour and for
pictures only; what arrives is in this library with the agent as its origin,
and the agent places it.
**What the library keeps is not quite what was sent.** Every upload, from
the panel or any other door, is cleaned on the way in:
- **The metadata goes.** A phone writes where a photograph was taken into it
(EXIF GPS), and the camera and the time to the second. The library takes
EXIF, XMP, IPTC and comments out of a JPEG, PNG or WebP without touching
its pixels, keeps its colour profile, and keeps its orientation, so a
portrait still stands up. A clip loses the place it was filmed the same
way; an AVIF's metadata is blanked where it lies. An SVG is kept as it
came, once it is safe to serve.
- **A JPEG or PNG longer than 2 400 pixels** is scaled down to 2 400 on its
long side, turned the right way up, in its own format. A WebP or an AVIF
is kept at its size (the panel sends a smaller one already).
- **Thumbnails** are written beside each JPEG, PNG and WebP: copies 160, 480
and 960 pixels wide (the ones narrower than the picture), JPEG — or PNG
for a picture with transparency — at
`.w.` on the same host,
served the same way. The library says each file's `thumbs` and
`thumb_ext`; the panel's lists draw those, not the original.
A file's key is the hash of what was kept, so the same photograph sent twice
is still one file. In a dev session, *Upload new* puts the file into the
library of the site the session copies — the one its content will name once
it is committed.
- **From the library** places a file the site already holds instead of
uploading it again. A file uploaded twice was always one file (its key is
its contents' hash); this is the way to find it again.
- **A file's words.** On a contract-3 site a file has its own words, its
`alt`, in the site's language. A picture placed without words of its own —
from the library, or by an upload of a file the library already describes —
takes the file's. A field's own words override them, and a translation's
override both in its language ([translations](../reference/translations.md)).
Changing a file's words gives the new ones to every place still saying the
old ones, as a change of the draft: counted, compared, saved and published
like a word typed there. Places whose words differ are left. The words live
in the content, so the build and `get_content` read them as any value.
- **Deleting** asks first, with the picture, and is refused while anything
uses the file — in the draft, the version or on the live site — and the
screen says where. **Put another in
its place** swaps another of the library's files into every place of the
draft the person may change (a field the design keeps is left and counted),
its words going with it where they were the old file's. Once that is saved
and published, the old file can go. A deleted file stays in the bucket for
older builds until the site is archived; uploading the same bytes brings
it back, and so does saving content that names it — an older version
copied back from the history, say.
## A collection as a spreadsheet
**Who:** whoever may add entries (the owner, an editor, the studio).
**Where:** a collection's screen, **Export to CSV** and **Import from CSV**,
below the list. *Import from CSV* opens a dialog (a sheet on a phone): a place
to drop the file or press to choose one, *Download an example* — the
collection's own columns and two example rows, which import as two new
entries — and *Download the current entries* to start from where the
collection has any, the format in four lines with this
section behind them, and — once a file is dropped — what it would do, in the
same dialog, with *Import N* and *Back*.
The export is one row per entry, in the collection's order, written as every
CSV here is ([the CSV files](your-clients-data.md#the-csv-files): semicolons,
UTF-8 with a byte-order mark, CRLF):
```
id;slug;visible;title;date;cover;cover.alt;pictures;price (CHF);section;category;tags;body;title@en;cover.alt@en
0193a5c3-…;eiche;yes;Eiche;2026-03-01;media/…/9e8d7c6b.jpg;Eichentür;media/…/a1b2.jpg | media/…/c3d4.jpg;120.00;Holz;Schönheit;Rot;Eiche.;Oak;Oak door
```
- `id`, `slug`, `visible` (yes or no; left empty, a new entry is shown and
an existing one keeps its switch), then each field of the entry's type by
its kind: words as they are; a number as digits; **money in major units,
the column naming the site's currency** (`45.00`, `from 45.00`,
`on request`); a length in minutes; an hour as `09:30`; a date as
`2026-11-12`; a switch as yes or no; **a choice by its label**; **a
reference by its entry's title** where that title names one entry, else
its slug, several joined by ` | `; a picture by its file's key, its words
in `.alt`; a gallery's keys and a list as JSON, which are read and
changed in the panel, not here.
- **One column per field with words, per language** — `title@en`,
`cover.alt@fr-CH` — the translation's own words; empty where it has none.
- The cells are written as every export's are: a cell a spreadsheet would run
as a formula starts with an apostrophe, which the import takes off again.
The import reads such a file twice. First it says, without writing anything,
per row what would be **added** (and *hidden*, where its `visible` says
no), **changed** or **refused**, and per cell
what each change is (`was → now`) and why one is refused: an amount that is
not one, a choice the field has not got, a reference to no entry or to two
of one title, a currency that is not the site's, a picture the library does
not hold, an address changed (that is the panel's, with its redirect), a
gallery or a list changed, a field the design keeps and the person may not
change. A row with one refused cell is left out whole. Then **Import** sends
the same file with the plan it was read as: under the site's lock, the plan
is made again and written only if the collection is still what was read —
otherwise *check it again*. Each entry is one change of the draft, each
language's words go into its translation, and new entries are made at the
collection's end as the panel makes them. Nothing is published by it: the
rail counts it as unsaved work.
A collection the bookings read is exported as its entries — the services,
the masters — never what was booked of them; those are the client's records,
and leave through [their own exports](your-clients-data.md). And what a module
books is in every language, so the import never holds an entry back in one.
A shop's products are not brought in this way: what they sell is lists — the
variants, the options, the customizations — which this import does not write,
as it writes no list. A catalogue comes in as an agent brings it, with `jtk
import products` ([the shop on the site](shop-on-the-site.md#the-catalogue-jtk-import-products)),
and the panel is where the owner changes it after.
---
# Who can do what
Every action the platform knows, who may take it, and where in the panel it is
taken. The columns are asked of the same function that refuses a request —
`access.Can` — so this table cannot say yes where the code says no. The
studio column is a member of the account that **holds** the site; a studio let
in as a guest has the role it was given and no more, and its agent has that
role's share of the agent column. A guest works on the code where it lives and
does not move a client's site to another repository: that is the holder's.
The last column is any
studio on the sample site every account sees (wiki/74): it looks, with the
sample people in the records, and changes nothing — the record endpoints
that write refuse it by name.
The rule under the table is one sentence: *an editor touches the content and
sees the numbers; an owner or an admin touches the money, the domain and the
people; the studio does what "not a builder" means — structure, address,
repository, launch.* An agent holds a studio's token and a builder's share of
it: nothing about the client's customers, nothing about people, nothing that
launches.
[The panel, by hand](../guides/the-panel.md) says what each screen asks for
and what refuses when it is not there.
| what | studio | owner | admin | editor | agent | preview link | a studio on the sample | where |
| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | --- |
| See every site on the platform (`site.list_all`) | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | Nobody's, through the panel — a job's and Grafana's |
| Make a site (`site.create`) | ✔ | ✘ | ✘ | ✘ | ✔ | ✘ | ✔ | Sites → New site; `create_site` |
| Archive a site, or bring one back as a draft (`site.archive`) | ✔ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | Sites → row menu → Archive, Restore |
| Attach or change the build repository, import a branch (`site.repo`) | ✔ | ✘ | ✘ | ✘ | ✔ | ✘ | ✘ | The site → Build; `attach_repo`, `import_branch` |
| Launch the site (`site.address`) | ✔ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | The site's screen → Go live |
| Attach the business's own domain, take it off (`site.domain`) | ✘ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | The site → Domain |
| Change how the site publishes itself (`site.settings`) | ✔ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | The site → Build |
| Read the live enquiries (the holder gets the count, never a row) (`enquiry.view`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✔ | Enquiries |
| Mark an enquiry read, delete one (`enquiry.manage`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✔ | Enquiries → the message |
| See how the enquiries are arranged — the list of destinations, never the contents (`enquiry.setup`) | ✔ | ✔ | ✔ | ✘ | ✔ | ✘ | ✘ | The site → Notifications |
| The live diary: read it with the person in it, book a real customer by hand, confirm, cancel, move (`booking.customers`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✔ | Diary (the holder sees the shape — times and states, never a name — unless a window is open) |
| The live orders: read them with the buyer, mark one fulfilled, take them out as CSV (`order.customers`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✔ | Shop → Orders (the holder sees the shape — numbers, totals and states, never a buyer — unless a window is open) |
| The diary's machine: opening hours, resources, which services are bookable and at what price (`booking.setup`) | ✔ | ✔ | ✔ | ✘ | ✔ | ✘ | ✔ | Diary → Opening hours |
| Set the starting stock of the SKUs that have not sold yet; a SKU that has sold is left as it is (`stock.set`) | ✔ | ✔ | ✔ | ✘ | ✔ | ✘ | ✘ | The agent's `set_stock`, or the studio's call; the counts drawn at Shop → Stock, and a product's card, are `stock.correct`'s |
| Correct any SKU's count by hand, sold or not, and read the stock (`stock.correct`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | Shop → Stock, and a product's card (never an agent's, never an editor's) |
| Say where the **live** enquiries and bookings go (`records.destinations`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | The site → Notifications (the site's own owner or admin — the holder while nobody owns the site yet, or on a site it has declared its own) |
| The test stream: make a test record, read it, decide it, clear it, and where it is announced (`records.test`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | Diary → Test; The site → Notifications → the test stream |
| Say that a live channel is the business's own — what makes it deliver, and what opens the launch (`records.confirm`) | ✘ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | The site → Notifications → Confirm (the site's own owner or admin; never the holder of a site nobody owns) |
| Let the studio see the live records for a while, and close the window (`records.sight`) | ✘ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | People → Sight (the site's own owner or admin — never the studio) |
| Give a customer their money back (`booking.refund`) | ✘ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | Diary → the booking → Refund (the site's own owner or admin — or the studio while it operates an unclaimed site) |
| Give a buyer their money back for a shop order, whole or in part, and say what goes back in stock with it (`order.refund`) | ✘ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | Shop → Orders → the order → Refund, Cancel the order (the site's own owner or admin — or the studio while it operates an unclaimed site; never an agent's, never an editor's) |
| Open where the site's money lands, and see it — and the two switches, VAT and the buyer's own currency (`payments.manage`) | ✘ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | Payments (the site's own owner or admin, or a maintainer the owner let at the money) |
| Send the business Stripe's form, made from what the site already says (`payments.invite`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | Payments → Stripe's form (the site's own owner or admin; the studio's owner or admin while the site has no owner yet; a maintainer the owner let at the money) |
| Rename the site (`site.rename`) | ✔ | ✔ | ✔ | ✘ | ✔ | ✘ | ✘ | The site → Name and addresses |
| Change what search engines are told (`site.indexing`) | ✔ | ✘ | ✘ | ✘ | ✔ | ✘ | ✘ | The site → Build |
| Add or remove pages (`page.manage`) | ✔ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | The repository, then `import_branch` |
| Add, remove or reorder blocks (`block.structure`) | ✔ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | The repository, then `import_branch` |
| Issue and reset the owner's link (`link.manage`) | ✔ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | The site → Preview links |
| Serve an earlier build again (`build.rollback`) | ✔ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | The site → Build → Builds; `rollback` |
| Hide or show a block (`block.visibility`) | ✔ | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | Pages → the page → the block's switch |
| Edit a field the schema marks client-editable (`content.edit`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✘ | Pages → the page, or tap it on the preview |
| Edit a field the schema does not (`content.edit_all`) | ✔ | ✘ | ✘ | ✘ | ✔ | ✘ | ✘ | Pages → the page (studio only) |
| Upload a picture or a clip (`media.upload`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✘ | Any media field on a page |
| Remove a picture or a clip (`media.delete`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✘ | Any media field on a page |
| See the preview, and make a link for somebody to look at it (`preview.view`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | Preview; The site → Preview links → Links to look; `get_preview_link` |
| Publish the draft (`publish`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✘ | The version rail → Publish; `publish` |
| Take the draft back to the saved version (`page.rollback`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✘ | The version rail → Discard the draft |
| See what changed and who changed it (`history.view`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✔ | Changes history; an entry's card → History; Overview → What happened |
| Add or remove an entry of a collection (`entry.manage`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✘ | Pages → the collection → New entry |
| See the site's numbers (`stats.view`) | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | ✔ | Numbers |
| See who is on the site (`member.view`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✔ | People |
| Invite somebody, change their role, remove them, let a studio in (`member.manage`) | ✔ | ✔ | ✔ | ✘ | ✘ | ✘ | ✘ | People |
| Switch a live site off and back on (`site.suspend`) | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ | No session may — the lapse ladder's, and the studio's Switch off is a separate act |
Three things are not in the table because no column may do them: suspension
is the lapse ladder's; reading every site on the platform is a job's; and
connecting another agent is nobody's, because a credential that can make its
own successor cannot be revoked.
---
# The brief: one conversation before the work
The brief is what lets somebody who never spoke to the client build the site.
Everything after it is an argument from it: if the page is wrong, the brief
was. It is gathered **once, before any building** — every question in one
message to the developer, not one at a time as each file needs its answer —
and it is done when the developer has read it and said yes.
## The rules
- **Nothing is invented.** Every fact carries where it came from: the client
said it, the developer said it, the old site says it, or it was asked and not
answered. A guessed opening hour ends up in the diary and in structured data,
which is the platform offering a time the business never kept.
- **What is missing is written down as missing.** A brief with holes is
workable; one with plausible filler is not, because nobody can tell which half
to check. Mark a gap `NEEDS CLIENT` and carry it to the launch as an open
item — never a placeholder price, never «9:00–18:00» because most places are.
- **One conversation, before the work.** Read what already exists first — the
old site, the profile the developer points at — so the client is not asked
what they have already said in public. Then ask the rest together.
- **The developer says yes.** Show the brief — the facts with their sources,
the defaults below, the open items — and build when they have said yes to it.
A default nobody confirmed is a fact invented by the kit.
## A person without a developer
When the person in the chat is the business itself — claude.ai, a phone, no
terminal — the brief is the same rule in one short exchange. Where they gave
their old site, read it first, and open with **the offer** (below): what their
site will do here that the old one does not. Then these questions together, in
the same message, **before** `create_site`, never one a message:
1. **The languages** — the site's own, and any others.
2. **What the site does** — online booking (paid online or on the spot: ask), a
shop, a blog. Each is a module `create_site` lays out.
3. **The currency**, only if the site will show prices.
4. **The design.** Does the business have a website already — its address? Sites
it likes — links? From those you can make a design of its own (say: a custom
design takes a little longer); read them with your own browsing. Or start
from jtakeit's quick template, in the design of Brumy (brumy.ch), jtakeit's
maker, and adapt its colours and type to the business. Pass the answer to
`create_site` as `design`: `custom` or `template`.
5. **The photographs.** Ask now. They can drop them on `media_link`'s page, or its
box in the chat (`box: true` — say first what the box is for and that you put
the photographs on the site after). Pictures already on their old website come in through
`media_link` with `site`, its address as they gave it: the platform reads the site's pages and
brings in every picture they show, galleries drawn by script too — the way to take their
photographs from their old site, rather than picking addresses out of its HTML. Where the
site refuses the platform (`site.refused`), read its pages yourself and send the
pictures' addresses in `urls` — a builder's resized copy comes in as its original. A public
profile's pictures: `media_link`'s `urls`, from addresses they give. Or the template's
photographs hold the places for now and theirs replace them later — say so.
### The offer
The person came with a site that does what it can; this one can do more, and
they should hear what, about their business, before they answer anything. Read
their site for what it does by hand or not at all, and say in a few lines what
it becomes here — each line tied to something on their site, never a list of
features. What the platform does, against what an old site usually has:
| On their site | Here |
|---|---|
| a booking link to Calendly, a form, «call to book» | the diary on the site: free times shown, booked online, paid online or on the spot, confirmed, in the panel and to Telegram or e-mail |
| a weekly plan or a monthly programme as text or a PDF | the classes as entries with their times, and the next two weeks drawn live from the diary with the places left — a timetable that keeps itself current |
| events, workshops, courses with dates | entries with their dates: the next one on the home page, a past one hidden or marked over by itself (`ends_by`) |
| a price list typed into a page | services with their prices and lengths, which the owner changes in the panel from a phone, the money in the site's currency |
| opening hours as text | the hours the diary keeps, and «open now» on the business's clock |
| things they sell — oils, vouchers, products | the shop: products, variants, stock, delivery, Stripe's checkout straight to their account |
| one language | its other languages, each page translated beside the original |
| news, a blog on Instagram | a journal on the site, written from the panel |
| reviews pasted in | testimonials the owner adds and orders |
| changes only through whoever built it | every word and picture edited by the owner on the page, from a phone |
Two or three lines that matter to this business, not the table read out — and
what is shown in the catalogue (`get_design_catalogue`, a site's `booking` and `prices`
pieces) is how it can look.
Then `create_site`. What it lays out is the kit's example: its words and its people
(Alex, Maria and Sam Muster, an «Erstgespräch») are placeholders, never the
person's site and never «ready pages». Write the site in the person's language
from what you know — the name, what they do, this brief — before you tell them
to look; the preview link may be given at once — it shows a waiting screen
until your first build. On `design: custom` the design comes first (below), and the
link waits until a build is designed.
What you do not know, ask for; never leave the example's text in its place.
### A custom design
`design: custom` is a stage of its own, before any page is built — the owner
asked for a design «inspired by the old site» and got the template with its
colours changed, called custom (18 November 2026). The site is laid out in the
kit's bare look (where the kit has none yet, in its default, and the create's
`says` tells you). The design comes before the content: it decides the blocks —
which sections, in what order, with what message — and the words are written
into the design the person chose, never into the bare look first; the same
words read differently in another design, and a person shown their words in
the bare look reads it as their site. The link keeps its waiting screen until
a build is designed. Then:
1. **Look at what has been built**: `get_design_catalogue` — the studio's sites in
pieces, pictures and code, browsed whole, then close. **Study** the person's
site and the references they named: the palette, the type pairing, the grid
and the spacing, how photographs are treated (full bleed, framed, cut out,
black and white), the rhythm of the sections, the motion.
[The design](design.md) lists the axes every site chooses on — the
hero, the header, the overlap, the surfaces, the mark… — with the variants
sites already built took; choose one per axis from the business's own
material, or make a new one.
2. **Write `DESIGN.md`** at the site's root: a short design brief — the page's
sections in order, each with its message; the choices in a few lines each,
and where each came from — and the choices in
`jtk/design.json`'s `axes`. The floor in [the design](design.md) is
kept whatever the look: the screen's height, fonts that don't jump, numbers
that line up, the measures, one family of corners.
3. **Show two or three directions as pictures**, each with the business's own
photographs, its name, its headline and the facts that carry the message — the
rest of the words wait for the choice — declared in `jtk/design.json`'s
`directions`, each a design of its own, three axes apart, the hero among
them ([the design](design.md), «Directions to choose from»): the person
switches them on the preview; `get_built_page` with `shot` and
`direction` pictures each. Look at each as a demanding designer would
first — `get_built_page` with `shot: "review"` — and fix what that
finds, two rounds. Let the person choose.
4. **Build the chosen one**: rewrite the hero, the header, the footer, the
sections and their composition (the kit's `docs/compositions.md` is the
vocabulary), not only the tokens; delete the template's files the site no
longer draws, and the other directions and `directions`. Then write the full
content into its sections.
Every build counts the template's design files the site still wears, byte for
byte the scaffold's (`get_build` → `design`); on a custom site whose design
is mostly the template's, the build and `preflight` say
`JTK_W_TEMPLATE_DESIGN` — advice, never a refusal. Never call a recoloured
template custom: if the person settles for the template adapted, say exactly
that, and the path is `template`.
Where the chat shows apps (claude.ai on the web, the desktop app, a phone), the
site's preview appears under `get_preview_link`'s answer, pictured in a real
browser, and updates itself: «your agent is writing your site» until your first
build, then the site — a content change at once where it is drawn live, a code
change after its build. Call it when the person asks to see the site or at a
milestone (the first version, a new design), at most once in a reply. The
person can mark an area of a page there, or tap a text, and write what to
change; «Send to Claude» brings you a message with their notes, and
`get_site`'s `notes` holds them with every field the area covers. Do what they ask in the files, tell them, and close each note
with `write_files`' `notes_done` (alone, it needs no base).
## What to ask
Keep it short — a fifteen-minute conversation, not a form:
- who the business is, where, what it sells — a sentence each;
- who actually comes: the last three customers, not a persona;
- the one thing a visitor should do on the page — call, book, write;
- which service they want more of: «what would you like the phone to ring
about» — that and the city are the query the page is written for;
- what makes them different, in their own words; who they turn away, and why;
- what they dislike on competitors' sites;
- the language, the domain, the photographs — and, where the business is one
person, a good photograph of them;
- **the mark** — a logo, the sign over the door, as a file (SVG best, or a
square picture of 180px or more). It is the icon in every tab, on a phone's
home screen and beside the site in search results, and nobody thinks to give
it unless asked. Without one the scaffold's stand-in is the business's
initials (`public/favicon.svg`); say that back, and replace it when the mark
comes. `preflight` checks the icon and says when it is still the stand-in;
- **the design** — `npx @jtakeit/astro create` lays the site out in the
design system of Brumy (brumy.ch), jtakeit's maker, as an example: ask
whether the business has a look of its own (its sign, its colours, a site it
likes). Say the example's look may be kept, and recommend adapting or
redoing it for this business — a design of its own is *A custom design*
above, never the example's look recoloured; then ask which of the example's sections the
business needs, and take the others out before the first push — their
blocks, their entries and their words;
- **a second language**, only where the developer names one — it is a second
site to keep written, every page and every post, for ever. Then
`npx @jtakeit/astro create --locale de-CH --locales en` lays it out: a
translation beside every original, holding only the words, and the words
that are not content from `npx @jtakeit/astro copy `; what people
book is in every language, always
(`jtakeit:///guides/languages.md`);
- **a blog**, only where somebody will write it — an empty one says the
business stopped caring. `jtk create --blog` turns it on, with its listing
at `/blog`; write the first posts before launch;
- what the prices are in — the currency, three letters: `uah` for a business
in Ukraine, asked where the site shows prices (with bookings or a shop it
must be). Give it to `create_site` as `currency`; a site made without
one takes it from `jtk/site.json` at the import — `"currency": "UAH"`
at the top (`"business": {"currency": "uah"}` on a contract-2 site) —
and every build writes it back for the page. Once the site has its currency, a person
changes it in the panel (*The site → The business*); a contract-3 import
that brings a new one is refused, `JTK_E_CURRENCY_SET` (the one the last
save wrote, from before that change, is left for the next save). One currency a site,
set on the site and nowhere else: a page shows a price with
`siteCurrency` from `src/lib/site.ts` and never names a code or a sign
of its own — preflight reads the built prices and fails one in another
currency. A price is whole minor units of it — `{"minor": 18000}` is
CHF 180, `{"minor": 1000}` is ¥1000 (a bare `18000` on a
contract-2 site). No kit knows the currency (a kit is for every country), and it
starts no payment;
- **whether a booking is paid online or on the spot** — before anything
else about the money, and never assumed. Read the current site: where
people book and pay at the till today, say so («the site books without
paying; people pay on arrival») and ask whether paying online is a feature
the developer wants **added**, or whether the booking stays as it is. A
rate without `costs` is bookable and not payable, which is the ordinary
state for a business that takes its money on arrival. And when the price
depends on the day and the hour — a lane 25 € before six and 42 € on a
Friday night — it is the rate's `rates` instead of `costs`, a row per
span of the week (`jtakeit:///guides/bookings-on-the-site.md`, *A price by
the hour of the week*), never a rate per price zone or a price near enough;
- where the enquiries go: the Telegram chat or the email a person links in the
panel (an agent cannot link one);
- **whether the business sells goods online** — then it is a shop, and the shop
kit below is laid over the site whole. Every order is paid online (there is no
paying on the spot in a shop), so what is asked is what it sells, where it
ships and its VAT, as *A shop* says;
- **whether the enquiry form takes photographs**, and how many (1 to 7) — an
order form for a website, a quote from pictures of the job. Declared as
`photos` on the form's block; the kit's `` draws the control, the
platform cleans and keeps them privately and takes none a form did not
declare (`jtakeit:///guides/connecting-a-site.md`, *Photographs with an
enquiry*). Never health or other sensitive pictures;
- **the slug** — the site's name, the first part of its handle (where its preview is), so that `create_site` follows
the brief at once and the studio sees the site in its list while you work;
- **where the code will live** — on jtakeit (`push_code`, nothing to install,
the default when the copy has no GitHub remote), or in a GitHub repository:
then which organisation or account, and who administers it. Our GitHub App
has to be installed there by that person before `attach_repo` works
(, *Install*, choose the repository;
it reads `Contents` and nothing else;
`jtakeit:///guides/connecting-a-site.md`, *Where the code lives*). It is the
one step you cannot do, so ask for it now rather than when the work is
waiting on it;
- **what the site is built with**, when the developer has not said. Offer
Astro: the platform ships its scaffold (`npx @jtakeit/astro create`, with
a kit laid out in one command), so a site on it is standing in minutes.
Any other static generator is taken too — Eleventy, a Next export, Nuxt,
SvelteKit, a script — and is laid out by you, to the list in
`jtakeit:///guides/connecting-a-site.md` (*On another generator*), with
the forms, `_meta.json`, the kit and the tool that writes the schema from `@jtakeit/kit`.
A developer who names a stack gets that stack; one who does not gets the
question, with Astro as the answer you recommend and the reason beside it.
Never a server-rendered site: the platform serves static files.
## Bookings: the kit, whole
**Bookings are not built from nothing, and they are not made simpler.** Take
the [kit](../reference/kits.md) of the business's kind **whole** — every
collection and the role the diary gives it (classes, places, seats, a
resource's own hours and what it does), every rate with its fewest and most,
every setting (a break after each booking, a gap between lettings, the hours a
thing goes out and comes back, how long an unconfirmed booking holds its time)
— and put the client's facts into it. What the platform does with them comes
with it: a refused time offered the nearest free one instead, a stay in whole
days, a class promised instead of a car, a party seated at the smallest table
that fits, several services in one visit. A salon is not «a service and a
master», and a rental is not «a car and a day».
Taking something out of a kit — the classes of a rental with one of each car,
the party question of a restaurant that takes no groups — is a **decision**:
name it to the developer, say what the visitor loses by it, and write it in the
brief under *Decisions*. It is never a simplification made quietly.
Each kind below has two lists, and both are the kit's own:
- **Ask** — the facts only the business has. Ask each; what is not answered is
`NEEDS CLIENT`.
- **Taken by default — say it, get a yes.** What the kit chose for the trade:
confirmation, cancellation, payment, the hand-over hours, what visitors see,
where the business hears of a booking. Say each back to the developer as a
sentence; a «no» is a new value in the bookings' settings
(`jtk/modules/bookings.json`, `jtk/bookings.json` on a contract-2
site), and a yes is a fact with a source.
### apartments (apartments)
Apartments by the night: check-in and check-out hours, the guests an apartment sleeps. — [the kit](../kits/apartments.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- costs: the price of a night — the kit's rate is the unit, never a price
- the apartments: each one's guests, and what tells it from the others (a floor, a number) — shown to visitors when they choose one; not the street address unless the client wants it printed
**Taken by default — say it, get a yes**
- Every booking waits for the business to confirm it (`confirm: by_hand`), holding its time for a day and then lapsing (`hold`) — or are bookings confirmed at once?
- A visitor may cancel or move their booking themselves until 3 days before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Handed over at 14:00 and brought back at 12:00 on the last day (`hand_out`, `hand_back`).
- Bookable up to 365 days ahead (`horizon`).
- Bookable for today, with no notice (`lead: 0`).
- Shown to visitors: every apartment's name and its distinguishing marks, wherever a visitor may choose one; what is booked and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### car rental (cars)
A car rental: cars by the day, grouped in classes that carry the price of a day; a visitor takes a class or a named car. — [the kit](../kits/car_rental.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- the classes the fleet is sold in, each with its price of a day. A letting in a class costs that price times its days, whichever rate the visitor took — the week is seven of them, and a weekly discount cannot be set beside class prices; if the client has one, it is an open question, not a number to adjust
- the rates' own prices (`costs`) only if some cars are in no class: those are charged the rate
- the cars: each one's class, and what tells it from its twins — a colour, a trim. The marks are shown to visitors beside the name when they choose a car: a plate goes there only if the client wants it printed
**Taken by default — say it, get a yes**
- Every booking waits for the business to confirm it (`confirm: by_hand`), holding its time for a day and then lapsing (`hold`) — or are bookings confirmed at once?
- A visitor may cancel or move their booking themselves until a day before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Handed over at 10:00 and brought back at 10:00 on the last day (`hand_out`, `hand_back`).
- Bookable up to 180 days ahead (`horizon`).
- Bookable for today, with no notice (`lead: 0`).
- No gap between one letting and the next: back in the morning, out again the same day (`buffer_stay: 0`).
- Shown to visitors: every car's name and its distinguishing marks, wherever a visitor may choose one; what is booked, the classes and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### clinic (doctors)
A clinic or a dental practice: appointments by the hour with a doctor, confirmed by the practice. — [the kit](../kits/clinic.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- hours: when it is open — the kit does not guess them
- the services: each one's takes and costs
- the doctors: who they are, their own hours, which services each one sees patients for
**Taken by default — say it, get a yes**
- Every booking waits for the business to confirm it (`confirm: by_hand`), holding its time for a day and then lapsing (`hold`) — or are bookings confirmed at once?
- A visitor may cancel or move their booking themselves until a day before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Bookable up to 180 days ahead (`horizon`).
- No sooner than 2 hours from now (`lead`).
- 5 minutes kept free after each booking, to get ready for the next (`buffer`).
- Start times offered every 15 minutes (`slot_every`).
- Shown to visitors: every doctor's name and its distinguishing marks, wherever a visitor may choose one; what is booked and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### coworking (spaces)
A coworking space: desks and rooms by the hour inside opening hours, or by the day. — [the kit](../kits/coworking.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- hours: when it is open — the kit does not guess them
- costs: the price of each rate
- the spaces: each desk or room, and how many it seats
**Taken by default — say it, get a yes**
- A booking is confirmed at once (`confirm: auto`) — or does the business confirm each one by hand?
- A visitor may cancel or move their booking themselves until 2 hours before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Bookable up to 30 days ahead (`horizon`).
- No sooner than 30 minutes from now (`lead`).
- Start times offered every 30 minutes (`slot_every`).
- Shown to visitors: every space's name and its distinguishing marks, wherever a visitor may choose one; what is booked and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### equipment rental (equipment)
Equipment for hire: items by the day, each told from its twins by a serial number. — [the kit](../kits/equipment_rental.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- costs: the price of each rate, a day and a week — the kit's rates are units, never prices
- the equipment: each item, and what tells it from its twins — a serial number, a colour. The marks are shown to visitors beside the name when they choose an item
**Taken by default — say it, get a yes**
- Every booking waits for the business to confirm it (`confirm: by_hand`), holding its time for a day and then lapsing (`hold`) — or are bookings confirmed at once?
- A visitor may cancel or move their booking themselves until a day before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Handed over at 10:00 and brought back at 10:00 on the last day (`hand_out`, `hand_back`).
- Bookable up to 90 days ahead (`horizon`).
- Bookable for today, with no notice (`lead: 0`).
- Shown to visitors: every item's name and its distinguishing marks, wherever a visitor may choose one; what is booked and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### hotel (rooms)
A hotel: rooms by the night, grouped in room types that carry the price of a night. — [the kit](../kits/hotel.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- the room types, each with its price of a night. A stay in a type costs that price times its nights, whichever rate was taken
- the rates' own prices (`costs`) only if some rooms have no type: those are charged the rate
- the rooms: each one's type, how many guests it sleeps, and its number — shown to visitors when they choose a room
**Taken by default — say it, get a yes**
- A booking is confirmed at once (`confirm: auto`) — or does the business confirm each one by hand?
- A visitor may cancel or move their booking themselves until a day before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Handed over at 14:00 and brought back at 12:00 on the last day (`hand_out`, `hand_back`).
- Bookable up to 365 days ahead (`horizon`).
- Bookable for today, with no notice (`lead: 0`).
- Shown to visitors: every room's name and its distinguishing marks, wherever a visitor may choose one; what is booked, the classes and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### photo studio (studios)
A photo studio: halls by the hour, with time to set the hall up again after each session. — [the kit](../kits/photo_studio.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- hours: when it is open — the kit does not guess them
- costs: the price of an hour
- the halls: each one and what tells it from the others
**Taken by default — say it, get a yes**
- Every booking waits for the business to confirm it (`confirm: by_hand`), holding its time for 12 hours and then lapsing (`hold`) — or are bookings confirmed at once?
- A visitor may cancel or move their booking themselves until a day before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Bookable up to 60 days ahead (`horizon`).
- No sooner than 2 hours from now (`lead`).
- 30 minutes kept free after each booking, to get ready for the next (`buffer`).
- Start times offered every 30 minutes (`slot_every`).
- Shown to visitors: every studio's name and its distinguishing marks, wherever a visitor may choose one; what is booked and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### restaurant (tables)
A restaurant: a table for the length of a sitting; a visitor says how many they are, and the smallest table that seats them is theirs. — [the kit](../kits/restaurant.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- hours: when it is open — the kit does not guess them
- the tables: each one's seats
- how long a sitting takes, if not two hours
**Taken by default — say it, get a yes**
- A booking is confirmed at once (`confirm: auto`) — or does the business confirm each one by hand?
- A visitor may cancel or move their booking themselves until 2 hours before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Bookable up to 60 days ahead (`horizon`).
- No sooner than an hour from now (`lead`).
- Start times offered every 15 minutes (`slot_every`).
- A visitor books for up to 8 at once (`party`).
- Shown to visitors: every table's name and its distinguishing marks, wherever a visitor may choose one; what is booked and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### salon (masters)
A salon or a barbershop: services by the hour, masters who each keep their own hours and say what they do. — [the kit](../kits/salon.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- hours: when it is open — the kit does not guess them
- the services: each one's takes and costs
- the masters: who they are, their own hours when they differ, what each one does
**Taken by default — say it, get a yes**
- A booking is confirmed at once (`confirm: auto`) — or does the business confirm each one by hand?
- A visitor may cancel or move their booking themselves until 3 hours before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Bookable up to 60 days ahead (`horizon`).
- No sooner than an hour from now (`lead`).
- 10 minutes kept free after each booking, to get ready for the next (`buffer`).
- Start times offered every 15 minutes (`slot_every`).
- A visit may be several services, one after the other (`combine`).
- Shown to visitors: every master's name and its distinguishing marks, wherever a visitor may choose one; what is booked and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
### sessions (classes)
A studio of classes: each class keeps its timetable in its own hours and has places; a visitor books a place. — [the kit](../kits/sessions.md).
**Ask**
- zone: the business's time zone — from its address; say it back rather than asking
- the services — the `services` collection, one entry per kind of class (block type `course`): how long a session takes and what one place costs — `per: "person"`, so a party of two pays two places (wiki/70)
- the classes — the `sessions` collection, one entry per timetable (block type `session`): its weekly hours, one row per session's start, and how many places it has
**Taken by default — say it, get a yes**
- A booking is confirmed at once (`confirm: auto`) — or does the business confirm each one by hand?
- A visitor may cancel or move their booking themselves until 12 hours before it starts; after that only the business can (`cancel_until`).
- Nothing is paid online: the visitor pays on the day (`payment: no`) — or a deposit, or in full when booking?
- Bookable up to 30 days ahead (`horizon`).
- No sooner than an hour from now (`lead`).
- Start times offered every 15 minutes (`slot_every`).
- A visitor books for up to 2 at once (`party`).
- Shown to visitors: every class's name and its distinguishing marks, wherever a visitor may choose one; what is booked and their prices. Nothing goes into the marks that the client would not want printed.
- A new booking is sent where the site's enquiries go — the Telegram chat or the email a person links in the panel; an agent cannot link one. Ask which, and say it is theirs to link before the launch.
A business none of the kits is for takes the nearest one, its `kind` and both of its lists, and writes over the words that do not fit — the trades an agent meets, each with its kit and what no kit has, as [kits](../reference/kits.md#a-business-not-among-the-kits) says:
| business | nearest kit | words to write over | what no kit has |
| --- | --- | --- | --- |
| barbershop | `salon` | none — «майстер» fits | — |
| nail or beauty studio | `salon` | none | — |
| yoga or dance studio | `sessions` | none — classes with places | — |
| personal trainer, one to one | `salon` | the resource: «майстер» → «тренер» | — |
| group trainer | `sessions` | none, or the class's name | — |
| photographer in a studio | `photo_studio` | none | — |
| photographer who comes to you | `salon` | the resource: «майстер» → «фотограф» | the customer's address: in the note |
| excursions and tours | `sessions` | the booking: «заняття» → «екскурсія», in `letter.*`, `page.*`, `diary.*` | a meeting point per tour: the kit's entries have no field for it — a field added to the schema, or the page's own text |
| tutor | `salon` (one to one) or `sessions` (a group) | both the resource and the booking: no kit says «урок» or «учень» | — |
| master who comes to the customer — a plumber, a massage at home | `salon` | the resource, and the booking where «запис» does not fit | **the customer's address**: there is no field for it, only the note |
| karaoke room, billiard table, a court by the hour | `photo_studio` | the resource: «зал» → «кімната», «стіл» | — |
| parking | `coworking` by the hour, `equipment_rental` by the day | the resource: «місце» → «паркомісце»; the booking | **the car's plate**: only the note |
| guest house | `apartments`, or `hotel` where rooms are of types | none | — |
| hovercraft or boat hire | `equipment_rental` | the resource | — |
## Before it is handed over: the self-check
A site that takes bookings is not handed over until the server has walked a
booking through the whole chain on the build published now. `preflight` with
`self_check: true` asks for it. The server books as a visitor would — on
rows nobody sees and nobody is told of, deleted when it ends — and walks it
through what the owner and the customer do: the state it is made in, checked
against the kit's rule (a kit that confirms at once books it confirmed);
confirmed, refused, moved by the owner, another time offered and accepted,
«it suits», moved and cancelled by the customer, cancelled by the owner, the
time free again. Every letter on the way is written by the code that sends it,
and read: no hole left, no field empty, no word of another kind of business,
the site's language.
1. Run `preflight` with `self_check: true`.
2. Read the steps under `self_check`: each is `passed`, `failed`,
`blocked` — it could not be walked: no published build, or no free time
in the next three weeks, which is the setup's fault — or `not_applicable`:
nothing of it on this site, as a kit that confirms at once has nothing to
confirm.
3. Fix what a failed or blocked step names, build, publish, and run it
again — once a minute at most.
4. Do not say the site is done until `preflight` says `ready`. A site that
takes bookings is not ready while the self-check has not run, failed,
could not be walked, or is of an older build — a version published since.
What it does not check: the booking form's script on the page
(`try_booking` books through the form), whether a letter is delivered, and
the payment — it never pays. A site that takes money online is advised
`JTK_W_PAYMENT_UNCHECKED`: check the payment by hand, and tell the owner it
was not checked.
## A shop: the shop kit
**A shop is not built from nothing either.** It is laid over the site with
`npx @jtakeit/astro add shop` — **whole**, beside a booking kit or without
one — and the business's facts are put into it: the products collection and the
product type, the shipping settings it starts from (one zone, two methods with no
price) and the storefront's components to copy. [The shop kit](../kits/shop.md)
is the platform's, [the shop on the site](shop-on-the-site.md) says what it lays
and what the page draws, and leaving something out of it is a decision, written
under *Decisions*, as a booking kit's is.
It has the same two lists, and both are the kit's own:
**Ask**
- the catalogue: what it sells and roughly how many products — a spreadsheet, or a WooCommerce or Shopify export, with the SKUs and the stock it already has
- variants and customizations: whether any product has variants (sizes, colours) or customizations (a name on a tag) — customizations are written only for the products that have them
- the country it sends from: the zone the kit starts with — from the address; say it back rather than asking
- where it ships, and each method's price: flat or by weight, and free above a total
- pick-up: whether the business offers it, and where to collect
- VAT: which products are not ordinary goods — books, food, children's clothing — where the business charges it
**Taken by default — say it, get a yes**
- Stock is counted for every product (`tracked`), and a product nobody stocked is sold out until its count is set — or is any made to order (`tracked: false`)?
- A checkout holds what it sells for 31 minutes while the buyer pays on Stripe's page; the last item goes to the first who goes on to pay.
- Every order is paid online — by card, Apple Pay or Google Pay — a pick-up too.
- The buyer gets a confirmation, and an *on its way* email with its tracking link, or *ready for pick-up*, when the owner marks the order fulfilled.
- New orders go where the site's enquiries go — the Telegram chat or the email a person links in the panel, which an agent cannot link.
- VAT and paying in one's own currency are off until the owner turns them on, on the site's Payments screen.
**A person's steps, said in the brief.** An agent does none of them, and each is
the business's to do in the panel: **connecting the business's Stripe account**
(nothing is paid before it is), **linking where new orders go** (the Telegram
chat or the email, in *The site → Notifications*), and **switching VAT on** and
the buyer's **own currency** on, on the site's *Payments* screen. And the
studio's: a **shop line** on its plan beside the site's, under *Reselling*, by
its owner or admin — a site that sells is refused its launch without one. Say to
the developer, in the brief, that these are theirs to do before the launch, and
write each under *Open*.
**The tax code.** A product's `tax_code` is Stripe's — `txcd_` and eight
digits — and decides the VAT only where the business charges it. Ordinary goods
unless the business says otherwise: a product with none is taxed as that. Ask
which products are not ordinary goods and give each the code of what it is,
from the short list the panel offers by name, or *Another code*, typed, for any
other of Stripe's; never a rate, which Stripe applies for each country.
| the panel offers | `tax_code` |
| --- | --- |
| Ordinary goods | `txcd_99999999` |
| Printed books | `txcd_35010000` |
| Children's books | `txcd_35010001` |
| Newspapers | `txcd_35020100` |
| Magazines | `txcd_35020200` |
| Food and groceries, not eaten on the premises | `txcd_40040000` |
| Clothing and footwear | `txcd_30011000` |
| Children's clothing and footwear | `txcd_30011200` |
| Another code | any other of Stripe's, in the same shape |
## Where it is written
`BRIEF.md` at the root of the site's repository, in this shape:
```markdown
# — brief
Read on . Sources: developer , , .
## In one sentence
## The one action
## Facts
| Fact | Value | Source | <- every row sourced; `NEEDS CLIENT` where it is not
## Bookings
The kit: , whole — or what was taken out, under Decisions.
| Asked | Answer | Source |
| Default | Confirmed / changed to | Source |
## The shop
The kit: shop, whole — or what was taken out, under Decisions.
| Asked | Answer | Source |
| Default | Confirmed / changed to | Source |
## Decisions
## Open — NEEDS CLIENT
```
It is the client's repository too: nothing goes in it that you would not show
them. The facts that the page prints — the name, the address, the phones — go
into `src/data/site.ts` as well, confirmed ones only.
## Done when
The list under this heading is a task list — `- [ ]` and `- [x]` — that
`jtk create` seeds from this guide's lines and the kit's asks (add a line
below that a scaffold did not seed), and that the panel shows the owner as
*the agent's own list*, in your words, beside what the files say. Keep it
true; nothing checks it but the person reading it.
- every fact has a source, and every gap is `NEEDS CLIENT`;
- the kit is taken whole, or each thing taken out is under *Decisions*;
- every default has been said back and answered;
- the icon: the business's mark, or the monogram said back and accepted;
- the design: adapted, or the developer said to keep the example's look;
- nothing of the example's words or photographs left, or each one kept by
the developer's say;
- the developer has read the brief and said yes.
---
# The design: the floor and the axes
Every site stands on the same floor and differs on its axes. The floor is *how*
a site is built — the same on every site, never compared, and it never makes two
sites alike. The axes are *what it looks like* — the choices every site makes,
each with the variants sites already built took. Choose a variant per axis from
the business's own material, or make a new one; nothing here refuses a site
for resembling another. The person decides what their site looks like.
The variants below come from the sites Brumy (brumy.ch), jtakeit's maker, built
on the platform. They are a catalogue to draw from, and it grows the way it
started: a variant enters when a site has built it.
## Look at what has been built, first
Before `DESIGN.md`, look: `get_design_catalogue` holds the pieces of those
sites — heroes, headers, phone menus, galleries, price lists, proof, contact
blocks, footers, motifs, whole pages, and pieces with no axis at all — as
pictures with their code, what each is, why it suited its business and how
another would adapt it. Browse it whole (no arguments), then by a kind, an
axis, a site or words, then a few pieces close (`ids`) with their code. Take
ideas and make them the business's own, from its material; never a palette,
words or photographs that are another's.
## The floor
The scaffold carries it in both looks — the template and the bare one a custom
design starts from — as tokens and defaults. Keep it when you rewrite the
design; each item is something every visitor feels, whatever the look.
| | Rule | Why |
|---|---|---|
| F1 | **The screen's height is `--screen`**, never `vh`, `svh` or `dvh` in a height | the browsers inside Telegram, Instagram and WhatsApp resize the viewport under `vh`, and the page jumps |
| F2 | **Fonts don't jump**: the site's own font files, the first screen's faces preloaded, fallbacks with metric overrides (`jtk fonts` measures a pair); no font from a third-party host, no family named and never loaded | the text reflows when the font arrives, and a family that is never loaded silently falls back |
| F3 | **Numbers line up**: tabular lining figures wherever money, times and durations are drawn | prices and times are read in columns |
| F4 | **Three measures**: `--measure-read` for text and photographs on paper, `--measure-object` for filled surfaces — a calendar, a form, a card — one width with the header, full bleed for the beginning and the end | the page reads as one system, not a pile of blocks |
| F5 | **One family of corners** from one `--radius`; a nested corner is the outer one less the padding | nothing looks borrowed |
| F6 | **Phones by rule**: a row of up to seven things becomes a swipe with a peek; a long list stays a list; thumbnails share the width, never cropped; a tablet is a large phone, not a narrow desktop | the phone looks designed, not stacked |
| F7 | **Data shows only an action**: the booking form offers the days and times there are | no crossed-out noise, no dead ends |
| F8 | **The first screen answers**: the home page's heading and its one action are on the first screen of a phone (390 × 844) and of a desktop (1280 × 800) | a visitor who sees only a picture does not learn what the business does or how to book it |
| F9 | **A link lands on its words**: a tap on `#kontakt` puts the section's first words just under the header — `scroll-margin-block-start` the header's height and a little air, less the section's top padding | a visitor who arrives at empty padding scrolls again, and thinks the link missed |
| F10 | **What can be seen whole, is**: a section a little taller than a desktop's screen is tightened to fit it; a form with its heading fits one screen | the button of a form is out of sight while it is filled |
| F11 | **A wall of pictures ends on a line**: rows of one height, one proportion, or a picture spanning two — never columns ending apart | a ragged edge reads as unfinished |
| F12 | **«Book» lands at the form**: a button to the booking form links to the form's anchor (`/services/#book`), not the page's top | the visitor who asked to book does not hunt for it |
The kit's lint warns where a site leaves the floor — advice in the build's
findings, never a refusal. `preflight` measures F8–F12 in a browser, in every
direction (`JTK_W_FIRST_SCREEN`, `JTK_W_ANCHOR_LANDING`, `JTK_W_SCREEN_FIT`,
`JTK_W_RAGGED_GALLERY`, `JTK_W_BOOKING_LINK`), and `get_built_page` says F8
beside a picture of the home page.
## The axes
Write the choices in `jtk/design.json` under `axes`, one short line per key — what
and from where, three words or more, never a tag like `split` or `linen`
(`hero`, `ground`, `measures`, `shape`, `header`, `phone_menu`, `overlap`,
`surfaces`, `mark`, `motion`, `fonts`, `hook`, `proof`, `contact`), and the
reasons in `DESIGN.md`.
| Axis | Variants built | Chosen from |
|---|---|---|
| **Hero** | a portrait dissolving into the words · words and a framed photograph side by side · typography as the image over the business's own film · words over a live product window · a reel of their work · their own 3D model, turned or exploded by scroll · an object that is data — the next night as a ticket · a full-bleed photograph after an intro that draws the monogram · a live material field, no photograph | a strong picture of a person, of a thing they make, or neither |
| **Ground** | all light · light with one dark band (the ending, the booking) · a dark hero, then light · a dark room with one light object | the business's hours, its room |
| **Measures** | reading 30–44rem against a shell of 72–94rem | how many objects the business has — a calendar, a menu, a configurator |
| **Shape** | square, 0–2px · small, 3–12px · a scale 6–34px · soft, 10–28px — pills on top, or not | the material: wood and cloth softer, steel and concrete stricter |
| **Header** | a strip that becomes a capsule as you scroll · a floating capsule throughout · a strip that hides going down and comes back going up · a bar with menu panels · the wordmark alone, no navigation | the mark, the number of menu items |
| **Phone menu** | a full-screen wipe · a circle opening from the button in the accent · a dropdown card · a popover · an accordion with a floating action | |
| **The overlap** — one per page | a sheet over the hero's foot that stands up on scroll · a card over a photograph's edge · chips breaking a photograph's frame · the object over their own poster · a caption over a turning object · none but the header over the hero | what the one action is |
| **Surfaces** | always from their photographs or their place — linen, walnut and cork off the room; drafting paper and a millimetre grid; the blue of their tiles; lime plaster and walnut | never the template's palette |
| **The mark** — required | a motif from the business's own material, repeated in the interface: the ring off a logo, drawn; plan annotation and dimension lines; a rail with sleepers; a ticket stub; wood grain; a gloss sheen; a road; a drawer tray; an arch | always this business's, never compared |
| **Motion** | rises and stands up on scroll · scrubbed by scroll · draws · a sheen · timed cycles · follows the pointer — and how many regions always move | the tempo of the business |
| **Fonts** | serif and serif · serif and sans · grotesk and grotesk · a wide variable sans and a mono · condensed capitals and a sans · a heavy display and a sans | their voice, their sign |
| **The hook** | tap where it hurts · a turning product in your colour · a configurator whose price carries into the booking · a price list that adds up · a road of steps with the next free slot · free times on the home page · before and after | the one question a visitor arrives with |
| **Proof** | references with their places · approvals as plates with their validity · a wall of their own posters · ratings in the hero · a pass rate · the tradition's figures · a client's words | what the business must prove |
| **Contact** | one portrait, a form and a phone · two people with their own lines beside the form · the brand alone and a ticket · one WhatsApp message · the platform's diary in the page | how they work with a customer |
Two things are recorded but not chosen from a list: the order of the home
page's sections, which follows from what the business must prove, and the
transition between pages.
**Live data is the platform's own advantage.** The diary, the events and the
shop are on the platform, and a page can draw them: the next free lesson in the
hero, the free times on the home page, the next night as the hero itself. Where
the business has them, consider it before a static picture.
## Directions to choose from
When the person is shown two or three designs before one is built, declare
them in `jtk/design.json`, each with its own axes:
```json
"directions": [
{ "key": "a", "name": "Lehm & Leinen", "axes": { "hero": "…", "mark": "…" } },
{ "key": "b", "name": "Salbei", "axes": { "hero": "…", "mark": "…" } }
]
```
The first is the default — the site's own styles are it. Style the others under
`html[data-direction='b']`: the platform writes the attribute on a page asked as
`?direction=b` by somebody who may see the site (never for the public), keeps
the choice for the next page, and offers the directions by name on the
preview's badge and in the preview in the chat. `get_built_page` takes
`direction` for a picture of one. Never a switch of the site's own: nobody
can reach it.
**A direction is a design, not a palette.** Two directions differ on at least
three axes, the hero among them — another hero, another shape, other surfaces,
another mark. Directions that differ in colour and a typeface are one design
recoloured, and the build says so (`JTK_W_DIRECTIONS_ALIKE`); a custom design
that chooses fewer than ten axes or no mark is said too (`JTK_W_DESIGN_AXES`).
Once the person has chosen, make the chosen one the site's own styles, take the
others and `directions` out, and write its choices under `axes`.
## What a model reaches for
A design nobody held to the business's material comes out the same everywhere.
Stay away from these unless the business's own material asks for one by name —
each is fine once, chosen; together they are a model's site:
- a display serif of the moment (Fraunces, Playfair Display, Cormorant) over Inter;
- cream or linen with terracotta, or sage green, as the palette;
- the photograph in an arch, a radial glow or a blurred blob behind it;
- pill buttons on everything, every section centred, numbered cards;
- icons for ornament, an emoji in a heading, a gradient on the words;
- a hero that is a photograph first and the words under the fold.
## Look before the person does
Before the person sees a direction, look at it as a demanding designer would:
`get_built_page` with `shot: "review"` pictures the first screen of every
direction at a phone's width and a desktop's, says what the platform reads of
the design — the axes, the mark, the faces, the business's own photographs
against the trade's stand-ins, the fold — and asks the questions; answer them
against the brief,
the axes and the floor — the first screen, the mark, whether it could be any
other business's site — and what lies below it: the floor's F9–F12. Fix what
that finds, and look again: two rounds.
## Ask at the end
A message that shows the person their site ends on one short paragraph, never
a report: which direction they like, where there are several; what they would
change; and, where you see one, an offer in a sentence — a section to add or
take out, a motion, something the platform does that their site does not use
yet (the two-week timetable, the shop, a journal).
---
# Bookings on the site
What a site that turns the bookings module on has to draw. The rules — when
the business is open, how long a slot is, whether a time is still free — live
in one place and it is not the page: every address the page talks to is served
by the platform on the site's own host, and the page renders what they answer.
Those addresses, the visitor's own page, the letters and Turnstile are
[the booking protocol](../reference/booking-protocol.md); this page is what to
draw with them.
## Turning it on
For a business of a kind the platform knows — a salon, a clinic, a car
rental, a hotel and the rest — start from its [kit](../reference/kits.md): the
collections, the rates and the settings below, already laid out for the trade
and judged on the way past. What follows is what a kit is made of.
The schema declares the module and points it at two collections:
```jsonc
"modules": {
"bookings": {
"services": "services", // entries carrying `takes` (minutes) and, to be payable, `costs`
"resources": "masters" // entries that get occupied; one entry is a solo business
}
}
```
The shape the two entry types have to be — `takes` as a `duration`, `costs` as
`money`, `hours` as a list of `day`, `opens`, `closes` rows — is generated from
the module's own declaration in [modules](../reference/modules.md), and the
validator holds a schema to it: a services type with no `takes`, or a key
of the wrong kind, is refused before any build.
**Paid online, or on the spot?** Ask before deciding. A rate without `costs`
is bookable and not payable, and that is the ordinary state for a business
that takes its money on arrival — a bowling club, a hairdresser with a till.
Where the current site books without paying, say so and ask whether paying
online is to be *added*; do not switch a business to online payment because
the module can. **A price that depends on the day and the hour** — a lane 25 € before six
and 42 € on a Friday night — is the service's `rates` *instead of* `costs`:
rows of `day`, `from`, `until` and `costs`, a week of opening hours with a
price on each row. See *A price by the hour of the week* below. Not a rate
per price zone (the visitor would be left to match the zone to the time, and
nothing would check it), and not one price near enough with a footnote (the
form would name a sum the till does not).
A resource entry may carry its own weekly `hours` — a list of `day`, `opens`,
`closes` rows, the same shape as the module's — and is then offered only inside
them and inside the business's own. The business's hours, days off, the
confirmation mode, the cancellation window and the payment policy are the
module's settings document, which the client edits in the admin under the
diary.
## A record, not a post — and every fact once
What the module reads is a record the diary occupies or offers, and the panel
draws it as a form. Two mistakes the first booking-enabled sites made, both
valid schemas, both wrong:
- **The blog's shape copied onto a service or a table.** An excerpt, a cover, a
`body` of eight thousand characters and a page at `/tables/` for each
one. A service is short fields — a name, `takes`, `costs`, a line — with no
`body`, and its collection's `route` is `"none"` with `shown_on` naming the
price list's page, because it is a row of the price list the form reads. A resource is a name with its own `hours`, what
it `does`, `seats` or `spots`; a master may well have a page and a paragraph
about her, a billiard table may not.
- **A fact the module holds, typed again as text.** Opening hours as `day` and
`time` text rows on a page block, beside the hours the owner keeps in the
diary; a tariff block with `price` as text, beside the services' `costs`.
Two copies, and the page's goes stale the day the owner changes the panel's.
The hours live in `jtk/modules/bookings.json` in the repository — the page
reads its opening hours from there, through the kit's door
(`site.module('bookings')`) — and the price list is the same `services`
entries the form reads.
**Seed the hours in the commit.** `jtk/modules/bookings.json` is read by the
import (`push_code`'s push, or `import_branch`) into the diary's settings, and
`publish` makes them what the preview offers: a demo takes bookings with nobody
opening the panel. The owner changes them in the diary afterwards, and the
next publish writes them back to the file — one place, edited from either side.
Until the first publish the settings are a draft: the setting up already
counts them (the launch publishes them), a visitor does not see them yet.
The file is the module's own document, and its shape is the one publish
writes: `v`, and the settings under `settings`, every row of a list with its
`_key` ([the files under `jtk/`](../reference/jtk-files.md) and
[modules](../reference/modules.md) have every field). `jtk create --kit`
lays it out, and `npx @jtakeit/astro schema` seeds an empty one when the
schema turns bookings on and the file is missing:
```json
{
"v": 1,
"settings": {
"zone": "Europe/Warsaw",
"hours": [{ "_key": "mon", "day": "monday", "opens": 540, "closes": 1020 }],
"horizon": 30,
"confirm": "auto",
"payment": "full"
}
}
```
Written any other way — the settings as top-level keys is the mistake that has
actually been made — the file is refused
([`JTK_E_DOCUMENT_INVALID`](../reference/errors.md#jtk_e_document_invalid)),
by the import and by `validate_schema`, so the diary is never imported empty
and then written back empty over the seed. Send the file in `validate_schema`'s
`files` before the push, and it is judged with the schema.
On a contract-2 site the settings are `jtk/bookings.json`: a document of one
block of type `bookings_config`, the settings as the block's fields —
`{"blocks": [{"type": "bookings_config", "v": 1, "zone": …}]}` — refused in
any other shape with
[`JTK_E_MODULE_FILE_INVALID`](../reference/errors.md#jtk_e_module_file_invalid).
`jtk upgrade contract-3` moves it to `jtk/modules/bookings.json`.
**What is booked is in every language, always.** On a site in several
languages a service, a master, a class — any entry of a collection the module
names — is offered in every language's form, in the original's words where
nobody translated it: its collection cannot say `untranslated: "hide"`, and its
translation cannot hold it back
([a site in several languages](languages.md#what-nobody-translated)). The diary
reads the original, so the form names a service by the original's slug
(`entry.baseSlug`), whatever a language calls it.
The validator says both as **advice** rather than a refusal:
[`JTK_W_MODULE_POST`](../reference/errors.md#jtk_w_module_post) and
[`JTK_W_MODULE_TWIN`](../reference/errors.md#jtk_w_module_twin), under `advice`
in `validate_schema`'s answer, once nothing is refused. Act on them before
the first build; they are what the studio would otherwise say after opening the
panel.
**Prove it without a browser.** `preflight` with `try_booking` walks the
visitor's path under your own session — on the preview before the launch, on
the address after: the ticket is exchanged for a cookie, a free slot of the
first service a visitor can book — shown, in the site's own language, with a
length (`takes`) and somebody who performs it — is booked through `/api/book`,
and the booking is cancelled again. A booking made under a session that may view the site is a test row,
which is why it pays no Turnstile and never reaches the business as a
customer's; it is booked under an address on `.invalid`, so no letter goes
and the business is not told of it.
**And the whole chain, on the server.** `preflight` with `self_check` has the
server walk a booking through what the owner and the customer do, on the
build published now: booked as a visitor and checked against the kit's rule,
confirmed, refused, moved by the owner, another time offered and accepted,
«it suits», moved and cancelled by the customer, cancelled by the owner, the
time free again — every letter written by the code that sends it and read for
holes, empty fields, another kind's words and the site's language. Its rows
are seen by nobody and told to nobody, and deleted when it ends. A site that
takes bookings is not `ready` until it has passed on the build published now;
[the brief](the-brief.md#before-it-is-handed-over-the-self-check) has the
steps, and what it leaves to a person: the form's script, a letter's
delivery, the payment.
It books **in the shape your form sends**, read off the built page: the form
marked `data-booking` on the booking page (`page` in the bookings' settings)
lists the fields it posts in `data-sends`, and nothing else is sent. It is one
list separated by commas — `data-sends="service,start,name,phone,email,note"`;
written with spaces or as a JSON array it is not read, and the check says so
before anything is booked. A rate
taken several at once is booked for more than its fewest, a site that takes
parties for two. So a form that sends `units` for nights is refused by the
edge, and one that never sends `count` where a stay is one to thirty nights
fails before anything is booked. The form from `npx @jtakeit/astro create`
says it and sends nothing it does not say; a form written by hand must list
its fields in `data-sends`, or the check fails as **NOT CHECKED** — a
booking made the platform's way would prove nothing about your form.
## Several nights, or several hours, at once
A rate sold by the day — a night of a hotel, a day of a car — is taken several
times in one booking, and so is a rate by the hour whose `most` is above one —
a studio's hour, one to twelve. The page asks how many with **`count`**: on the
availability (`&count=4`) and in the booking's body (`"count": 4`), the same
number on both, so the times offered are the ones a stay that long fits. The
platform makes the end and the price from it — the rate's `takes` and `costs`
times `count`, and on a business by the day the letting runs from the hand-out
hour to the hand-back hour — and never takes either from the page.
- Absent, it is the rate's `fewest`. Outside its `fewest`…`most` the answer is
`400` with the range in the sentence. A visit of several services is taken
once. Each service's `fewest` and `most` are in the availability answer's
`services`; by the hour, ask «how long» only where `most` is above one.
- There is no `units`, `nights` or `days`, and `"count": "4"` is not `4`. Sent
from a preview or under the studio's session, either is refused with
[`JTK_E_BOOKING_FIELD_UNKNOWN`](../reference/errors.md#jtk_e_booking_field_unknown);
from a stranger it is dropped and the stay is booked at its fewest — one
night, whatever the form said. Try the form once on the preview.
- **`class`** books «any of this class» where no `resource` is named, for a
business whose rates are sold in classes — a room type, a car class. The
answer's `resource` says which one was given, and `class` the one promised.
`/api/availability` lists the classes that can be asked for in `classes`,
and a class nothing is in yet — a room type with no room — in
`empty_classes`: say it and do not let it be chosen. Asked anyway, it has no
free day, ever.
- A service nobody performs — a salon's service no master does — is still in
`services`, and is named again in `empty_services`: say it and do not let it
be chosen, the same way. Asked anyway, it has no free time, ever.
## A price by the hour of the week
A service whose price depends on the day and the hour carries **`rates`**
instead of `costs` — never beside it, and the validator refuses both on one
entry. Each row is a `day`, a `from`, an `until` and a `costs`, the same
shape as a week of opening hours with a price on each row; a row whose
`until` is before its `from` runs past midnight, as an hours row does.
```jsonc
// jtk/entries/services/bahn.json
{ "id": "0193a5c3-…", "collection": "services", "slug": "bahn", "visible": true,
"fields": { "title": "Bahn", "takes": 60, "most": 4,
"rates": [
{ "_key": "fr1", "day": "friday", "from": 540, "until": 1200, "costs": { "minor": 2500 } }, // 09:00–20:00
{ "_key": "fr2", "day": "friday", "from": 1200, "until": 60, "costs": { "minor": 4200 } } // 20:00–01:00
] } }
```
(On a contract-2 site the same entry is a block of its type with `costs` a
bare number of minor units, `2500`.)
- **A business open past midnight** writes the hours after it on the
calendar day whose clock shows them, not as a continuation of the night
before: a lane 32 € from 01:00 to 03:00 on a Saturday night is a row for
`sunday`, `from: 60, until: 180`. A row whose `until` is before its `from`
(`friday 1200 → 60`) is the one other shape, for a span that *starts*
before midnight; `time_of_day` never goes past 1439. A unit is priced by
the row of the weekday its start falls on — a bar's 00:30 on Saturday is
Saturday's row, or Friday's row running past midnight if there is one.
- **Each unit is priced by the row covering its start**, and the booking is
the sum. A lane sold by the hour (`takes: 60`) booked Friday 18:00–21:00 at
a before-eight and an after-eight price is two hours at one and one at the
other. Not a share by the minute, and not the first hour's price for the
whole.
- **The price is the slot's.** Every slot in the availability answer carries
`costs_minor`, the full price of the booking starting there for the service
and the count asked about — for a flat price too, so a form has no mode to
know: print the slot's price beside the chosen time whenever one came.
`prices` is `0` for a service priced by time, because it has no price until
a time is chosen; the list of services says «from …» from the rows.
- **An open hour no row covers is not sold.** The form is not offered it for
this service, a page of its own that asks for it is refused with *that time
has no price*, and the panel says which hours those are, beside the rate —
a table copied from a website has a gap somewhere, and this is where it is
found rather than by a customer who could not book Tuesday noon. Write the
whole week; the panel's list editor is made for ten rows.
- **Two rows on one minute of one day are refused**, by the validator before
any build and by the import, with both rows named. A price two rows claim
is a price nobody can explain to the person charged it.
- **The deposit, the frozen amount, the class.** The share is taken of the
sum as it is of `costs × count`; the line on the booking says the sum of its
units and is never read from the table again; a class's `costs` on a letting
business outranks the rows as it outranks `costs`.
The kit's `renderBookingForm` says «from …» beside a service with rows (pass
`rates` with the entry's other fields) and `` prints the slot's
price beside the time; a site's own form reads `costs_minor` off the slot or
ignores it and books exactly what it books today.
## What a price depends on
A unit's price is the service's table at the unit's moment of the week
(`costs`, or `rates`), and two more things the same table takes:
- **The unit's index in the booking.** A `rates` row may say which units it
is for — `from_unit` and `until_unit`, counted from one, `until`
exclusive, open when absent. The club's billiards on a Friday night is
three rows on one span: 16 € for any hour, 14.40 € for the second
(`from_unit: 2, until_unit: 3`), 12.80 € from the third (`from_unit: 3`).
**The most specific row wins**; two rows of one window on one minute are
refused as two prices. Absolute prices, never percentages: the row says
the number the till charges.
- **The party.** A service may say `per: "person"`: its price is times the
party — a class per place, a tour, a tasting. Without it, `booking`: a
haircut is one head whatever the party says. In a group each row's
share of the party is what its price is times.
- **An add-on**: a service with a price and no `takes` — shoes, a racket, a
towel. Taken only beside a timed service in one visit (`combine` on),
priced once per visit, times the party when `per: "person"`; alone it is
no service. The validator advises an add-on on a site whose visits take
one service — `JTK_W_UNPRICED_HOURS`'s neighbour, `JTK_W_ADDON_ALONE`.
- **A package** is a service: Late Night, two hours for 45 €, is `takes:
120` with `rates` rows covering only the late window.
Not a price: a percentage, a discount for three lanes, a member's price, a
no-show fee (a policy after the fact — the deposit does its work in
advance). Seasons by date are the next key on the row, when a hotel asks.
## Several of a class in one booking
Three lanes for a birthday, two rooms for a family, two cars for a crew: a
booking is one resource, and several of a class are **a group** — the rows
one request made, sharing a party, a payment and a page. The owner allows
it in the booking settings (*Most in one booking*, `quantity`; one by
default, and the form never asks). The availability answer carries it as
`quantity_max`, and a slot's `free` says how many are free there.
- **Send `quantity`** on `POST /api/book` with a `class` (or nothing — any
of all). Never with a `resource` named by slug: a name is one thing, and
«lanes 2 and 5» is «any two» or two requests. Never on a session
(`spots`): its places are the `party`.
- **The party is asked once**, as now, and seated across the chosen
resources: the set that seats it with the least seats over, each row
keeping the share seated on it. Fewer free than asked is no booking:
`409 {"error": "only 2 free then", "free": 2}`, with the number so the
form can offer two.
- **The answer** is the first row's, as it always was, plus `group`:
`{ id, quantity, party, bookings: [{ id, resource, resource_name,
amount_minor, party, state }], amount_minor }` — the sum. A page built
before the group reads what it always read and books one.
- **Paid together**: `/api/pay` under the first row's id takes the group's
sum, and every row is marked paid. Each row keeps its own price, so one
lane cancelled alone is refunded alone.
- **One page, one letter, one reminder.** The visitor's page under any
row's token lists the group and offers to cancel one or all (`POST
/api/booking/cancel` with `"all": true`); rows that start together move
together. The letters name every lane.
The kit's form draws «How many» when `quantity_max` is above one, bounded by
the chosen slot's `free`, and the receipt says the lanes and the sum.
## Four businesses, one module
The module reads three more keys from a resource's card — `does`, `seats`,
`spots` — and one from the settings, `party`, and with them it is a workshop,
a consultant, a class or a restaurant without a second module
([modules](../reference/modules.md) says each in one line). The schema
reference carries one worked schema per business, judged by CI: copy the one
that matches and change the words.
| business | services | resources | the visitor is asked |
| --- | --- | --- | --- |
| a workshop of masters | each with `takes`, `costs` | each master with `hours` and `does` — what they perform; empty is everything | a service, then any master who does it or a named one |
| a consultant | each kind of meeting | one resource with `hours` | a kind of meeting and a time |
| classes | one per kind of class, `takes` the session length | one per timetable, with `spots` and `hours` naming the sessions; a resource with spots offers the *start* of each row and nothing in between | a class, a session, and how many places |
| a restaurant | one, *a table*, `takes` the turn time | one per table with `seats`; the business's hours are the service periods, lunch and dinner as two rows | a day, a time, and how many — the smallest table that seats them is theirs |
`seats` and `spots` are two kinds of resource: a table takes one party that
has to fit, a class takes as many bookings as it has places. A card that
claims both is refused, and so is a party larger than the settings allow.
## The form, by default — the rules a visitor needs
The kit's element (`@jtakeit/kit` 0.5 and later) draws these over the form,
and a form drawn by hand keeps them: each one is something a visitor ran
into on a real salon's page (10 October 2026) and should not run into again.
- **Two steps**: what and when, then who is coming — the choice summarised
beside the name (what, with whom, when and until when, how long), a way back.
- **The day as a week of seven** from today, closed days struck out, **never
yesterday**: the floor is the browser's today in the browser's own day, not
the build's and not UTC's.
- **The times by the part of the day**, one part at a time, each tab saying
its hours; a part of one or two times joins its neighbour.
- **A master chosen greys out the services they do not do** («not with
Noa») and unticks them; *Anyone* brings them back. The resources carry
`does` for this.
- **A time picked stays picked** across a change of services if it is still
offered; otherwise a line says the visit is a different length now.
- **The end of the visit** under the times, from the answer's `ends`.
- **A 24-hour clock in every language**; the markets do not read «11:15 AM».
- **The success shows the link whole, with Copy, and says to keep it** — it is
the booking's only key. The visitor's page wears the site's clothes
(`/_jtk/booking.css`, [the visitor's page](../reference/booking-protocol.md#the-visitors-page)).
- **The Turnstile widget in the page's colours and language**, not the
browser's.
- **The hint says what is missing** — a service, a day — never an error body.
## The form is the site's, not the kit's
The scaffold's `src/components/BookingForm.astro` is **a working base to copy
and design**: the whole form written out, every field, with the scaffold's
look in a `