Archives and Templates

Run a complete local example

Start the backend as in Quick start. Save this as docs-first-room.mjs in the repository root. Each run creates a new tutorial room, adds one character and a numeric variable, creates an actual archive, and saves the retrieved snapshot locally. It does not invoke a model.

import { writeFile } from 'node:fs/promises';
const base = process.env.TEA_API || 'http://127.0.0.1:4318';
async function api(path, body) {
  const response = await fetch(base + path, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { 'Content-Type': 'application/json' },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  return response.json();
}
const { room } = await api('/api/rooms', { name: 'Docs tea room', description: 'A local tutorial room' });
const prefix = `/api/rooms/${encodeURIComponent(room.id)}`;
await api(`${prefix}/characters`, { name: 'Guide', personality: 'Patient and precise', background: 'Hosts the tea room', speaking_style: 'Short sentences', description: 'Tutorial character' });
await api(`${prefix}/variables/set`, { name: 'danger', value: 0 });
const { archive } = await api(`${prefix}/archives`, { title: 'First local archive' });
const snapshot = await api(`${prefix}/archives/${encodeURIComponent(archive.id)}`);
await writeFile('docs-room-archive.json', JSON.stringify(snapshot, null, 2));
console.log(JSON.stringify({ roomId: room.id, archiveId: archive.id, characters: snapshot.room.characters.length, variables: snapshot.room_variables, saved: 'docs-room-archive.json' }, null, 2));

Then run:

node docs-first-room.mjs
node scripts/export-room-template.mjs docs-room-archive.json docs-room-template

Success means docs-room-archive.json contains the created room and variable, and docs-room-template/template.json contains schema_version: 1, one room, a Guide character and danger with value 0. IDs and timestamps vary. A non-2xx API response stops the script; do not use an older output file as evidence that the latest run succeeded.

What is preserved and what is omitted

An archive is a snapshot, including conversation records. The current export script instead preserves a reusable room setup: characters, room/global variables, room bar, world information and behavior rules. It omits message history. Templates can still contain personal information in descriptions, character text or world information, so review those fields before sharing.

The archive records variable_displays, but this version of export-room-template.mjs does not copy that field into the exported template. Keep the archive if you need the original HUD labels/ranges and add those definitions deliberately when authoring a template. Do not assume a round-trip backup.

Use the provided example as a reference

The public source includes examples/templates/agent-room-basic/template.json. It demonstrates characters, a danger variable, display configuration, world information and a condition-based behavior rule. Its condition example activates at danger ≥ 8. The current guide does not claim a one-click template import or export button: the verified export path is the command above. Use the source's template-authoring reference when preparing configuration for a new workspace.