> ## 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.

# Contributing

> How to add or change docs in this repo.

You write docs the same way you write code: in branches, reviewed by a
human, deployed automatically. This page covers the mechanics.

## Setup

```bash theme={null}
git clone git@github.com:septemberai/engine-docs.git
cd engine-docs
npm i -g mint
mint dev
```

That spins up a local Mintlify server on `http://localhost:3000`. Edits
to `.mdx` files are picked up live.

## Writing a new page

1. Decide which tab the page belongs in: Platform, Operations, or
   Internal.
2. Decide the Diátaxis mode: tutorial, how-to, conceptual, or reference.
   See the [style guide](./style-guide).
3. Write the page in `.mdx` with frontmatter:
   ```yaml theme={null}
   ---
   title: "Your title"
   description: "One-line description used in search and the sidebar."
   internal: false  # set true for internal-only
   ---
   ```
4. Add the page to `docs.json` so it shows up in the navigation. The
   build will fail if you forget.
5. Cross-link from related pages.
6. Open a PR.

## Reviewing a doc PR

Reviewers check:

* **Mode purity.** Page is one Diátaxis quadrant, not several.
* **Voice.** Right person, right tense.
* **Accuracy.** Endpoint paths, env var names, types — all match the
  Engine's current behavior.
* **Code samples run.** Reviewer should be able to copy-paste and have
  it work.
* **Cross-links.** First mention links to canonical reference.
* **Internal/public split.** Anything sensitive is gated.
* **Style.** Sentence case, no marketing words, no exclamation marks.

If a page violates the style guide, the fix is to follow the style
guide, not to update the style guide. The style guide changes through
deliberate review, not by drift.

## Build flavors

The same source builds two outputs:

* **Public build.** Strips pages with `internal: true` in frontmatter.
  Strips `internal: true` blocks within pages (Mintlify supports
  conditional content).
* **Internal build.** Includes everything.

The build script reads an environment variable to decide which flavor
to produce:

```bash theme={null}
DOCS_FLAVOR=public mint build
DOCS_FLAVOR=internal mint build
```

The strip step is in `scripts/strip-internal.mjs` (TODO — script lands
with the first deploy).

## When to ask

* Should this be a new page or an addition to an existing one? — ask in
  PR review.
* Should this be public or internal? — when in doubt, internal.
* Substantial reshape of the docs surface? — discuss in the docs
  channel before opening a large PR.

## Pulling docs from the Engine source

Some pages — env vars, endpoints, event types — are best as
auto-generated content. Today they're hand-written but kept in sync with
the engine repo. The longer-term plan is a generator that reads the
engine source on every build and emits a `_generated/` tree, which is
gitignored.

## Test before merging

There's no CI test that catches a misleading paragraph, but there is one
for broken links and frontmatter. The Mintlify CLI runs both:

```bash theme={null}
mint broken-links
mint check
```

Both should be clean before requesting review.

## After merging

Mintlify rebuilds and redeploys automatically. The internal site updates
within a couple of minutes. The public site updates on the next release
window — see the release calendar.

## Learning more

* [`README.md`](../README.md) for the repo layout.
* [`CONTRIBUTING.md`](../CONTRIBUTING.md) for the public-facing version
  of this page (briefer).
* [Style guide](./style-guide) for voice and structure.