Skip to content

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, 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 <file> 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/<path>.json for a page, jtk/entries/<collection>/<slug>.json for an entry, jtk/shared.json for the text on every page, jtk/modules/<module>.json for a module's settings, and a translation <name>.<locale>.json beside each original (a site in several languages). jtk/site.json is the platform's, written by its saves.

The format reference has the shape and worked examples, and the files under jtk/ each file's. The short version is that a block declares fields, a field declares a kind, 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": "<jtk/schema.json, as text>",
  "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, 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');
---
<h1 {...hero.at('title')}>{hero.text('title')}</h1>   <!-- data-jtk-path="blocks[hero].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).

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].titlea field of the block whose _key is hero, on this page
blocks[faq].items[r7k2].answera field of a row of a list, by the row's _key
blocks[work].pictures[g2x9].srca picture of a gallery. The words beside it are edited in the panel and carry no annotation
titlean entry's own value, on the entry's own page (its fields)
shared:blocks[contacts].phonethe text that is on every page — see jtk/shared.json
entry:<id>:title, page:<id>:blocks[hero].titlea 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); 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).

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[<key>], shared:blocks[<key>], page:<id> and entry:<id> (each may go on :blocks[<key>]), module:<name>. 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). 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). 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).

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: '<label field>', 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 <data-attribute>:<path> separated by spaces:

astro
<article data-date={date} data-starts={starts}
  data-jtk-bind={`data-date:blocks[night].night_date data-starts:blocks[night].night_starts`}>

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).

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 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/<slug>/ 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_URLthe site's address, https://<the site's address>/. 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/<slug>/, 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_ANNOTATEon for every build. Emit data-jtk-path when it is set; the edge strips it for visitors
JTK_CONTENT_FILEwhere 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), when robots.txt shuts every crawler out (JTK_E_ROBOTS_DISALLOW), when the sitemap is empty or on another host (JTK_E_SITEMAP_EMPTY), or when the canonical is elsewhere (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, 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 <file>, which also mints the ids and _keys the files lack). A business of a known kind starts from its kit: npx @jtakeit/kit apply --kit <kind> lays it out in contract 2's files only, so on contract 3 write its types, settings and rates from its page in contract 3's words, or lay a scratch site out with npx @jtakeit/astro create --kit <kind> and take the files from it.
  2. jtk/pages/, jtk/entries/<collection>/, jtk/shared.json, jtk/modules/<module>.json and the translations beside them, in the shapes of the files under jtk/; 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

  1. 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.
  2. data-jtk-path on every tappable, client-editable field, by key, as annotations says — including entry:<id>:<field> 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.
  3. 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). Both are the kit's: renderBookingForm() and renderLeadForm() give the markup at build time, <jtk-booking> and <jtk-lead> 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 (<jtk-product>, <jtk-cart>, <jtk-checkout>, <jtk-order>, <jtk-listing>), 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).
  4. _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/<slug>/ 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 <meta name="jtk-base"> (or window.__JTK_BASE__), which that preview puts first in <head> 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.
  5. One specimen page per block a post may hold, at the collection's entry address with _fl-<type> for the slug — /blog/_fl-text/ (and _fl-<type>-<view>/ 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.
  6. 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.
  7. 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 '<url>'

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 '<url>' <dir> 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 _keys 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 '<url>' [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 '<url>' 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: <img> and srcset (the largest candidate), <picture>, 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 <img> 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/<n> 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 '<url>' --media '<media url>', which runs the media push before the code, or npx @jtakeit/astro media push '<media url>' 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, https://github.com/apps/jtakeit-connect — 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 <jtk-lead> 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.