Working on these docs

PreviewWindowsmacOSLinuxShips in the preview channel only. Not a stable release.

How the documentation site is built, how to add a page, and how generated references stay honest.

The documentation lives in the website repository, not the application repository, and is written in Markdown under content/docs/.

Structure

The path on disk is the URL:

content/docs/index.md            → /docs
content/docs/tui/index.md        → /docs/tui
content/docs/tui/composer.md     → /docs/tui/composer

Each section directory carries a _section.json:

{
  "label": "NALA TUI Agent",
  "description": "The resident terminal agent.",
  "order": 4
}

Page frontmatter

---
title: The composer
description: "One sentence. Quote it — plain YAML scalars break on colons."
order: 2
status: preview
platforms: [windows]
---

status is one of stable, beta, preview, experimental, planned, deprecated, platform-limited. It renders as a badge directly under the page title, along with platforms.

IMPORTANT

Do not omit status to make something look more finished than it is. The badge exists so a reader never has to infer whether a feature ships.

Authoring affordances

Callouts use GitHub alert syntax:

> [!WARNING]
> This is destructive.

Available: NOTE, TIP, IMPORTANT, WARNING, SECURITY, PREVIEW, PLATFORM.

Keycaps use <kbd>:

Press <kbd>Ctrl</kbd> <kbd>D</kbd> to split.

Origin tokens keep install commands correct across a domain change:

irm https://ideharmony.com/install.ps1 | iex

https://ideharmony.com and ideharmony.com are substituted at render time from NEXT_PUBLIC_SITE_URL. Never hardcode a hostname.

Tables and code blocks get scroll containment and copy buttons automatically.

Generated references

Three pages are generated from the application source and must not be edited by hand:

Page	Source
`/docs/tui/slash-commands`	`src/tui/slash-commands/builtin-commands.ts`
`/docs/providers/registry`	`src/shared/nala/native-provider-registry.ts`
`/docs/cli/command-index`	`src/cli/commands/nala/`

npm run docs:generate        # rewrite them
npm run docs:check           # fail if they drift

The generator resolves the app repo from --app-repo, then $NALA_APP_REPO, then conventional sibling paths. --check exits 0 with a notice when the app repo is absent, so deploy containers are unaffected.

Quality gates

npm test includes documentation checks that fail the build on:

Broken internal /docs/* links
Missing title or description
Unknown status values
Duplicate routes
Images without alt text
Skipped heading levels
Authored # h1 (the route renders the title)
Pages outside a section directory
Generated files missing their do-not-edit marker

Adding a page

Create the Markdown file in the right section.
Add frontmatter, including honest status and platforms.
Link to it from a related page — orphans are legal but unhelpful.
Run npm test.
Run npm run build to confirm it prerenders.

Writing standard

Direct, calm, technical. No marketing exaggeration, no superlatives, no unverified performance claims. Prefer stating a limitation plainly over omitting it.

A public claim needs evidence from shipping source, tests, schemas, registries, or packaged behaviour. When something is unknown, say it is unknown.