Docs

Appearance

Hailer Documentation Standard ​

Status: draft. The working spec for unifying Hailer's documentation.

1. Why this exists ​

Documentation has historically been fragmented across repos and left to drift. The goal of this standard is a single site, fed by markdown that lives next to the code it describes, kept current because updating it is part of the same PR that changes the code — and consumed equally by humans and agents.

Principles ​

  1. Docs live with code. Every documented repo owns a /docs (or /doc) folder, and doc changes ship in the same PR as the code.
  2. One rendered site. All repos' docs aggregate into this VitePress site (hailer-docs).
  3. Plain markdown, minimal magic. VitePress-flavored markdown + frontmatter.
  4. Agent-readable by construction. The same markdown feeds the website and the agents.

2. Architecture ​

hailer-sdk/docs/**          ─┐
hailer-app-sdk/docs/**       ├─►  aggregation build  ─►  hailer-docs (VitePress)  ─►  deploy
hailer-api/doc/v2/**        ─┘     (pins each repo,        this repo
                                    copies docs in)
  • This repo (hailer-docs) holds the site: VitePress config, theme, landing pages, and the aggregation build. Content is authored in each source repo, not here.
  • Aggregation assembles the site tree from each repo at a pinned version (git submodule under sources/), mapping a repo's docs folder to a site section. Current sections: hailer-sdk → /sdk, hailer-app-sdk → /app-sdk, hailer-api → /api.
  • Audience: the public developer/agent surface (SDKs + API).

3. Conventions ​

Frontmatter (required on every page) ​

yaml
---
title: Activity # page title + sidebar label
description: One-line summary. # used for search + RAG embedding
audience: public # public | internal
status: stable # stable | beta | deprecated
tags: [api, activity] # categorization + RAG facets
source: hailer-api # owning repo (set by aggregator if omitted)
generated: true # true = machine-generated, do not hand-edit
---

Style ​

  • Flat headings — H1 page title, H2 sections, H3 sub-sections.
  • Get to the point — lead with what it does and the minimal example; developers and agents skim.
  • RPC examples use @hailer/cli; genuinely-HTTP routes are documented with plain HTTP/curl. No framework-specific (React/Vue) snippets.
  • Sidebars are auto-generated from the folder tree. Hand-written index.md pages provide a section's landing/overview.
  • Test your examples. A snippet that doesn't run is worse than none.

4. The API reference is generated ​

The hailer-api endpoint reference is generated from the backend source — endpoint definitions and their Joi validation schemas become the Parameters/Returns tables, with a runnable @hailer/cli example per endpoint. Pages carry generated: true. Concept topics that span endpoints (for example permissions and insights) are hand-written guides.

How the generator works, and how to opt a module in, is documented in the hailer-api repository.

5. Development process & enforcement ​

TO BE DECIDED.

Hailer Developer Documentation

© 2026 Hailer