# Atlas Books

A book is a documentation library served through Atlas. It lives in a directory under `books/` and is served at `/book/{slug}/`.

---

## Two Types

**Standalone book** -- static HTML files. No template, no depot. Atlas serves them directly. The book and its content are the same thing.

**Templated book** -- a template defines the structure, a depot (called a larder) provides the data. Atlas renders a landing page with links to the template definition and the data browser.

## Directory Structure

### Standalone Book

```
books/
└── feature-flow/
    ├── index-en.html       # English version
    ├── index-es.html       # Spanish version
    └── CLAUDE.md           # Dev notes
```

Routes:
- `/book/feature-flow/` -- language picker
- `/book/feature-flow/en` -- English
- `/book/feature-flow/es` -- Spanish

A standalone book is just HTML. Put it in the directory, register it in `books.json`, add a route in `main.py`.

### Templated Book

```
books/
└── feature-form-samples/
    ├── template/                   # Template definition
    │   └── plantilla-flujo.md
    ├── feature-form/               # Larder (data)
    │   ├── .larder                 # Marker file
    │   ├── pet-owner/
    │   ├── veterinarian/
    │   └── backoffice/
    ├── index.html                  # Larder browser
    └── detail.html                 # Detail renderer
```

Routes:
- `/book/feature-form-samples/` -- landing page (links to template + larder)
- `/book/feature-form-samples/template/` -- template definition
- `/book/feature-form-samples/larder/` -- data browser
- `/book/feature-form-samples/larder/{user_type}/{file}` -- specific entry

The `.larder` marker identifies which subdirectory holds the data.

## The Feature Flow Example

Feature Flow is the standalone reference. It documents the BDD standardization pipeline -- how features go from idea to Gherkin to test. Two languages, no template, pure HTML.

## Registration

Books are registered in `books.json`:

```json
{
  "items": [
    {
      "name": "feature-flow",
      "slug": "feature-flow",
      "title": "Feature Flow Pipeline",
      "status": "ready",
      "system": "atlas"
    }
  ]
}
```

## Adding a Room-Specific Book

1. Create the book directory in `cfg/<room>/atlas/books/{slug}/`
2. Add the HTML files
3. Register it in the room's `books.json` (in `cfg/<room>/data/`)
4. Add routes in main.py if it needs custom handling
5. Build: `python build.py --cfg <room>`

The build merges room books into the output alongside core books. Room books can also override core books by using the same slug.