Working on these docs

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.

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://nalaos.dev/install.ps1 | iex

https://nalaos.dev and nalaos.dev 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:

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

1. Create the Markdown file in the right section.
2. Add frontmatter, including honest status and platforms.
3. Link to it from a related page — orphans are legal but unhelpful.
4. Run npm test.
5. 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.

Related

• Developers overview
• Feature status