From the repo root (`~/dev/localllm`):

```bash
# 1. Stage userdocs + aispace → .build/docs/
uv run python -m py.stage

# 2. Build static site → site/
uv run mkdocs build

# 3. Serve locally (http://127.0.0.1:8000/)
uv run mkdocs serve
```

For a quick preview you can skip `build` and just do `stage` then `serve` — MkDocs builds on the fly while serving.

## .build/docs/   vs  site/

They serve different roles — it’s not really a duplicate of the same thing.

| Path | What it is |
|------|------------|
| `.build/docs/` | **Markdown sources** staged for MkDocs (`docs_dir`) |
| `site/` | **HTML output** after a full build (`site_dir`) |

**`mkdocs serve`** reads `.build/docs/`, builds in memory (or a temp area), and serves a live preview. It does **not** need to write `site/` for you to browse.

**`mkdocs build`** writes the finished static website into `site/` — HTML, CSS, JS, assets — ready to deploy (rsync, GitHub Pages, nginx, etc.).

So:

- Day-to-day editing/preview → `stage` + `mkdocs serve` (uses `.build/docs/`)
- Shipping / hosting → `mkdocs build` → publish the contents of `site/`

`.build/docs/` is your assembled Markdown tree; `site/` is the compiled website.