cloudgeni-ai/opengeni/sites

Sites

A Site is a saved page or web app in the workspace: one self-contained HTML file that the console shows, shares and can put on the web, plus optional editable source. Sites have no server of their own; Opengeni AI, tools and saved data come from the host.

Do not invent a Site framework, deployment service, App Host, custom domain setup, provider-specific API wrapper, or platform-only build CLI. Putting a Site on the web is built in (see "Publish to the web").

Pick the path first

• Single-file Site: one HTML page with inline CSS and plain script, no

build. A page to read or look at (recipes, an event page, a menu, a CV, a short report), or a small personal tool that keeps the viewer's own entries (a blood-pressure or habit log, a reading list, a form that collects answers). No workspace tools, no AI, no data that several people edit together. Follow "Single-file Site" below; nothing else in this Skill is needed.

• App: needs React or a build, workspace tools, AI or chat, data several

people share or edit, Site SQL, or several views with their own state. Follow "Apps" below and read only the reference files the app needs.

Build what the person asked for. Offer likely extras (export, notes, editing, filters, more charts) in one sentence of the reply instead of building them. A Site you can finish in this turn needs no goal.

Single-file Site

The person should have a working link in a minute or two, after a handful of tool calls.

1. Do not set a goal, start workers, install packages, or set up React, Bun,

tests, a preview server or a browser build for it.

1. Write one index.html with inline CSS and script. Include

<meta name="viewport" content="width=device-width, initial-scale=1">, follow the readable defaults below and let content reflow into one column on a phone. Use system fonts, text, inline SVG or small data-URL images such as icons and logos, so nothing has to load beside the file (draw a chart as inline SVG). Photos and video go outside the HTML (see "Keep the page small").

1. To keep entries, load the host client with this exact tag before your own

script, and use Site Data:

``html <script src="/__opengeni/site-tools/client.js"></script> <script> const entries = createOpenGeniSiteClient().data.collection("entries"); // await entries.insert({ systolic: 128, diastolic: 82, date: "2026-10-26" }); // const { records, nextCursor } = await entries.list({ sort: [{ field: "$createdAt", direction: "desc" }], limit: 200 }); // pass { cursor: nextCursor } to load older entries (a "Show more" button). // each record is { id, data, ... }; render record.data with textContent. </script> ``

Catch errors and show one friendly line instead of crashing; Site Data only works on the saved Site, so a local copy shows that line.

1. At most one quick look at phone width (about 390 px), and only when the

layout is unusual. Skip desktop sweeps, 200% text passes, screenshots at several widths, preview servers and test harnesses; those are for apps.

1. Save it as in "Publish one immutable version", with requestedTools: []

and no source upload: its HTML is the editable source. If it keeps entries, then call opengeni__site_data_define_collection with the Site id, the same collection name and accessMode: per_viewer for each person's own entries (add privateRecords: true for health or other personal data), append_only for a form that collects answers. Skip jsonSchema; check values in the page.

1. Reply with the link as soon as it is saved, in the person's words: what

it does and how to use it. The link opens for workspace members only. When the person wants others to open it (family, customers, "on their phones"), offer to put it on the web and ask before making it public, then follow "Publish to the web".

Make new Sites readable by default

Choose a clear type scale before building. For new Sites without an explicit type scale, start main reading text at 16–18px, controls and table content at 14–16px, and reserve smaller text for genuinely secondary metadata, not descriptions, navigation, labels needed to use a control, or key results. Use comfortable line heights (about 1.5–1.7 for prose) and reading widths of roughly 60–75 characters. Check the chosen font at its rendered size: a large headline does not make small body copy readable.

Use rem/em for text, keep the browser's root font size, and allow browser zoom and user text scaling. Do not shrink primary copy on mobile to fit more columns; reflow the layout, wrap content, or scroll a wide table instead. Keep form text readable and let controls grow with their labels.

These are authoring defaults, not a mandatory theme or runtime CSS override. Honor a user's deliberate design, retain an existing app's type system, and leave embedded components such as SessionConversation on their own styles. Do not inject a blanket font-size rule into existing Sites or use !important to force this scale onto a component library. If frontend-design is available, use it for visual direction alongside these readability defaults.

For a new page, this optional starting point applies only to elements you mark with these classes; adapt it to the design rather than importing a global reset. The sizes below assume the usual 16px browser default and scale with it.

.site-copy { font-size: 1.0625rem; line-height: 1.6; max-width: 70ch; }
.site-control { font: inherit; font-size: 1rem; line-height: 1.5; }
.site-table { font-size: 0.9375rem; line-height: 1.5; }
.site-meta { font-size: 0.8125rem; line-height: 1.5; }

A single-file Site that follows these defaults needs no more checking than its one optional phone-width look. For an app, before publishing, inspect actual paragraphs, labels, inputs, buttons, table cells and empty/error states at desktop and narrow mobile widths, then with text enlarged to 200%. Check computed sizes and look for clipped or overlapping text; fix layout pressure rather than making the content smaller. A fixture can demonstrate a type scale, but does not prove every generated Site follows it.

Edit an existing Site

• Call opengeni__artifacts_get_source first and restore the download URL in

downloads.source.url using curl or Bun, then restore the source bundle ({entrypoint, files: [{path, content}]}). If source is null, download downloads.html.url and edit that HTML instead. URLs expire; call the tool again to refresh them. The returned current version id is the optimistic-concurrency fence for the next publish.

• Treat retained source as the editable truth and the compiled HTML as the

runtime projection. Never edit only the generated HTML when source exists.

• Keep the path the Site already has: a single-file Site stays one file unless

the requested change makes it an app.

Keep secrets, Opengeni access keys, OAuth tokens, workspace ids, API base URLs, and signed URLs out of every Site's source and HTML.

Publish one immutable version

1. Call opengeni__artifacts_prepare_upload (no hashes or sizes required).
2. Upload the HTML (index.html for a single-file Site, dist/index.html for a

built app) to html.putUrl with HTTP PUT using curl or Bun. Send the returned requiredHeaders exactly.

1. If editable source exists, save JSON {entrypoint, files: [{path, content}]}

locally and PUT it to source.putUrl. Paths must be relative and traversal-free. Exclude node_modules, caches, build output, and credentials. Source is optional: skip this upload for an HTML-only Site.

1. Call opengeni__artifacts_create with uploadId, title, description,

idempotency key, and exact requestedTools. For an edit, call opengeni__artifacts_publish with the artifact id and expectedCurrentVersionId from artifacts_get_source.

Do not put generated HTML or source into model tool arguments. Upload file bytes directly from the sandbox. No special SDK upload helper is required. Finish both intended uploads before publishing. For changed content, prepare a new upload; published versions do not change if an old PUT URL is reused.

If an idempotent create or publish reports an uncertain outcome, inspect the artifact list/source and rerun that same persistent script with the exact same idempotency key. Never mint a replacement key for the same intended version.

After a successful create or publish, use the returned artifact.workspaceId and artifact.id to give the user a standard Markdown link to the durable Site:

[Open <Site title>](/workspaces/<workspaceId>/artifacts/<artifactId>)

Include that link in the completion reply instead of making the user search for the Site. Never present a sandbox URL, API content URL, or object-storage URL as the finished destination. Mention source files, tests or tool names only to someone who asked about them.

Archive with opengeni__artifacts_archive and restore with opengeni__artifacts_restore. Archiving unpublishes the Site but preserves its immutable versions and retained source. There is no hard-delete workflow.

Keep the page small

Visitors download all of the HTML before anything shows, and the Sites gateway can't serve a page over 256 MB. Keep it under 5 MB: resize and compress images to their shown size (WebP or JPEG), and link video or large images from where they are hosted. Site files (references/site-data.md) also hold media: shared files open for every visitor of the Site, signed-out guests of a public Site included. A create or publish result with warnings means the page is too heavy: shrink or move the media and publish again.

Publish to the web

When the user wants a Site outside the console (a public page, a client portal, a form for people outside the workspace), publish it to its own address under the deployment's Sites domain, such as team-crm-4k9x.opengeni.site. Ask before making a Site public; members-only is the safe default. Use opengeni__site_hostname_check for the address, then opengeni__site_publication_update (read with opengeni__site_publication_get), or point the user to Publish on the Site page. Publishing is off when the deployment has no Sites domain (sites_publishing_disabled), and an Only me Site must be shared with the workspace first.

• Access: members, invited (members plus listed emails, who sign in first) or public (anyone; visitors who don't sign in are guests).
• The same Site HTML and Site Data work there; no rebuild is needed.

After publishing or changing access, read the publication's warnings (opengeni__site_publication_get or _update): each names what won't work for whom and what to change. Fix them, or tell the user about warnings you leave, and suggest View as visitor on the Publish page to check the Site as its audience sees it. A public_sign_in_required warning means this deployment asks every visitor to sign in to Opengeni, even on public Sites: that is its setting, not a broken link, so tell the person their visitors sign in first instead of reporting sharing as broken.

A published Site is a public web page. Never put secrets, tokens or private data in its HTML. An invited or public Site that keeps entries in Site Data, or an app that uses Site SQL, workspace tools or an embedded agent, also needs references/publish-to-web.md.

Apps

Apps follow these two rules and read the references they need.

Sites have no server; AI comes from the host