> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Find a template

# Find a template (and the rules it carries)

**When to use:** Before filling or rebranding a template ([`fill-template.md`](./fill-template.md), [`rebrand-template.md`](./rebrand-template.md)), or whenever the user says "template", "theme", or "use one of our decks as a starting point" and you don't already have a `canvas_id` in hand.

## Templates vs themes

| `template_type` | What it is                                                                                                                                                           | Format          |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `template`      | A finished design meant to be copied and refilled with new content — a deck, a social post, a one-pager, anything.                                                   | Any format      |
| `theme`         | A slides-only canvas supplying reusable page layouts, attached to a brand kit's `default_theme_canvas_id` and auto-applied to fresh slide decks made under that kit. | Always `slides` |

If a user says "template" loosely and means a deck or a post, they mean `template` — `theme` is the narrower, slides-only, brand-kit-attached concept. Don't reach for it unless the user is specifically talking about layouts a brand kit applies automatically.

## Finding one

Two lanes, same filters — pick by who the results are for:

```python theme={null}
# The user should see and pick — renders the visual gallery
list_my_canvases(query="pitch deck", template_type="template", limit=20)

# You just need a template_canvas_id for the next call — JSON only, no gallery
search_canvases(query="pitch deck", template_type="template", limit=10)
```

* Drop `query` from `list_my_canvases` and `template_type` alone browses the team's curated templates/themes **by recency** — useful when the user just wants to see what's available, with no search term yet.
* An empty result means the team curated none. **Say so** — don't presciently offer an ordinary canvas as if it were a template.
* Any readable canvas works as `start_design_task`'s `template_canvas_id` — the `template_type` filter only narrows discovery down to the ones the team deliberately curated for this purpose.

## The built-in instructions — aware, don't restate

The design agent **already receives** a template's author-written instructions automatically once you pass it as `template_canvas_id` — they travel onto the remix copy and are hydrated into the agent's turn prompt server-side. This gives three rules for the `prompt` you write:

1. **Never copy a template's instructions into `prompt`.** They travel automatically. A paraphrase ("never modify the title slide" → "keep it roughly as-is") creates a weaker, drifting duplicate in the more heavily-weighted user turn.
2. **Never write a prompt that asks for something the template forbids.** Read the row's `guidance` (below) before drafting.
3. **On a genuine conflict, ask the user — don't pick a side.** Locked nodes/pages are a hard constraint; everything else is author-intent vs user-request with **no defined winner at runtime**. Do not invent or publish a precedence rule the runtime doesn't implement.

Worked example — the user asks for something the template's guidance forbids:

> This template says "Never modify the title slide," but you asked for a new hero there. Want me to leave it alone, or start from a different template?

The one exception: if the user explicitly overrides after being asked, state the override plainly in the prompt (e.g. "the user asked to replace the title slide despite the template's note — do it"). That's the only case the prompt should mention a template rule at all.

## Reading `guidance` on a search/list row

A canvas with author-pinned instructions carries a `guidance` object:

```json theme={null}
{"agent_instructions": "…", "agent_instructions_truncated": true, "pinned_note_count": 4}
```

`pinned_note_count > 0` means there's additional per-element guidance (pinned notes on specific nodes/pages) you can't see from this row — you don't need to fetch it yourself, the agent will read and follow it once it runs against the copy. Just know it's there: don't assume a template with `pinned_note_count: 0` is unconstrained if `agent_instructions` is also present, and don't assume a template is safe to freely rewrite just because `guidance` is absent from the row (a canvas with no authored instructions has no `guidance` key at all — that's the "no constraints" case, not an omission).

## See also

* [`fill-template.md`](./fill-template.md) — content-only remix, same brand
* [`rebrand-template.md`](./rebrand-template.md) — full rebrand on copy, different brand kit
* [`../references/gotchas.md#templates-and-themes`](../references/gotchas.md#templates-and-themes) — the compressed reference version of this page