kleap.co

Kleap builds, HOSTS and AUDITS real websites (Astro). You have TWO ways to put code on a site: (A) write_files — YOUR model writes the exact file contents and you push them with write_files; Kleap stores, builds and deploys them as-is (deterministic, best when the exact wording, URL or schema matters); (B) modify_app — describe the OUTCOME and Kleap's AI writes the files (best for design and whole sections, and it knows the template's own components, auth, database and form wiring). Either way Kleap HOSTS it (build, deploy, SSL, DB, auth, domains, verified-live) and CHECKS it: publishing audits every internal link on every built page, flags pages whose content contradicts the link leading to them, and measures JSON-LD/sitemap/robots coverage — get_publish_status returns that as a report field. Read the report instead of re-auditing the site yourself. list_app_files shows the structure (Astro: src/pages/*.astro, src/data/*.json, src/components/*.astro, public/*). EDIT EXISTING FILES SAFELY — never rewrite a file blind. Do: list_app_files → read_files(app_id, [paths]) to get the CURRENT contents → edit_files to change ONLY the lines that must change → publish_app. Use edit_files whenever the file exists: send old_string and new_string, Kleap replaces in place. Resending a 30KB layout to fix one line wastes tokens and risks corrupting the rest. write_files stays for NEW files, wholesale replacement and images. This is the reliable way to fix shared components, headers/footers, wrong numbers, broken links, dead forms. read_files works with a Read-only key, so always read before you change. Prefer this read→edit→write loop over modify_app for precise, verifiable edits. That loop is complete: edit_files changes part of a file, write_files takes encoding:"base64" for IMAGES and binaries (logo, photo, OG image, favicon, font), and delete_files REMOVES a page or asset — never blank a file to "delete" it, that leaves a URL answering 200 with nothing. WHAT AGENTS ACTUALLY DO HERE (measured over 30 days of real calls): read_files 141, publish_app 70, list_app_files 36, write_files 31 — and create_app 4. This connector is used to MAINTAIN live sites far more than to create them. So the loop below leads with the edit path; creation is at the end because it is the rare case. THE LOOP 1. Find the site: if the user names it by address ("serrureriesk.ch", "mysite.kleap.io"), call find_app FIRST. If it returns NOT_FOUND, the site isn't on this account or isn't connected yet — fall back to list_apps or ask the user. Otherwise use list_apps. 2. Build/change — two paths: DETERMINISTIC = read_files then edit_files(app_id, [{path, old_string, new_string}]) to CHANGE something that already exists (one line, a price, a link, a shared header — it rewrites nothing else and cannot silently drop the rest of the file), or write_files(app_id, [{path, content}]) for a file you are creating WHOLE; then publish_app(app_id) (no task, no stall, best for exact pages/scaffolding). Reaching for write_files on an existing 30KB page means retyping 30KB to change one line — that is what edit_files is for. AI = create_app(prompt) for a new site or modify_app(app_id, message) to change one. create_app returns instantly with a task_id and a build_url. modify_app does NOT: it waits for the edit to land before answering (median 55s measured in production), so treat it as a call that blocks — do not fire it and walk away, and do not re-fire it because it feels slow. HAND-OFF RULE — CREATIONS ONLY (create_app, 3-11 min): the widget shows live build progress, so give the user the build_url and do NOT block or keep polling check_task; just tell them it is building and they can ask you for the link anytime. EDITS ARE THE OPPOSITE (modify_app, usually under a minute): do NOT hand off. Call check_task once or twice until it reports deployment_status deployed, then get_app once, then answer. Watched live: answering at 17 seconds with "it is deploying" left the user on a build frame for a change that was finished 20 seconds later, and nothing ever went back to show it to them. STAY ENGAGED while it builds (like a real builder, not a silent wait): ask the user 1-2 short refinement questions (brand colors, must-have sections, contact details, logo) and then apply their answers with ONE modify_app once the build is live. If the first request was vague, ask 1-2 quick questions BEFORE create_app to enrich the prompt. If you have NO widget (CLI/headless/API), poll check_task (long-polls, queued/processing/completed/failed, ~5-15 min) for the finished URL. 3. After a create_app/modify_app task status="completed", the files are written; claim the change is LIVE only when deployment_status="deployed". A pending or failed deployment is not live, even if production_url still contains the previous address. After write_files you MUST call publish_app to deploy. connect_domain attaches a domain the user owns (app must be live first). 4. SHOW IT. Once the work is live (check_task returns status completed AND deployment_status deployed, or publish_app succeeded), your LAST tool call before answering must be get_app on that app_id — exactly once. That single call is the only thing that puts the finished site, its screenshot and its address in front of the user; every other tool leaves them looking at a build in progress. Do it even when you are certain it worked, even when you already have the URL in text, and even after you have verified the files yourself — verifying is for you, get_app is for them. Skip it only if the task failed. ON FAILURE (task status="failed"): read error.code/message. For a transient stall, call retry_task — it returns a NEW task_id; poll check_task on THAT new id. Retry at most once or twice; if it keeps failing or is non-transient (out of credits — check get_credits — or a rejected prompt), stop and tell the user. MANY PAGES / PROGRAMMATIC SEO: BEST = write_files — generate a dynamic Astro route (src/pages/[service]/[city].astro) + a data file (src/data/locations.json with your full list) with YOUR model, push both in one write_files, then publish_app. Deterministic, scales to thousands, no stall, no credits. ALTERNATIVE = ONE modify_app asking Kleap's AI for that same dynamic route + data file. Never make N calls (one per page) — that stalls. DATA, ACCOUNTS & FORMS (Astro, the default) — durable data NEVER lives in browser storage. Anything a person expects to keep (accounts, records, bookings, orders, listings, posts, saved results, carts) belongs in the app's first-party Kleap Database, never localStorage / sessionStorage / IndexedDB / cookies — per-device, invisible to the owner and to other visitors, wiped on cache-clear or device-switch (the #1 'my data disappeared' bug); those are fine only for a throwaway UI toggle (theme). Contact / lead / newsletter / booking forms need nothing built — hydrate the seeded island: import KleapForm from '@/components/KleapForm'; <KleapForm client:load formId="contact" fields={[...]} /> collects straight to the owner's Kleap dashboard. The template already ships the data + auth wiring (getKleapDb from '@/lib/kleap-db', read inside a client:load island and RLS-scoped to the signed-in user by default; login UI @/components/auth/KleapAuth), but the database is switched ON only while a data/accounts feature is being built — and that one-time provisioning is exactly what write_files does NOT do (it only stores the files you send). So to STAND UP a data or accounts feature, use modify_app and describe the data/accounts you need: Kleap's AI owns the wiring and provisions the database automatically as it builds — no connect step, no button, no keys. DB or auth code pushed by raw write_files has no backend behind it and silently does nothing. Once the app is provisioned, keep editing those pages with the normal read->edit->write loop. rename_app changes only the display name (URL never changes). There is no tool to delete an entire app; delete_files removes selected source files. AFTER PUBLISH: use get_analytics(app_id) for visitor/pageview/top-page/referrer stats (needs the app to be published — analytics is wired automatically on deploy), get_search_console(app_id) for how the site performs IN GOOGLE SEARCH (queries it ranks for, impressions, clicks, CTR, average position — real Search Console data; if it comes back not connected, connect_search_console(app_id) hands you the Google consent link to give the user, and the property binds itself from there), and get_form_submissions(app_id) to read leads/contacts from any KleapForm-based contact form on the site. Analytics and search both need analytics:read, forms need forms:read: connections authorized BEFORE these tools shipped don't have them — a 403 INSUFFICIENT_SCOPE means the user must disconnect and reconnect (re-authorize) the Kleap integration.