/templates

name: templates
description: Use when publishing a Butterbase app as a public template (visibility + listed + repo snapshot), browsing the template gallery, or cloning a template with environment-variable preflight. Templates are public apps with a pushed repo snapshot that other users can fork into their own region.

Butterbase Templates

A "template" is a Butterbase app marked `visibility: 'public'` and `listed: true`, **with a repo snapshot uploaded via `butterbase repo push`**. The clone pipeline replays the source app's schema, RLS, functions, config, and frontend artifact into a new app in the cloner's region; the pushed repo gives the cloner the actual source tree to keep developing.

How the repo snapshot flows (`repo push` / `repo pull` / `repo status`)

The repo snapshot is the **source-code half** of a template; the clone job replays schema/RLS/functions/config separately. Both halves are pinned via `apps.repo_latest_snapshot`.

• **`butterbase repo init <app_id>`** — Bind the current directory to an app. Writes `.butterbase/config.json` and seeds `.butterbaseignore`. Run once per project. `butterbase clone` does this for you on the cloner side.
• **`butterbase repo push -m "<msg>"`** — Publisher uploads. Walks the project tree (respecting `.butterbaseignore` + `.gitignore`), hashes files (SHA256), uploads any new blobs via presigned URLs, commits a new immutable snapshot, updates the local pin. Content-addressed — re-pushing an unchanged tree is a no-op upload. **This is the only way the source tree gets onto the snapshot.** Clone replay does not synthesise it.
• **`butterbase repo pull [--force]`** — Cloner / collaborator downloads. Fetches the remote latest manifest, diffs against the locally pinned snapshot, downloads changed/new files, deletes files that are gone upstream, and bumps the local pin. Refuses if a file was deleted upstream but modified locally — `--force` overrides. `butterbase clone` invokes this **automatically** after the clone job completes, so cloners get a working tree without thinking about it.
• **`butterbase repo status`** — Inspector. Shows files modified vs pinned, untracked locally, and deleted locally. Use before `push` to confirm what's about to be uploaded; use after `pull` to confirm a clean tree.
• **`butterbase repo log`** — List all snapshots for the bound app.
• **`butterbase repo wipe`** — Destructive; clear all snapshots. Requires app-id confirmation.

**Reading a template's source code:** clone it into a scratch directory — `butterbase clone <source_app_id> /tmp/peek` — and read the resulting tree. There is no separate "browse template source" CLI; snapshots are only materialised by `repo pull`, which requires the caller to be bound to the app.

**Updating a clone with newer template versions:** clones don't auto-follow the source — each clone owns its own app and its own snapshot history. `butterbase repo pull` in the clone fetches the cloner's *own* latest, not the upstream publisher's. To track upstream changes, the cloner has to clone again into a sibling directory and merge with git, or the publisher has to push to a snapshot the clone can read (uncommon).

What clone replay DOES and DOES NOT copy

| Copied on clone | Not copied — cloner must do | |---|---| | Schema (DDL) | App user data (unless explicitly seeded) | | RLS policies | Auth provider OAuth secrets | | Functions (handlers + non-secret env) | Function secrets / API keys (cloner provides via preflight) | | App config | **Agents** (record in `agents` table) — bundle as `agents/*.json` in the repo and re-import after clone | | Frontend artifact (with app-id rewritten) | **Storage objects** (only the bucket config replays) | | Repo snapshot (files) | OAuth integration installs |

This makes the **README in the pushed repo** the most important publishing artifact — it has to explain everything that doesn't replay.

When to use

• Publishing an app you built as a public template.
• Listing or searching templates.
• Cloning a template (or guiding a user through clone with env-var preflight).
• Toggling visibility / listed status on an existing app.

Publishing checklist

Before flipping `visibility: public`, verify all of the following. Each one prevents a class of broken-on-clone bugs.

1. **Repo snapshot exists and is fresh.** Run `butterbase repo push -m "publish v1"` from the project root. Confirm `apps.repo_latest_snapshot` is non-null via `manage_app action: get`. The clone preflight endpoint returns `has_repo: false` if missing, and discovery hides templates without a repo for several sort modes.

2. **README.md at repo root with clone instructions.** No formal "template instructions" field exists — the README in the pushed snapshot **is** the instructions. It MUST cover:

• **One-line pitch** (what does this app do?)
• **Required env vars per function** — the preflight surfaces keys but not what they're for. List each (e.g., `STRIPE_SECRET_KEY — server-side Stripe secret`).
• **Auth setup** — OAuth provider IDs/secrets the cloner must register (OAuth secrets do not replay).
• **Agent re-import** — if the app uses agents, the spec files (`agents/*.json`) ride along in the repo, but the `agents` DB rows don't. Document: `butterbase agents create -f agents/<name>.json`.
• **MCP server registration** — if agents reference MCP servers, document each server's URL/transport/auth-header so the cloner can register them post-clone.
• **Seed data steps** — if the app needs minimum rows (e.g., a default category), provide a seed script or document `manage_schema` / `select_rows` calls.
• **First-run smoke** — concrete command(s) to verify the clone works.

3. **Env-var conventions for auto-mint.** If a function reads `butterbase_api_key`, the clone preflight auto-mints a scoped key for the cloner. Use this convention name exactly so the clone modal can fill it without asking.

4. **No secrets in committed files.** `.butterbaseignore` covers