---
inclusion: auto
---

# Documentation

## Format

- This repository SHALL use Org Mode for project documentation. New
  project docs SHALL use `.org` files.
- Architecture docs SHALL be updated when MQTT topics, payload schema,
  host roles, or data flow change.

## README Rendering

- README files in Markdown and Org mode SHALL render as semantic
  documentation, not as line-numbered source listings.
- README headings SHALL be native `h1`-`h6` elements with stable
  fragment IDs; the heading text links to its own `#fragment` URL.
- README prose SHALL use the sans-serif documentation style in
  `lib/static/readme.css`; source-block syntax colours remain in
  `syntax-theme.css`.
- Org `#+TITLE`, `#+AUTHOR`, `#+DATE`, and related metadata SHALL
  render as styled document metadata rather than raw directives.
- Other README formats currently use the Markdown-compatible fallback.
  Add parser support deliberately before claiming native support for
  another format.

## Configuration Reference

- The project SHALL include a `config.toml` file at the project root
  that serves as reference documentation.
- Every configurable variable SHALL appear in the file with its
  default value, uncommented.
- Each variable SHALL be preceded by a comment explaining the
  variable's purpose and other permissible values (e.g. types, allowed
  ranges, examples).
- When a configuration variable is added or changed, `config.toml`
  SHALL be updated in the same commit.

## Doc-Updater Agent Integration

After implementing a new feature or making a significant behavioral
change, delegate documentation updates to the **doc-updater** agent
defined in `.kiro/agents/doc-updater.md`.

### When to invoke

- A new module, route, handler, or view is added.
- Configuration options are added or changed.
- The request-flow architecture is modified.
- A new agent or hook is added under `.kiro/`.
- A TODO item is resolved.

### How to invoke

Use `orchestrate_subagent` with the `general-task-execution` role.
Provide a prompt that includes:

1. A summary of what was implemented or changed.
2. Which areas of the codebase were affected.
3. Instruction to follow the doc-updater agent spec at
   `.kiro/agents/doc-updater.md`.

### After invocation

- Review the doc-updater's report.
- Stage and commit the documentation changes (separately or with the
  feature commit, as appropriate).
- Ensure `AGENTS.org` and `.kiro/steering/project.md` remain in sync.