Smallest AI Documentation

Source for docs.smallest.ai — the unified documentation site for Smallest AI's Voice Agents (Atoms) and Models (Waves) products.

---

About

This repository contains the source files for the Smallest AI documentation site at docs.smallest.ai. The docs are built with Fern and cover two products:

Product	Internal Name	Description	Docs URL
Voice Agents	Atoms	End-to-end voice AI agents for telephony, web, and mobile	docs.smallest.ai/voice-agents
Models	Waves	Text-to-Speech (Lightning) and Speech-to-Text (Pulse) APIs	docs.smallest.ai/models

Note on naming: the rendered URL space and product display names are voice-agents and models. The internal folder + spec names in this repo are still atoms/ and waves/ — that's intentional so SDK generation and internal tooling don't break. When editing content, work in atoms/ and waves/ folders; when writing an internal link or redirect, target /voice-agents/* and /models/*.

Repository Structure

.
├── fern/
│   ├── docs.yml                          # Main docs config (products, theme, layout)
│   ├── fern.config.json                  # Fern org + version
│   ├── docs/
│   │   ├── assets/                       # Logos, favicon, CSS, images, videos
│   │   └── changelog/                    # Changelog entries
│   ├── apis/
│   │   ├── atoms/openapi/                # Atoms (Voice Agents) OpenAPI spec
│   │   ├── waves/                        # Waves OpenAPI + AsyncAPI specs (SDK generation)
│   │   ├── waves-v4/overrides/           # Waves v4 API reference overrides (docs rendering)
│   │   └── unified/                      # Unified SDK generator config
│   ├── products/
│   │   ├── atoms.yml                     # Voice Agents navigation config
│   │   ├── atoms/pages/                  # Voice Agents documentation pages (MDX)
│   │   ├── waves.yml                     # Models navigation config
│   │   └── waves/pages/                  # Models documentation pages (MDX)
│   └── snippets/                         # Shared MDX snippets
├── .github/workflows/
│   ├── publish-docs.yml                  # Auto-publish on push to main
│   ├── preview-docs.yml                  # PR preview URLs
│   ├── python-sdk.yml                    # Python SDK generation
│   ├── ts-sdk.yml                        # TypeScript SDK generation
│   ├── go-sdk.yml                        # Go SDK generation
│   └── test-quickstarts.yml              # Quickstart code sample tests
└── README.md

Which Files to Edit

Models (Waves)

What you're changing	Where to edit
Waves docs content (pages, guides)	fern/products/waves/pages/*.mdx
Waves sidebar navigation	fern/products/waves.yml
Waves API spec (REST/HTTP endpoints)	fern/apis/waves/openapi/*.yaml
Waves API spec (WebSocket endpoints)	fern/apis/waves/asyncapi/*.yaml
Waves API ref page rendering (what shows on docs site)	fern/apis/waves-v4/overrides/*.yml
Waves images	fern/products/waves/pages/images/

Voice Agents (Atoms)

What you're changing	Where to edit
Atoms docs content	fern/products/atoms/pages/**/*.mdx
Atoms sidebar navigation	fern/products/atoms.yml
Atoms API spec	fern/apis/atoms/openapi/openapi.yaml
Atoms images	fern/products/atoms/pages/images/

Global

What you're changing	Where to edit
Product toggle, global config	fern/docs.yml
CSS / styling	fern/docs/assets/styles/global-styling.css
Logos, favicon	fern/docs/assets/
Shared MDX snippets	fern/snippets/

Important — three spec layers for waves:

1. Base spec at fern/apis/waves/{openapi,asyncapi}/*.yaml — source of truth for structure.
2. SDK overrides at fern/apis/waves/{openapi,asyncapi}/*-overrides.yaml (siblings of base) — drive SDK method names, examples, and deprecations via fern/apis/unified/generators.yml.
3. v4 docs overrides at fern/apis/waves-v4/overrides/*.yaml — drive what renders on the docs.smallest.ai/models/api-reference/* pages via fern/apis/waves-v4/generators.yml. The -v4 directory name is a historical carry-over from an earlier version-selector setup; the folder name stays because SDK-gen configs reference it by path.

A description, default, enum, or example set in the v4 docs override wins on docs render. Editing the same field in the base spec alone is invisible. Always update both layers in lockstep, and run python3 scripts/spec-live-tests/spec_drift_check.py before pushing — CI runs it on every PR that touches fern/apis/waves/** or fern/apis/waves-v4/overrides/**.

Atoms has its own base + override pairs (REST under fern/apis/atoms/openapi/ and WS under fern/apis/atoms/asyncapi/). The atoms WebSocket endpoint at WSS /atoms/v1/agent/connect lives in agent-ws.yaml and renders at /voice-agents/api-reference/api-reference/realtime-agent/realtime-agent — easy to miss if you only audit openapi/. The drift check script auto-discovers all atoms and waves layers.

Setup

Prerequisites

• Node.js 18+
• npm or yarn
• A Fern account and FERN_TOKEN (for publishing)

Install Fern CLI

npm install -g fern-api

Local Development

Preview the docs locally with hot-reload:

fern docs dev

This starts a local server at http://localhost:3000 with live reloading as you edit MDX and config files.

Preview a Build

Generate a preview URL (useful for PR reviews):

fern generate --docs --preview

Publish to Production

Publishing happens automatically when changes are merged to main via the publish-docs.yml GitHub Action. To publish manually:

FERN_TOKEN=<your-token> fern generate --docs

Upgrade Fern Version

fern upgrade

Then update the version in fern/fern.config.json if needed.

Contributing

We welcome contributions from the community! Here's how to get started:

1. Fork & Clone

git clone https://github.com/smallest-inc/smallest-ai-documentation.git
cd smallest-ai-documentation
npm install -g fern-api

2. Create a Branch

git checkout -b docs/your-change-description

3. Make Your Changes

• Content changes: Edit MDX files in the relevant pages/ directory (see Which Files to Edit)
• Navigation changes: Edit the YAML config (atoms.yml or waves.yml)
• API spec changes: Edit OpenAPI/AsyncAPI files in fern/apis/
• Style changes: Edit fern/docs.yml or fern/docs/assets/styles/global-styling.css

4. Preview Locally

fern docs dev

Verify your changes look correct at http://localhost:3000.

5. Submit a Pull Request

Push your branch and open a PR against main. A preview URL will be automatically generated and posted as a PR comment.

Guidelines

• All content pages use MDX format (Markdown + JSX components)
• Follow existing naming conventions for file and folder names
• Keep images in the images/ directory next to the pages that use them
• Use Fern's component library for callouts, cards, tabs, etc.
• Test that internal links work by previewing locally before submitting

Related Repositories

Repository	Description
smallest-python	Official Python SDK
smallest-js	Official JavaScript/TypeScript SDK
cookbook	Examples and guides for using Smallest AI

Support

• Documentation: docs.smallest.ai
• Discord: Join our community
• Email: support@smallest.ai
• Issues: Open an issue