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#

1
2
3
4
5
6
7
8

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:

1
2
3
4
5
6
7

```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:

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#

1
2
3
4
5
6
7
8

# 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.