# Atlas Templates

A template is a documentation pattern. It defines the structure that content must follow. Templates turn unstructured knowledge into consistent, browsable documentation.

---

## How Templates Work

A template defines fields, layout, and validation rules. Content that follows the template gets rendered through Atlas with consistent formatting and navigation.

Templates live in `soleprint/atlas/templates/` (core) or inside a book's `template/` subdirectory.

Data templates -- the schema files that define structure -- live in `cfg/<room>/data/template/`.

## The Feature Form Example

The feature form template captures user flows in a structured format:

| Field | Purpose |
|-------|---------|
| User Type | Who performs this flow |
| Entry Point | Where the flow starts |
| User Goal | One-sentence objective |
| Steps | Numbered sequence of actions |
| Expected Result | What success looks like |
| Common Problems | Known failure modes |
| Special Cases | Edge cases and exceptions |
| Related Flows | Connected user flows |
| Technical Notes | Developer-facing details |

This template is served at `/book/feature-form-samples/template/` as a styled HTML form with placeholder fields. Non-technical team members can understand the structure without reading code.

## Depots and Larders

A **depot** is data storage connected to a template. In Atlas, the depot pattern is called a **larder** -- a directory that holds content conforming to a template.

The connection works like this:

```
Template (structure)  +  Larder (data)  =  Templated Book
```

A larder directory contains a `.larder` marker file and organizes content in subdirectories. For feature forms, the larder groups entries by user type:

```
feature-form/
├── .larder
├── pet-owner/
│   ├── register-pet.html
│   └── book-appointment.html
├── veterinarian/
│   └── review-history.html
└── backoffice/
    └── manage-users.html
```

Each file in the larder follows the template's field structure. Atlas renders them through a detail view that reads the content and applies consistent styling.

## The Larder Pattern

Larders enforce a constraint: all content in a larder must match the connected template. This keeps documentation consistent even when multiple people contribute.

The landing page of a templated book links to both:
- The **template** -- so you can see the pattern
- The **larder** -- so you can browse the actual content

This separation means the template can evolve independently from the data. Update the template, and all larder entries get the new rendering.

## Adding a Template

1. Define the template structure (HTML or markdown) in `soleprint/atlas/templates/` or inside a book's `template/` directory
2. Create a larder directory with a `.larder` marker
3. Add content files that follow the template structure
4. Register the book in `books.json` with `template` metadata
5. Add routes in `main.py` for the landing page, template view, and larder browser