Writing the docs

This page is the canonical writing contract for lomi. developer documentation. It merges the API style contract, Diátaxis doc types, and brand rules used across the monorepo.

Agents: install the condensed rule with lomi install-rules --target cursor (includes Docs writing). Always read llms.txt before integrating.

Brand and naming

Context	Form
Product in prose	lomi. (with trailing dot)
npm package	`@lomi./sdk`
Hostnames	`lomi.africa`, `docs.lomi.africa`, `api.lomi.africa` (no trailing dot)

Diátaxis doc types

Set docType in frontmatter on new guide pages:

Type	Use for	Examples
`tutorial`	Linear learning path	Integration journey
`how-to`	Task-focused steps	Verify payments
`explanation`	Concepts and trade-offs	Choose integration, Payment state machine
`reference`	Schemas and endpoints	REST API operation pages

Voice and structure

Direct and confident: "Creates…", "Returns…", not "This endpoint allows you to…".
Merchant-centric: status codes, idempotency, async mobile money, webhook requirements.
Question-led titles for Build guides when possible.
No filler: avoid "seamless", "robust", "powerful" without a concrete behavior.
No em dashes in prose: use commas, colons, or periods instead (table empty cells may use -).

Hand-authored guides should link to canonical references instead of duplicating tables (e.g. point to Sandbox payments for test cards).

Integration truths (repeat in guides)

Amounts in XOF use centimes (integer minor units) unless a specific API field documents otherwise.
API key determines environment: lomi_sk_test_… vs lomi_sk_live_…; wrong key against an environment returns 401.
Live mobile money is asynchronous: confirm with webhooks and GET /transactions/{id} before fulfilling orders.
Never trust client-only success: see Verify payments.

Every English page under content/docs/ (.mdx without a locale suffix) requires a French sibling (.fr.mdx). Spanish (.es.mdx) and Chinese (.zh.mdx) pages are optional locale variants. pnpm docs:drift enforces EN/FR parity.

Generated REST pages

See API reference authoring and apps/docs/lib/scripts/manual-api/DOC-STYLE-CONTRACT.md for operation page structure, banned OpenAPI phrasing, and EN_OPERATION_COPY maintenance.

Anchor pages to imitate

Drift checks

Before merging docs changes:

cd apps/docs && pnpm lint && pnpm docs:drift

From the monorepo root:

lomi docs check

CORE-38 design brief: apps/design/docs/note.md in the monorepo
Install agent rules