AI prompt templates & Superprez zip packaging

Everything below is written so an assistant can understand Superprez hosting from the first run: Git/zip layout, build/start contracts, networking, entry HTML, and the two supported deployment patterns — plus copy-ready prompts.

Making a presentation compatible with Superprez

Superprez hosts your deck as a real web app cloned from GitHub. After you upload a zip (or connect a repo), our builders install dependencies, build if needed, and start a process that serves HTML to your audience. The human title of the presentation is set in the Superprez UI; your app's <title> tag is separate and should still be sensible.

You must satisfy both: Git / zip packaging rules (so the repo imports cleanly) and runtime rules (so Superprez and our hosting stack can reach your app and find an entry page). Failure on (1) is usually wrong folder nesting or missing required files. Failure on (2) is usually nothing listening on the right port, binding only to localhost, serving the wrong folder, or skipping build so no dist/ exists.

Superengine ports & examples

Decks run on Superengine-compatible layouts (manifest + compose templates, or Node build/start flows). Before authoring Pattern 1, skim Superengine documentation— official docs explain port manifests, compose.yaml.hbs, nginx/static patterns, and link to example repositories that match production expectations.

Tip: keep this page open next to your IDE — every numbered subsection maps directly to the one-shot prompt in section G.

A. Canonical zip / repository layout

Topology (most common failure)

Either: package.json at the root of the zip, or exactly one top-level folder that directly contains package.json. Do not double-nest (e.g. MyDeck/MyDeck/package.json).

Exclude from the archive

Do not commit: node_modules, dist, build, .next, coverage, other generated output, __MACOSX, .DS_Store, Thumbs.db, stray zip files.

Required at the project root (after unzip / clone)

File	Purpose
package.json	Must define scripts (see below). Use `engines` if Node version matters.
package-lock.json or pnpm-lock.yaml	Committed lockfile; dependencies must install deterministically on Linux builders.
README.md	Exact commands: install, build, start; which URL and port to open locally; note if the server binds `0.0.0.0`.
picture.png	Small cover image for the catalog (simple graphic is fine).
.env.example	Every environment variable your app or scripts read, with placeholders only (no secrets).
Dockerfile	Include one only if your stack truly needs a container build. If present, it must match what README.md says.

Size

Keep the uncompressed project under ~12 MB before base64 upload limits.

Path characters

Use only safe path segments: [A-Za-z0-9._-] per segment (avoid spaces and exotic Unicode in file and folder names) so zip import sanitization does not strip or break paths.

B. Required package.json scripts

Your root package.json must expose:

"scripts": {
  "build": "...",
  "start": "..."
}

Contract

build — Produces runnable static assets and/or a runnable server build (e.g. dist/, .next, compiled output). It must exit 0 on a clean Linux machine with only repo + lockfile + npm install (or pnpm install) already run.
start — Starts the HTTP server your audience will hit. It must listen on process.env.PORT when PORT is set (recommended). If PORT is not set, document a single default port in README.md and use that consistently in code.

Order

Hosting runs npm install (or pnpm install), then npm run build, then npm run start (exact package manager depends on lockfile — document which one you use in README.md).

Critical: start must serve the tree that exists after build.

If HTML is only generated under dist/, start must serve dist/, and you must never rely on “there is already a dist/ in the zip” — generated folders must not be committed.

C. Networking (preview and live viewing)

Browsers reach your deck through Superprez; our API may fetch your app from the host/port advertised by our hosting/runtime layer.

Your server MUST

Listen on 0.0.0.0 (all interfaces), not only 127.0.0.1, unless our documentation for your specific template says otherwise.
Honor PORT from the environment when provided.
If you document a default port in README.md (e.g. 8080 or 4173), state clearly: “In production, Superprez sets PORT; locally you may use the default.”

D. Entry HTML and URL paths

After clone and build, our tooling must be able to resolve a useful index.html for the root URL of your server.

Practical rules

Prefer either index.html at the repository root and serve it from start, or index.html under dist/ (or build/) after build, and start must serve that folder as the site root.
Do not leave index.html only at repo root while start only serves dist/ unless build copies index.html (and assets) into dist/ every time.
All static assets you reference (JS, CSS, JSON, images) must be part of the repo or produced by build, with paths that work when served from your chosen root (avoid hard-coded absolute URLs to localhost).

E. Two supported patterns (choose one explicitly)

To avoid ambiguity for authors and for AI tools, Superprez documents two compatible patterns.

Pattern 1 — Superengine port (static site under public/, nginx)

Use this when you want maximum compatibility with our default “app port” flow: static files + official compose template.

You MUST include (names exact)

manifest.json — app-spec-version, subject, entitlements, templates listing at least compose.yaml.hbs (and any other required templates).
compose.yaml.hbs — Typically an nginx (or equivalent) service that bind-mounts ./public read-only to the web root inside the container.
public/ — Contains public/index.html and the rest of your static site (CSS, JS, data JSON, etc.).

package.json may still provide build: validate that public/index.html exists (or run a trivial static asset step). start: optional local static server serving public/ for development.

Do not require a committed dist/ for Pattern 1; the live docroot is public/.

Reference: align with official Superengine port examples — see Superengine documentation.

Pattern 2 — Node / framework app (build → output dir, then start)

Use this for Vite, Next, custom Node servers, etc.

You MUST

Implement build so the full site (including index.html at the served root) exists under a known directory (e.g. dist/, build/, .next with the correct start command for that stack).
Implement start so it serves that directory (or runs the framework production server documented in README.md).
Document Node version in engines and in README.md if relevant.

Pattern 2 fails most often when authors assume npm start alone is enough without a prior npm run build on the server, or when start serves the wrong folder.

F. Interactive decks and /data

If you ship JSON or CSV for charts:

Put files under a clear path (public/data/… for Pattern 1, or dist/data/… after build for Pattern 2).
Load them with relative URLs from your app root (e.g. /data/foo.json).
Document in README.md where authoring files live in Git vs where they appear after build.

G. AI / collaborator prompt

Paste into your AI assistant (ChatGPT, Claude, Copilot, Gemini, etc.). Same content ships in the Add presentation modal as “Copy prompt”.

You are building an interactive presentation as a web app for Superprez drop-code (zip upload). The result MUST work for BOTH Superprez (install → build → start / preview) AND Superengine (manifest + compose templates). Context — read before coding: Superprez hosts the deck as a real web app cloned from GitHub or zip. After upload, builders run install, optional build, and a start command that serves HTML. The human title of the presentation is set in the Superprez UI; your app <title> is separate and should still be sensible. Official ports (copy patterns from here): https://software.superengine.tech/superengine/ Local mirrors to diff against: SUPERENGINE-PORT-GUIDE.md, superprez-pitch-competition-deck/, super-interactivity-*-pitch-deck*/ (pulse-wallet-port / nginx static layout). ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ NON-NEGOTIABLE SUPERENGINE FILES (Pattern A — REQUIRED for "works on Superprez + Superengine") ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ You MUST ship ALL of the following at the zip root (same folder as package.json), with valid JSON/YAML and NO Windows CRLF quirks breaking parsers: **manifest.json** - "app-spec-version": "1.2" - subject.name.en + subject.version (bump version on every redeploy) - "templates": EXACTLY these two strings, in this order: ["compose.yaml.hbs", "embedded_ui/overview.html.hbs"] - "actions": [] (empty array) - Static nginx deck entitlements — use this EXACT name order (Superprez pitch-port validator; do not reorder): 1. HostHostnameOrIPAddress → "host" 2. PortUnspecifiedStaticNumber → "port-number" 3. ApplicationDataDirectoryPath → "folder-path" 4. OperatingSystem → "os" 5. IDUserNumber → "uid" 6. IDGroupNumber → "gid" - Do not use a "minimal three" set for these decks unless you also change scripts/validate-build.js and compose to match. **compose.yaml.hbs** - Docker Compose v2 shape, ONE service, image nginx:1.27-alpine (or a pinned patch you document). - Service key: {{app_id}}-<short-lowercase-alphanumeric-suffix> (suffix unique to this deck, no spaces). - ports (critical): one line, unquoted Handlebars — spaces or quotes break deploy: ports: - {{entitlements.port-number}}:80 Wrong: "{{entitlements.port-number}}:80", '…', or {{ entitlements.port-number }} with spaces inside braces. - volumes: mount YOUR real static docroot to /usr/share/nginx/html:ro - If docroot is public/: ./public:/usr/share/nginx/html:ro - If docroot is html/: ./html:/usr/share/nginx/html:ro - Same path string in compose, npm start, and npm run build validation. - restart: always, logging driver local (match official ports). - Do NOT reference dist/, build/ unless that folder is guaranteed to exist before compose runs. **embedded_ui/overview.html.hbs** - Handlebars fragment (Bulma-style markup is fine), MUST include a primary link: href="http://{{entitlements.host}}:{{entitlements.port-number}}" target="_blank" rel="noopener noreferrer" - Short description of the deck + "Open deck" (or equivalent) button text. **embedded_ui/about.html** (required for pitch-port parity) - Short static about blurb; mention unquoted port binding if helpful. **LICENSE.txt** and **NOTICE.txt** at zip root (required for catalog / port rules). **picture.png** at zip root (256×256 recommended catalog icon). If ANY of (manifest template list, entitlement order, compose path, unquoted ports line, overview link, legal files) are wrong, Superprez/Superengine validation or install will FAIL. This is the #1 cause of "zip works locally but not in hosting." ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HOSTED CACHE (why "only some edits" appear after upload) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Superprez/nginx may cache styles.css and app.js while index.html updates. On every content or style change before zipping: - Bump query strings in index.html, e.g. styles.css?v=<deck-slug>-<version> and app.js?v=<deck-slug>-<version>. - Bump manifest.json → subject.version. - Tell the user to hard-refresh or use a private window after redeploy. Without cache-bust bumps, copy in HTML can look new while layout/JS behavior stays old. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ NPM / SUPERPREZ PREVIEW (must match what Superprez runs) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ package.json at zip root (or exactly ONE top-level folder containing package.json — no double nesting). - "scripts": MUST define BOTH "build" AND "start". - "build" SHOULD run a validator (e.g. node scripts/validate-build.js) that checks manifest order, compose unquoted port, docroot exists, LICENSE.txt, NOTICE.txt, picture.png. - Declare "engines": { "node": ">=18" }. - Commit BOTH package.json AND ONE lockfile: package-lock.json (npm) OR pnpm-lock.yaml (pnpm) — never neither. README must match (npm ci vs pnpm install --frozen-lockfile). - start: MUST listen on 0.0.0.0 (NOT 127.0.0.1-only). - start: MUST honor process.env.PORT when set; document default when unset in README (e.g. 8080). - start: MUST serve the SAME tree nginx mounts (public/ or html/). After npm ci && npm run build && npm run start on clean Linux, GET / MUST return a valid HTML document from the served docroot. Do NOT rely on committing dist/, build/, .next/, etc. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ZIP / REPO HYGIENE (GitHub import + size + paths) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - Zip port files at the archive root (manifest.json, compose.yaml.hbs, html/ or public/, …) — not only inside a long hash-named folder unless that folder is the single top-level package root. - Exclude from zip: node_modules, dist, build, .next, coverage, OS junk (__MACOSX, .DS_Store, Thumbs.db), stray nested zips. - Path segments: use only [A-Za-z0-9._-] per segment (GitHub zip import sanitization). - Keep uncompressed project under ~12 MB. - Include at repo root: README.md, picture.png, .env.example (placeholders only). - Dockerfile: ONLY if truly needed; if present, commands MUST match README. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ CHOOSE ONE PRIMARY PATTERN (state in README — default to A unless impossible) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Pattern A — Superengine static port (DEFAULT, most reliable for zip): - public/index.html (+ assets) OR html/index.html (+ assets) — pick one name and use it everywhere. - manifest.json + compose.yaml.hbs mounting ./public or ./html - embedded_ui/overview.html.hbs + about.html - Node-only preview server in start, still serving the same folder nginx uses. Pattern B — Node build → serve output: - ONLY if build output will exist wherever Superengine serves from; otherwise forbidden. - If you use Pattern B, you STILL need the same Superengine files as Pattern A, but compose MUST mount the built directory that actually exists after build in deployment, OR you must supply a multi-stage Dockerfile — and README must describe that truthfully. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DELIVERABLE FORMAT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Before you say you are done: 1) Print a file tree. 2) Run npm run build and report output. 3) For each checklist line below, print PASS or FAIL with one evidence path per item. Checklist: - Zip topology: package.json at zip root OR exactly one top-level folder containing package.json (no MyDeck/MyDeck/package.json). - Zip topology: manifest.json, compose.yaml.hbs, picture.png, LICENSE.txt, NOTICE.txt at package root. - manifest.json: app-spec 1.2; templates includes BOTH compose.yaml.hbs AND embedded_ui/overview.html.hbs; actions: []. - manifest.json: entitlements order host → port-number → folder-path → os → uid → gid (static deck). - embedded_ui/overview.html.hbs exists and uses host + port-number in the Open link. - compose.yaml.hbs: {{app_id}}-… service, nginx:…, ports line unquoted {{entitlements.port-number}}:80, volume path matches real docroot. - package.json: build + start; lockfile committed; README has exact install/build/start, npm vs pnpm, PORT/local URL, 0.0.0.0 binding. - index.html cache-bust query params on styles.css and app.js; subject.version bumped if redeploying. - picture.png, .env.example at project root; no secrets. - No committed generated dirs; paths safe per segment; size ~<12 MB. - Clean Linux: npm ci && npm run build && npm run start → GET / is index.html from served tree. If ANY item is FAIL, fix before claiming done. When repackaging an existing deck after edits: rebuild the zip, bump cache-bust + version, and remind the user to redeploy/replace the port and hard-refresh the browser.

Full prose contract (topology, scripts, networking, patterns): sections A–F above. Superengine port references: superengine.tech/docs.

Additional templates

1) Flagship narrative deck from legacy slides/PDFs

Use when leadership supplies PDFs/PPTX plus brand guidance.

You are a senior front-end engineer. Build a single interactive presentation web app for [COMPANY] targeting [AUDIENCE]. Brand & assets: - Primary colors: [HEX / tokens]. Font stack: [FONTS]. Logo path: /assets/logo.svg (I will place the file). - Recreate narrative flow from: [SOURCES]. Match slide order and metrics; do not invent financials. Product expectations: - Follow this page's "Making compatible with Superprez" guide (sections A–F): topology, build/start contract, PORT + 0.0.0.0, entry HTML, choose Pattern 1 OR Pattern 2 explicitly. - Output package.json scripts: "build" and "start"; accessible responsive 16:9 layout and keyboard navigation between sections. - At least two interactive moments tied to real data under /data (see section F). - Superprez shows the dashboard title separately—still set a sensible <title> aligned with "[DECK_DISPLAY_NAME]". Deliverables: - README + optional /docs/NOTES.md mapping legacy slide numbers to new sections. - Self-verify: clean Linux install → build → start → GET / returns index.html from the served tree.

2) Prepare a repo before linking GitHub in Superprez

Initialize [FRAMEWORK] with deterministic dependencies and satisfy sections A–F on this documentation page. Requirements: - Default branch main; lockfile committed; no absolute paths. - README lists PAT expectations for personal GitHub hosting (fine-grained vs classic scopes per Superprez onboarding docs). - Declare Pattern 1 vs Pattern 2 in README. Provide command cheat sheet + PASS/FAIL checklist before handing off.

3) Edit an exported Superprez zip and ship it back

You have ./deck.zip from Superprez. Tasks: 1) Unzip; detect whether layout is flat vs single-root folder—preserve it exactly. 2) Apply changes: [LIST]. 3) Strip node_modules and build caches before re-zipping. 4) Regenerate picture.png only if branding materially changed. 5) Produce deck-resubmit.zip under ~12MB with the same topology discipline as the incoming archive. Summarize files touched for the presenter changelog. Reminder: uploads become one snapshot commit on main; Superprez rebuilds the git tree from the zip—imports fail if you relocate package.json.

4) Debugging a failed Superprez build

Given this repo tarball and builder stderr [PASTE], enumerate: 1) Missing dependency / script issues vs package.json 2) Node engine mismatches 3) Missing picture.png or Dockerfile promised in README 4) Asset path casing problems 5) Zip topology mistakes (nested duplicate folders) 6) start binding localhost only or wrong directory vs build output (sections C–D) Produce a prioritized patch checklist.

5) Collaborator onboarding without GitHub CLI

Draft email for [NAME]: iterate locally via [COMMANDS], return deck.zip; Superprez applies commits on their behalf. Link to Documentation → Collaboration if helpful.

6) Presenter dashboard title vs in-app headline

Explain how Superprez dashboard title "[SUPERPREZ_TITLE]" relates to in-app H1 "[IN_APP_HEADLINE]"—when they should match vs diverge, plus changelog habits after rebrands.

Product context: Packaging overview, Drop code & zip updates.