---
title: "ScaiWave public documentation \u2014 source"
path: README
status: published
---

# ScaiWave public documentation — source

This directory is the source of truth for what's published at
<https://www.scailabs.ai/docs/scaiwave>. Edit here, then run
`scripts/publish_docs.py` to push.

## Layout

```
overview.md                          # /docs/scaiwave/overview
quickstart.md                        # /docs/scaiwave/quickstart
concepts/<topic>.md                  # /docs/scaiwave/concepts/<topic>
tutorials/{first-steps,power-user,developer}/<recipe>.md
reference/api/<domain>.md
reference/<topic>.md                 # cli, configuration, error-codes, …
troubleshooting/<symptom>.md
changelog.md
```

Each `.md` file maps to a single page at
`/docs/scaiwave/v1/<relative-path-without-extension>`. Index pages for
each subtree live at `<subtree>.md` (e.g. `concepts.md` for the
`concepts/` index).

## Frontmatter

Each page starts with a fenced JSON frontmatter block that the
publisher converts into the `frontmatter` JSON field on the API:

````markdown
```json frontmatter
{ "title": "Overview", "audience": "everyone", "summary": "What ScaiWave is, in one paragraph." }
```

# Overview

…
````

Supported keys:

- `title` — required. Becomes the page's `title` field.
- `audience` — informational: `everyone`, `beginner`, `power_user`,
  `developer`, `admin`. Shown in the page card.
- `summary` — short blurb; surfaces in llms.txt and search snippets.
- `prev_url`, `next_url` — explicit nav override; otherwise sibling
  order in the tree is used.
- `status` — `published` (default) or `draft`.
- `sort_order` — integer; lower sorts first in the sidebar.

The publisher strips the frontmatter block before sending the body
to the API.

## Tone

- **First-user pages**: no jargon, no internal acronyms unless
  immediately defined. Assume the reader just got a login.
- **Power-user pages**: assume they know what a "room" is. Skip the
  preamble.
- **Developer pages**: assume HTTP + JSON literacy. Include curl
  examples. Don't apologize for technical content.

## Code fence language tags

Every fenced code block needs an explicit language tag — bare
` ``` ` lets the renderer auto-detect, which often picks wrong and
shows the content in red error-highlighting. Use:

| Content | Tag |
|---|---|
| Shell / cURL / env vars / `KEY=value` | `bash` |
| Pure JSON (strict, no comments) | `json` |
| JSON with `//` or `/* */` comments / annotations | `jsonc` |
| Python | `python` |
| TypeScript / JavaScript | `ts` / `js` |
| Markdown samples (showing the source) | `markdown` |
| HTTP request / response headers | `http` |
| YAML | `yaml` |
| Diagram | `mermaid` |
| Plain text / file trees / URLs / ad-hoc | `text` |

> **JSON pitfall.** JSON does **not** allow comments. If your example
> uses `// ...` or `/* ... */` (we use these for inline field
> annotations), the tag must be `jsonc`, not `json` — Pygments' JSON
> lexer marks comment lines as errors.

The publisher leaves the frontmatter block alone — that's the
literal string `json frontmatter`, which the renderer treats as
plain.

If you really want no highlighting, use `text` (don't leave bare).

## Publishing

```bash
# Dry-run: show what would be sent, no API calls.
.venv/bin/python scripts/publish_docs.py

# Push everything.
.venv/bin/python scripts/publish_docs.py --execute

# Push just one path.
.venv/bin/python scripts/publish_docs.py --execute --only overview
```

See `scripts/publish_docs.py --help` for the full surface.