Publish
publishCreate an app from its files, or change one.
A change takes app_id and base_version (the version get_app_context or the last publish returned) and only the files and assets that changed. To change part of a file, send edits instead of the file: "edits": [{"path": "index.html", "find": "old text", "replace": "new text"}]. find must occur once, unless count says how many times, and a miss refuses the publish and says what it found. Without base_version a publish replaces every file. A stale base is refused, so someone else's change is reloaded rather than overwritten. An app is named by an app_id from a reply or list_apps, never found by name.
A create omits app_id and takes intent. Files are a single client-side page: index.html plus css/js, plain text, no build step, no server. Files with SKILL.md at the root and no index.html publish a skill, in one call with all its files. A picture, font or sound is an asset: listed in assets with its sha256 and byte count, and the reply says where to PUT its bytes before publishing again. Changes start from the files get_app_context returned, not the HTML at the app URL. Files carry literal angle brackets.
Every call takes work_context (goal, current_state, decisions, open_work, verification, known_issues; no credentials, transcripts, or stored records) and summary (one line of 200 characters or fewer, in the person's words). When work stops unpublished, checkpoint_app saves that context with the exact base_version.
An app that stores data uses window.cloche and declares collections in schema. get_deploy_instructions returns the runtime API, the purpose-built AI surface, the authoring rules, and the less common publishes: rename, reserve an address before the files exist, share or invite while creating, slug, icon.
A local folder with server code (Flask, Express, SQLite, login routes, database URLs) is rewritten into this shape before publishing. Its server is neither uploaded nor run, its credentials are dropped, and no auth is invented: window.cloche and schema replace them. A rewrite of any existing tool, including a browser localStorage app, keeps every persisted entity and field from the source store, including optional fields and nested groups such as folders, as schema collections and fields, and adds no feature the source lacked.
Data from a private or external source travels as data_publication with the files, never as rows in files or work_context: the collections and fields the app reads and the recipe of read-only tool calls that produces them. Its shape is the example get_deploy_instructions returns. Those collections are shared in schema, and the app reads them through window.cloche.data like stored ones.
Cloche runs the recipe for each person who opens the app with that person's own access to the source, so everyone sees what they can already see there. No model or generated code runs it. An owner's publish goes live; an editor's reading anything new waits for approval at the Data address this call returns, where the owner can keep a copy.
A changed source, argument, selection, collection, or field is a new publication: the files go again with the complete publication details.
The result's bundle_bytes is what the app's files now total, for checking the change. An app far smaller than before was sent truncated, not edited. get_app_context with version returns a past version. Its files published against the live base_version put a damaged live version back.
The result says what looks like personal data in the version and where, when the organization checks for it.
Files are live only when this call returns ready.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | when creating: a Tabler icon name saying what the app is, e.g. list-check. An unknown name is read by its words, then the app name | |
| name | No | display name; with app_id and no files: rename | |
| role | No | for a grant share, user or editor; for a link, omit or user -- a link cannot be editor | |
| slug | No | full label on rename; creation adds the organization handle. Earlier names open until removed | |
| edits | No | with base_version, change part of a file without sending it whole | |
| files | No | the app bundle's files, inline | |
| share | No | when creating: how to share it once live: "link", "public", or "grant" by subject_or_email; omit to keep it private | |
| app_id | No | omit to create; otherwise the app_id from a reply or list_apps | |
| assets | No | binary files (images, fonts, audio, video) by path, sha256 and byte count; the reply says where to PUT the bytes before a second publish | |
| intent | No | when creating: what the app is for, in the author's own words | |
| schema | No | collections this app stores; needs files on create; omit for an app that stores nothing. A replace takes the whole schema again | |
| answers | No | replies to open comments by comment_id, shown under each with this version | |
| summary | No | one line of 200 characters or fewer, naming what this is or what changed, in the words the person would use for it | |
| base_version | No | the version get_app_context or your last publish returned; files may then carry only what changed | |
| organization | No | when creating: destination organization id. Required when you belong to multiple organizations | |
| work_context | Yes | compact continuation state for the next session: no credentials, transcripts, or stored app records | |
| removed_paths | No | paths to delete from the version named by base_version | |
| contract_version | No | ||
| data_publication | No | with files: the collections and fields this app reads from a source, and the recipe of read-only tool calls that produces them; never rows | |
| subject_or_email | No | who to invite when share is "grant": their email address, or their Cloche account id | |
| development_token | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | the app's own URL, a Template's page in Cloche, or a skill's page until it is public. The app stays private unless you shared it | |
| kind | No | "app" or "skill": what this publish put live | |
| name | No | ||
| app_id | No | ||
| reason | No | set when status is "failed" with what stopped the publish, "awaiting_upload" with the next step to finish the upload or "waiting" with who decides | |
| status | No | "ready" when the files are live, "failed" when nothing went live, "reserved" when this call only took the address and there are no files yet, "awaiting_upload" when this call went no further than naming the bytes it needs -- nothing is live, "waiting" when the files are stored and an approver must decide before they go live | |
| answers | No | recorded ids, ignored ids (no open comment of this app has the id, or the answer was blank or repeated) and unsaved ids (a server problem kept the answer from being saved, so send it again) | |
| uploads | No | set when status is awaiting_upload: a signed url per asset that takes its raw bytes by PUT. The same publish arguments sent again then complete it | |
| version | No | the version this publish put live, and the base_version of the next change to this app | |
| data_url | No | where the owner keeps a copy, and approves a data update that waits | |
| deploy_id | No | ||
| share_url | No | the link people open, when share was "link"; the app's own URL stays private | |
| access_note | No | set on every publish while the app is private with nobody invited and no link, so only its owner can open it, and on every skill publish with who can install it; this result's own message already says it | |
| asset_bytes | No | what this app's assets total now, against asset_cap_bytes | |
| bundle_bytes | No | what this app's files total now, against bundle_cap_bytes | |
| personal_data | No | what looks like personal data in this version, as a count, a kind and a place such as "3 email addresses in index.html", then each file that was not checked. It holds no value | |
| asset_cap_bytes | No | ||
| continue_prompt | No | usually absent today; when present, a short message the person can paste into any agent to keep working | |
| bundle_cap_bytes | No |