# Working on these docs Source: https://docs.ideharmony.com/developers/documentation 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: ```text 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`: ```json { "label": "Harmony TUI Agent", "description": "The resident terminal agent.", "order": 4 } ``` ## Page frontmatter ```yaml --- title: The composer description: "One sentence. Quote it — plain YAML scalars break on colons." order: 2 status: preview platforms: [windows, macos, linux] --- ``` `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: ```markdown > [!WARNING] > This is destructive. ``` Available: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `SECURITY`, `PREVIEW`, `PLATFORM`. **Keycaps** use ``: ```markdown Press Ctrl D to split. ``` **Origin tokens** keep install commands correct across a domain change: ```markdown 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/` | ```powershell 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](/docs/developers) - [Feature status](/docs/reference/feature-status)