← Back to Superprez

Documentation for AI assistants

How Superprez works end-to-end: dashboard, Git-backed decks (personal vs Superprez-managed hosting), drop-code zip uploads and updates, collaboration. Copy-ready prompts, Pattern 1 vs 2 packaging, and a full first-run compatibility guide live on the prompts page — aligned with Superengine port docs.

Platform overview

  • Superprez is the product presenters use: workspace, catalogs, titles, sharing, collaborator invites, zip download/upload helpers, quota, Settings (personal GitHub PAT where applicable), live URLs, and dashboard status (building / live / sleeping / failed).
  • Behind the same surface, Superprez also builds and runs each deck from its GitHub remote: cloning tracked branches, compiling containers when needed, running check for update after new commits land on the default branch (usually main), and restarting deployments after zip uploads.

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). Superprez clones and deploys what is already on the default branch.
  • Drop code (.zip) — Superprez imports the archive into a private GitHub repository: either under your account when you choose My personal GitHub and have a PAT in Settings, or under Superprez-managed hosting (operator-configured GitHub access) when you pick the default hosted option. Superprez installs from https://github.com/<owner>/<repo>.git. Ongoing edits:presenters can upload a revised zip from the presentation page; that records a fresh snapshot commit on main via GitHub's APIs 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.

Related reading: How to structure interactive narratives, integrations patterns, starter prompt templates.

Collaboration & GitHub

Share invite: view-only vs modification — When the owner adds someone by email: without Allow modification, Superprez records dashboard access only. The collaborator never receives a GitHub repo invite, does not see the zip download/upload panel on the presentation page, and GET/POST /api/presentations/<slug>/bundle returns forbidden for them. With Allow modification on a personal-GitHub deck, Superprez attempts PUT …/collaborators/<login> after the in-app share row exists; if GitHub cannot resolve the email to a user, the flow fails and the in-app share is rolled back. Superprez-managed / drop-code decks skip GitHub collaborator invites; modification happens via Superprez zip APIs only.

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 (when Allow modification is on for an invite) invite GitHub collaborators by resolvable email as above.

No personal GitHub in Settings (Superprez-managed hosting) — If you upload a zip and use Superprez-hosted GitHub (operator-configured access), Superprez creates a private GitHub repository, imports the archive via GitHub's APIs, and installs the deck from an https://github.com/… remote—not a file:// folder on the Superprez server. Further zip uploads land as commits on main on that repo. Push webhooks may be registered with the managed PAT where configured.

Guests — zip workflow — Only collaborators invited with Allow modification see Download source (.zip) and Upload modified .zip. View-only guests never see that panel. 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 Superprez runs check-for-update + update. Same size limits as owners.

Drop code & zip updates

Decks created through Add presentation → Upload (zip / drop-code flow) 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 on GitHub—either via your PAT (personal hosting) or via Superprez-managed repo APIs—then Superprez runs check-for-update + update 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 when webhooks are configured.

  • 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 Superprez 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

Decks are built from Git like real apps: Superprez (via Superengine) expects deterministic installs, explicit build then start, servers listening on 0.0.0.0 with PORT when provided, and a root URL that serves index.html from the tree produced after build — not from a stale committed dist/. Authors choose Pattern 1 (Superengine port: manifest.json, compose.yaml.hbs, public/) or Pattern 2 (Node/framework output dir). Study official examples in Superengine documentation before shipping Pattern 1 layouts.

  • Committed lockfile, root picture.png, .env.example, README with commands and ports.
  • Zip topology: flat project root or exactly one top-level folder — never double-nested projects.
  • Ship all static assets referenced by the app; document env vars for operators.

Full first-run guide for assistants (sections A–G), copy-ready prompt, and Pattern details: Making a presentation compatible with Superprez.

Status lifecycle

  • Building — Superprez is compiling/deploying the deck.
  • Live — Containers running; iframe preview should load.
  • Sleeping — Stopped for quota; presenters must hit Run (owners) after waking.
  • Failed — Build error; inspect deploy logs in your operator tooling and repo health (missing files, bad zip topology).

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