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	Display Name	Description	Docs URL
Atoms	Voice Agents	End-to-end voice AI agents for telephony, web, and mobile	docs.smallest.ai/atoms
Waves	Models	Text-to-Speech (Lightning) and Speech-to-Text (Pulse) APIs	docs.smallest.ai/waves

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/versions/               # Models version configs (v4.0.0, v3.0.1, v2.2.0)
│   │   └── 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/v4.0.0/*.mdx
Waves sidebar navigation	fern/products/waves/versions/v4.0.0.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/v4.0.0/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: The fern/apis/waves-v4/overrides/ directory controls what renders on the docs API reference pages. The fern/apis/waves/openapi/ and fern/apis/waves/asyncapi/ directories are used for SDK generation. Both need to stay in sync when API parameters change.

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/versions/v4.0.0.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