# WriteUserTemplate

Creates or overwrites a Markdown template in the caller's `templates/` folder.

Templates written here are immediately usable by `ReadUserTemplate` (to inspect them) and `RenderUserTemplate` (to substitute `{{var}}` placeholders and apply defaults).

## Input

```ts
{
  name: string,        // slug — '.md' appended if absent
  content: string,     // full file text (optional frontmatter + Markdown body)
  overwrite?: boolean  // default: false — error if file exists
}
```

## File structure

The content is plain Markdown with an optional YAML frontmatter block:

```markdown
---
description: One-line description shown in ListUserAssets
params:
  - name: date
    type: string
  - name: author
    type: string
    default: "Team"
---
# Report — {{date}}

Prepared by: {{author}}

## Highlights

...
```

Frontmatter is not required. Templates without `params:` render as-is (no substitution).

## Frontmatter params spec

Each param entry in `params:` supports:

| field | required | description |
|-------|----------|-------------|
| `name` | yes | placeholder name used as `{{name}}` in the body |
| `type` | yes | `string` \| `number` \| `boolean` |
| `default` | no | value applied when the param is omitted |

Required params (no default) must be supplied by the caller of `RenderUserTemplate`. Missing required params produce an error at render time.

## Size limit

128 KB (UTF-8 encoded). Exceeding the limit returns `isError: true`.

## Overwrite semantics

By default (`overwrite: false`) writing to an existing file is an error.
Pass `overwrite: true` to replace the file atomically.

## When to use

- You noticed a recurring structure (email skeleton, weekly report, issue template) — persist it for reuse.
- The user asks you to create or update a template so they can render it later.
- You want to encode a multi-step prompt skeleton with named slots.

## Examples

### Email template

```js
WriteUserTemplate({
  name: "api-error-email",
  content: `---
description: Customer-facing API error notification email
params:
  - name: incident_id
    type: string
  - name: service
    type: string
  - name: eta
    type: string
    default: "unknown"
---
Dear Customer,

We have detected an issue with **{{service}}** (incident {{incident_id}}).

Our team is actively working on a resolution. Estimated resolution time: **{{eta}}**.

We apologize for the inconvenience.

— The Platform Team
`
})
```

### Report skeleton (no params)

```js
WriteUserTemplate({
  name: "weekly-retro",
  content: `# Weekly Retro

## What went well
-

## What to improve
-

## Action items
- [ ]
`
})
```

## Error cases

| Situation | `isError` | message contains |
|-----------|-----------|-----------------|
| No authenticated user | true | "authenticated" |
| `name` missing / empty | true | `"name"` |
| `name` contains `/`, space, etc. | true | "alphanumeric" |
| Content exceeds 128 KB | true | "bytes" |
| File exists, `overwrite` not set | true | "overwrite" |

## Notes

- `WriteUserTemplate` is a META_TOOL — available in every movement without listing it in `allowed_tools`.
- After writing, use `ReadUserTemplate` to verify the content and `RenderUserTemplate` to test substitution.
- Use `ListUserAssets` to see all templates currently in the folder.