# Local Documentation Server

Anteroom bundles a local documentation server so you can browse the full docs site on your own machine without depending on an external hosting service.

## Prerequisites

None — MkDocs and the Material theme ship with the base `anteroom` install. Just run the command below.

## Serving Docs Locally

Start the docs server:

```bash
aroom docs
```

This serves the documentation at `http://127.0.0.1:8400`. Open that URL in your browser to browse the full site with the same navigation and content as the hosted version.

### Custom Port

Override the default port:

```bash
aroom docs --port 8088
```

### Custom Host

Bind to a different address (for example, to expose on a local network):

```bash
aroom docs --host 0.0.0.0
```

## Run as a background server

If you want to keep working in the same terminal, run the docs site in the background with `aroom docs start`. The subcommands mirror `aroom start` / `stop` / `status` for the web UI but operate on the docs site. They write a PID file at `~/.anteroom/anteroom-docs-{port}.pid` and log output to `~/.anteroom/anteroom-docs.log`.

```bash
aroom docs start               # background, port 8400
aroom docs status              # running / responding / pid / log path
aroom docs stop                # terminate
aroom docs start --port 9400   # custom port; lifecycle commands auto-discover
```

Notes:

- `aroom docs stop` and `aroom docs status` auto-discover the running port when `--port` is omitted. If more than one docs server is running in the same data directory, they will ask you to pass `--port` to disambiguate.
- The host recorded in the PID file is re-used automatically, so `stop` / `status` do not accept `--host`.
- `aroom docs` (no subcommand) still runs MkDocs in the foreground and blocks the terminal — the same zero-config default as before.
- The background and foreground paths share the same underlying MkDocs invocation; there is no separate proxy or reverse server.

## Validating the Docs Build

Run a strict build to catch broken links, missing pages, and config errors:

```bash
aroom docs --build
```

This runs `mkdocs build --strict` under the hood and exits with a non-zero code on any warning or error. Useful for:

- **CI pipelines**: add `aroom docs --build` as a build step
- **Pre-push checks**: run locally before pushing docs changes
- **Contribution workflow**: verify your docs edits build cleanly

## How It Works

The `aroom docs` command is a thin wrapper around MkDocs. It:

1. Verifies that MkDocs is importable (it ships with the base install)
2. Locates the `mkdocs.yml` config file (from the repo root or the bundled package data)
3. Runs `mkdocs serve` (or `mkdocs build --strict` with `--build`)

The foreground form (`aroom docs`) runs MkDocs directly and does not
require the rest of Anteroom's configuration — no database, no API keys.

The background lifecycle forms (`aroom docs start`, `aroom docs stop`,
`aroom docs status`) read `config.app.data_dir` to locate their PID
and log files (`anteroom-docs-{port}.pid`, `anteroom-docs.log`) under
the same directory the web UI uses. They still do not touch the
database or need API keys, but they do load the normal Anteroom config
chain to resolve `data_dir` and the default docs port.

## Troubleshooting

**"MkDocs is not installed"**

MkDocs ships with the base `anteroom` install. If you see this error, reinstall Anteroom (`pip install --upgrade anteroom`) or run `pip install mkdocs-material` to reinstate it.

**"Cannot find mkdocs.yml"**

This can happen if you installed Anteroom from a wheel that does not include bundled docs. Try installing in development mode (`pip install -e .`) from a git clone.
