> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Style guide

> How we write docs.

The Engine's docs aim to be warm, conversational, respectful of the
reader's time, and concrete. This page is the long version of those
vibes, with concrete rules.

## Voice

* **Second person for tutorials and how-tos.** "You'll send a request,
  read the response, and..." A tutorial is a thing the reader is doing.
  Address them.
* **Third person for reference and conceptual.** "The Engine returns..."
  "When the agent loop encounters..." Reference and explanation are
  about the system, not about the reader.
* **Active voice.** "The Engine returns" not "is returned by the Engine."
* **Present tense for behavior.** "The Engine retries" not "the Engine
  will retry."
* **Past tense only for incidents.** "On 2026-04-12 the Engine returned
  500s for 12 minutes."

## Tone

* Warm, not cute. No emoji in technical content. No exclamation marks.
* Confident, not arrogant. State what the system does. Don't apologize
  for what it doesn't.
* Specific, not vague. Replace "many users" with a number or with "users
  who," etc.

## Structure

* **Lead with the thing.** Don't open with three paragraphs of context
  before showing code. Show the smallest working example first; explain
  after.
* **One thought per paragraph.** If a paragraph has more than one
  argument, split it.
* **Short sentences.** Long sentences hide long thinking. Cut ruthlessly.
* **Sentence-case headings.** "Streaming events" not "Streaming Events"
  or "STREAMING EVENTS." Product names keep their casing.

## Headings

* Use `##` for major sections, `###` for sub-sections. Avoid `####`. If
  you find yourself reaching for it, the page wants to be split.
* Heading text should answer "what's in this section?" — not "let's talk
  about X."
  * Bad: "About authentication"
  * Good: "How requests are authenticated"

## Lists

* Bullets when order doesn't matter.
* Numbered when order matters.
* One sentence or short clause per bullet. If a bullet runs to three
  lines, it wants to be a sub-section instead.

## Code

* Always tag code blocks with their language: `bash`, `python`, `js`,
  `ts`, `json`, `http`, `sql`.
* Code samples are real and tested. If the code is hypothetical, mark
  it `# pseudocode`.
* Use real values, not placeholders, where possible. `claude-sonnet-4-5`
  beats `<your-model>`.
* Wrap inline code in backticks: `task_id`, `X-Engine-Key`.

## Tables

* Use tables for parallel data with the same columns per row (env vars,
  endpoints, error codes).
* Use prose for narrative information.
* First column is the key being defined. Subsequent columns are
  attributes.

## Linking

* Link the first time you mention a concept; not every time.
* Use descriptive link text: "see the [agent loop](...)" not "see [here](...)."
* Internal links use relative paths. External links use full URLs.
* Cross-link reference pages from concept pages and back.

## Diátaxis discipline

Every page is one of:

| Mode       | Tense                          | Purpose                  | Example                 |
| ---------- | ------------------------------ | ------------------------ | ----------------------- |
| Tutorial   | 2nd person, present            | Learn-by-doing           | "Quickstart"            |
| How-to     | 2nd person, present            | Solve a specific problem | "Migrate from v1 to v2" |
| Conceptual | 3rd person, present            | Build a mental model     | "The agent loop"        |
| Reference  | 3rd person, present, scannable | Look up a fact           | "POST /execute"         |

Don't blend modes within a page. If a tutorial wants to explain why,
link to the conceptual page. If a reference wants narrative, link to the
how-to.

## Internal vs. external

* Anything not safe for public eyes — roadmap, customer names, cost
  figures, threat-model attacker profiles, anything touching live
  credentials — goes on a page with `internal: true` in frontmatter.
* The public build strips those pages. Don't rely on the strip — assume
  every line you write under `internal: true` could leak, and write
  carefully anyway.

## Diagrams

* Use Mermaid for all diagrams (Mintlify renders it inline). Mermaid
  produces real boxes, arrows, and clusters that render legibly in
  every browser.
* Avoid ASCII art — it's brittle, hard to maintain, and looks bad in
  most fonts.
* Always explain the diagram in prose immediately after.

## House rules for code samples

* HTTP requests show full headers. No assumed defaults.
* Python uses `httpx`. Node uses built-in `fetch`.
* Show error handling in real samples; skip it only when the page is
  explicitly about the happy path.
* Don't import what you're not using.

## Things we don't do

* We don't use marketing words. "Powerful," "robust," "best-in-class,"
  "next-generation." Cut them.
* We don't use "simply" or "just." If it's simple, it doesn't need
  saying. If it's not, the word is dishonest.
* We don't link to GitHub line numbers — they rot. Link to the file or to
  the relevant doc page.
* We don't write FAQ pages as a substitute for fixing the docs. If the
  same Q surfaces three times, fix the documentation that should have
  answered it.