Step 2 of 6

Define

Design the shape of your world before writing a single room.

Create the config

Before creating any content, you'll tell txtscape what kind of knowledge this project holds. Create .txtscape/config.json in your project:

.txtscape/config.json

{
  "concerns": [
    {
      "folderName": "rooms",
      "label": "Rooms",
      "description": "Locations in the labyrinth with descriptions, exits, and items.",
      "template": "# {name}\n\n## Description\n\n## Exits\n\n## Notable Features"
    }
  ]
}

This tells the agent: "this project has a rooms/ folder, and every room should follow this template." You haven't created any rooms yet — you've defined what a room looks like.

💡
{name} is a hint, not a substitution. The server passes the template text directly to your agent as part of its instructions. The agent reads {name} and understands it means "put the title here." Nothing is auto-filled by the server — it's guidance for the AI.

Create your first room

Now ask the agent to create a room. Don't dictate the content — just name it:

Tell your agent
"Create a room called The Entrance Hall. It's the threshold of the Minotaur's labyrinth on Crete — sunlight behind, darkness ahead. There's a bronze sword on the wall."

Watch what happens. The agent calls put_page and creates rooms/entrance-hall.txt — and the content follows your template:

.txtscape/pages/rooms/entrance-hall.txt

# The Entrance Hall

## Description
A wide stone archway marks the threshold between the
sunlit world and the labyrinth below. Dust motes drift
in the last shaft of daylight. Beyond the arch, rough
walls close in and the air grows cold.

## Exits
- North: Twisting Corridors

## Notable Features
- A bronze sword hangs on an iron bracket by the entrance

The exact words will differ — your agent writes its own prose. But the structure matches: # Name, ## Description, ## Exits, ## Notable Features. That came from your template.

What just happened

You defined a concern with a template. The agent used it automatically. You didn't paste the template into the chat or tell the agent to follow a format — it read the config and shaped its output to match.

This is the core pattern: you design the structure, the agent fills it in. The template is your lever. Change the template, and every room the agent creates will follow the new shape.

💡
Structure before content. In real projects, this is how you get consistency. Define a template for architecture decisions, runbooks, or API designs — and every page the agent creates follows the same shape. No copy-paste, no reminding.
✅
Pages are just files. You can open .txtscape/pages/rooms/entrance-hall.txt in your editor — it's a plain text file. Edit it anytime. Pages belong to you, not to the agent.
💡
About _meta.hash Put_page returns a hash alongside its confirmation. Your agent uses this automatically to detect conflicting edits — if two agents write the same page concurrently, the second write is rejected. You don't manage hashes manually; the agent handles it behind the scenes.

Commit your progress

git add .txtscape
git commit -m "define rooms concern and create Entrance Hall"
← Install Populate →