# Templates

> A template is a reusable prompt blueprint — an expert-written system prompt (structure, checklists, hard requirements) that combines with your prompt at run time. The Console's Templates page (Building blocks → Templates) is a block composer: build templates out of free-text blocks and referenced templates, version them, and optionally publish them publicly. As of September 25, 2026, OpenEng AI isn't live yet.

A **template** is a reusable prompt blueprint — an expert-written system
prompt (structure, checklists, hard requirements) that combines with *your*
prompt at run time. The Console's **Templates** page (Building blocks → Templates) is a
**block composer**: build templates out of free-text blocks and referenced
templates, version them, and optionally publish them publicly.

> [!WARNING] Status on September 25, 2026: OpenEng AI isn't live yet
> The Console and Web Console interfaces load, but the OpenEng AI API routes and the Broker aren't
> deployed. Nothing can be saved or published, and no AI engine can register or connect. Pro,
> Enterprise and pay-as-you-go launch in Q4 2026 and can't be purchased yet. This page describes
> OpenEng AI as it works once those services are live ([status](ai.md)).

*Figure: Building blocks → Templates — the block composer: the canvas, the library opened from the canvas, and the explicit Save and Publish version… in the header.*

## What it is, and when to use it

Use a template when a deliverable is big and repeatable — "production-grade
e-commerce platform", "system-design document" — and you want every run to
inherit the same structure and rules, with the template's blueprint combined
into your own prompt at run time.

Guidelines that make templates effective:

- Write the blueprint as **instructions to an expert**, not as an essay — sections, ordered steps,
  explicit deliverables.
- Put hard requirements ("always include tests", "never store raw secrets") in the template so
  every run inherits them.
- **Publish a new version on every content change.** Versions are per template, so you can evolve
  one template without touching the rest.

## Templates vs agents

They're complementary:

| Aspect | Agent | Template |
| --- | --- | --- |
| What it is | A persistent persona: a system prompt, optionally with its own model | A blueprint for one big, structured deliverable |
| How you apply it | `/agent <name>` in the Web Console | `/template <id>` in the Web Console, a `template=<id>` directive anywhere in a prompt, or the config's default template |
| What the engine does | Replaces the base system prompt with the agent's | Adds the blueprint to the turn's instructions as the authoritative method |

A common combo: an agent for your day-to-day persona, plus templates for the
occasional heavyweight deliverable. For a smaller, focused method (one technique rather than a whole
deliverable), use a [skill](skills.md). See [Agents](agents.md) for personas.

## The list: Mine, Catalog, Public

The list page has three scope tabs:

| Scope | What's in it | Can you edit? |
|---|---|---|
| **Mine** | Your own templates (`tpl_usr_…` ids) | Yes |
| **Catalog** | The shipped catalog (`tpl_def_…`) — e.g. `ecommerce`, `saas-platform`, `system-design` | Read-only |
| **Public** | Templates other accounts published publicly | Read-only |

As of September 25, 2026, the catalog at [templates.openeng.app](https://templates.openeng.app)
holds **754 templates** in 28 categories, from app and API builds and proofs of concept to deep
research, documentation, dashboards, debugging, security, and cloud investigations driven by cells.
Each one is a Markdown blueprint published at `https://templates.openeng.app/<slug>.md`.

Catalog and Public templates open the composer **read-only** with a
**Combine into new** action — you never edit someone else's template, you
build on it. The list also supports **multi-select across all three scopes**
feeding *Combine into new template*: your selection order becomes the block
order of a brand-new draft. Rows in your own scope carry trailing **Edit** /
**Delete** icon actions (delete behind a confirmation); Catalog and Public
rows don't — they aren't yours to delete. Copies the config builder made to pin a template to a
config sit apart, in a collapsed **Pinned to configs** group.

## The composer

The composer is one full-width screen: a header (name · visibility · version chip ·
save-state chip · *Publish version…* · **Save** · ⓘ), a validation strip when there are problems
(errors block Save and Publish; warnings only inform), the **block canvas**, and three collapsible
sections below it: **What the
engine will receive**, **Attachments** and **Versions**. The library opens from the canvas when you
insert a template.

*Figure: The template composer — text and reference blocks stack on the canvas; reference blocks freeze a snapshot and flag upstream drift with a one-click Re-sync; Insert from library lands a template at the chosen position.*

### Blocks

A template is an ordered stack of blocks of two kinds:

- **Text block** — free-form prompt text in a monospace editor. Use these for
  interstitial instructions between referenced templates.
- **Reference block** — another template inserted from the library, *showing
  its content*. The referenced body is **snapshotted at insertion** and
  frozen — your composition can never change underneath you.

### Inserting and arranging

- **Insert gaps** between and around blocks offer *+ Text* (a free-text block
  right there) and *+ Template*, which opens **Insert from library**: search the Catalog, Public and
  your own templates, and **Insert** lands the block at that position.
- **Drag** any library item onto the canvas (one drag context spans the library
  and canvas), or use the item's **Insert** button — the keyboard path.
- Reorder by dragging the handle, or via each block's menu (*Move up / Move
  down / Move to… / Remove*) — every structural edit has a no-drag
  equivalent.

### Snapshots, drift, and Re-sync

Because reference blocks freeze a snapshot, the composer tells you when the
source moves on:

- **Upstream updated** — the source template changed since you inserted it; a
  one-click **Re-sync** pulls the current body into your block.
- **Source removed — snapshot retained** — the source template was deleted;
  your snapshot stays in the block (that's the immutability win).

### Attachments

Files delivered with the template into the engine's context, each up to 10 MB. Only their metadata
is stored with the template and frozen into a published version.

### What the engine receives

The composed document **flattens** to plain prompt text: block bodies joined
in order with one blank line, no markers. The **What the engine will receive** section shows exactly
that text. It's what the engine fetches — byte-clean prompt text:

- your templates (`tpl_usr_…`) through `GET /v1/templates/{id}` or `{id}@{version}` on
  `api.openeng.app`, with your credential;
- catalog templates (`tpl_def_<slug>`) from the public CDN, as
  `https://templates.openeng.app/<slug>.md` (always the latest).

Two hard size rules guard against silent failures:

- An **empty** composition is blocked — the engine refuses empty templates.
- Over **256 KB** is blocked (the engine's hard cap — it would silently skip the
  template); a warning appears from 200 KB.

## Using templates

A template reaches a turn in three ways:

- **The config's default template.** In the config's **Templates** step, pick the templates the
  config ships and choose the default; the engine adds the default to every prompt served on that
  config.
- **One message in the Web Console.** Type `/template <id>` before the message at
  [app.openeng.app](https://app.openeng.app) (the composer suggests templates from the running
  config), or tick it in the component selector beside the composer. It combines with `/agent` and
  `/skill`.
- **A directive in the prompt.** `template=<id>` anywhere in a prompt applies that template to the
  turn and is removed from the text the model sees. A directive wins over the config's default.

A running engine keeps each template it fetched for up to an hour before fetching it again. If a
template can't be fetched, the turn goes ahead without it and shows a notice.

## Saving, versions and publishing

- **Save is explicit.** Edits never reach the server on their own: the
  header's **Save** button writes the live document (disabled with the reason
  while the composition is empty/oversize or unchanged, toast on result). As
  you edit, the draft mirrors to the browser's local storage — reopening the
  composer offers **"Restore unsaved draft?"** — and an *Unsaved changes*
  chip shows until you Save. Saving never stamps a version.
- **Publish version…** is the deliberate step: it suggests the next semver
  (patch bump of your highest), and freezes an immutable **`<id>@<version>`**
  pin server-side. Pinned fetches never change; unpinned fetches follow your
  latest. Publishing writes the live document too, so a publish also clears
  the unsaved state. The **Versions** section lists every published version with its copyable
  pinned id.

### Visibility: Private vs Public

Every template has a **Private / Public** switch in the header — on **every
plan**, no gate. Public templates appear in other accounts' *Public* tab
(read-only to them, combinable into their own work). Private is the default.

## Plan & tier notes

Templates carry **no plan gate anywhere** — authoring, versioning, public
publishing, and selecting them into configs are open on every tier. Running them needs the
`openeng` engine, which starts only on an active Pro plan ([Plans & billing](account.md)).

## Troubleshooting

**The engine says the template is empty / skips it.** The composer blocks
empty and oversize saves, so check which version the machine fetched — a pin
(`<id>@<version>`) keeps serving the frozen version even after you fix the
draft; publish a new version and update the pin.

**A reference block shows "upstream updated" right after publishing.** That's
the design: you published the *snapshot* taken at insert time, and the source
changed afterwards. Re-sync if you want the new body, then publish again.

**I can't edit a template I can see.** Only your own (`tpl_usr_…`) templates
are editable. Catalog (`tpl_def_…`) and foreign public templates open
read-only — use **Combine into new** to build your own on top.

**A template doesn't apply.** Confirm your account has resolved (the
template is fetched per-id at use time), and that the id is right — the
list page has a copy-id affordance on every row.

**I published a fix, but a running engine still uses the old text.** A running engine keeps a
fetched template for up to an hour. Wait, or restart the engine.