Documentation for AI assistants

How Superprez and Superengine behave in this product: GitHub, hosted vs personal accounts, drop-code and zip updates, collaboration. Copy-ready AI prompts and Superengine zip checklists live on a dedicated page (linked in the sidebar).

Superprez vs Superengine

Superprez is the authenticated web dashboard: catalogs, titles, sharing, collaborator invites, drop-code onboarding, zip download/upload helpers, quota, Settings (personal GitHub token, hosted GitHub PAT), and the live URL surfaced as “Open live.”
Superengine backs deployments: builds runnable web apps from the linked repository, exposes deployment status (building / live / sleeping / failed), runs check for update after new commits reach the tracked branch (often main).

Practical rule: Git history and runnable code belong in the repo; the human-readable deck name in the Superprez UI is controlled by what the presenter typed there, not necessarily by <title> in the shipped HTML. Keep SEO-friendly titles inside the app, but assume the sidebar title is authoritative for the presenter.

Supported workflows

New presentation (AI in Superprez) — in-app wizard; Superprez provisions a repo and orchestrates AI messages.
Add GitHub repo — connect an existing repository (requires a Personal Access Token in Settings; fine-grained or classic both work). Superengine clones and deploys what is already on the default branch.
Drop code (.zip) — explode the archive into either a private GitHub repo (when the user's personal PAT is connected) or a per-deck folder on the Superprez server (default for users without GitHub). The folder is git-initialized so Superengine can clone it via file://. Ongoing edits:presenters can upload a revised zip from the presentation page; that records a fresh snapshot commit and triggers check-for-update + update the same way as collaborator zip uploads (see below).
Work outside Superprez — use Cursor / ChatGPT / Claude to author the repo locally, commit and push to GitHub, then connect that repo from Add presentation or rely on webhooks if already linked.

Collaboration & GitHub

Personal GitHub connected — the presenter pastes a Personal Access Token in Settings (either fine-grained github_pat_… or classic ghp_…; both are accepted) and Superprez stores it encrypted. With it, the back can create repos under the user's account, fetch zipballs, apply zip uploads as commits, register push webhooks, and invite GitHub collaborators by email when the email can be resolved to a GitHub user (via PUT /repos/<o>/<r>/collaborators/<login>). If the email isn't discoverable on GitHub, the share still happens inside Superprez but no GitHub invite is issued.

No personal GitHub (server-hosted decks) — by default, drop-code without a personal PAT saves the unzipped source in a per-deck folder on the Superprez server, initialised as a git repository. Superengine clones that folder via a file:// URI; updates are commits on local main. There is no GitHub repo, no remote push, and no webhook. Collaborator invites in this mode are scoped to Superprez (share-link allowlist + the modification-zip panel) — there is no GitHub collaborator entry to add.

Guests without GitHub tooling — when an owner shares a deck with Allow modification, the collaborator sees Download source (.zip) and Upload modified .zip on the authenticated presentation page. Uploads are imported by rebuilding the git tree from the zip contents and writing a single snapshot commit on the default branch (not a textual diff/patch apply), then Superengine check-for-update + update fires. Same size limits as owners.

Drop code & zip updates

Decks created through Add presentation → Drop code are tagged in the catalog as code_upload. Only those owners (not owners who imported from a connected GitHub repo) see the “Update via zip (drop code)” panel on the presentation page. Uploading rebuilds the source tree from your zip and writes one snapshot commit on main: for personal-GitHub decks this is a GitHub commit pushed via your PAT; for server-hosted decks this is a local commit in the per-deck folder on the Superprez server. Either way, Superprez then runs check-for-update + update on Superengine and restarts the deployment if it was already live. Owners whose deck originated from Connect repo use git push instead — the auto-update webhook covers them.

Keep archives under the configured upload cap (currently 12 MB raw zip before base64).
Strip node_modules, .next, and other heavy folders before zipping.
After upload, wait for status to move through building if Superengine needs a fresh build.

Titles & dashboard metadata

Superprez surfaces the title the user entered in the product (and updates from the catalog) in the dashboard, share dialog, and navigation. The HTML document title or marketing label inside the deck can differ; do not assume they stay synchronized unless the team manually mirrors them. When prompting an AI, instruct it to keep internal SEO titles consistent with the brand, but call out that Superprez will show the outer title supplied by the presenter.

Packaging & build expectations

Match the Superengine port expectations for your workspace: deterministic dependencies, committed lockfiles, explicit install, build, and start scripts, and no machine-specific paths. Browse official port repositories at software.superengine.tech/explore/repos alongside community mirrors: superengine port examples (GitHub search).

Ship all static assets referenced by the app.
Document required environment variables in README for operators.
Prefer static hosting friendly defaults if the port template expects them.

Detailed zip checklist (including picture.png) plus copy-ready AI prompts: AI prompt templates & zip packaging.

Status lifecycle

Building — Superengine is compiling/deploying.
Live — Containers running; iframe preview should load.
Sleeping — Stopped for quota; presenters must hit Run (owners) after waking.
Failed — Build error; inspect Superengine logs and repo health.

After zip upload or collaborator push paths succeed, refresh the page to watch status propagate.