> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comforthub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing here

> Add or change a page without breaking the rules the check enforces

## Before you start

* The `mint` command installed (`npm i -g mint`) so you can preview and validate.
* The git hook wired once per clone: `git config core.hooksPath scripts/githooks`.
* A clear answer to "is this page an explanation, a how-to, or a reference?" If you cannot answer, it is two pages.

## Steps

<Steps>
  <Step title="Copy a template">
    Copy the matching file from `templates/` into the right folder. The folders mirror the menu: `handbook/`, `systems/`, `reference/`.
  </Step>

  <Step title="Fill the front matter">
    Every page needs `title`, `description`, and `kind` (`explanation`, `how-to`, `reference`, or `hub`). A page goes in only when it is finished; there are no placeholder pages.
  </Step>

  <Step title="Check every fact against the code">
    A timing, a threshold, a name, a trigger: find the code, the config row, or the vendor setting that makes it true before you write it. Put the proof in the commit message, not on the page.
  </Step>

  <Step title="Write it like you would say it">
    Short sentences. "You", not "the user". Say *customer* and *work order*, never the code names. If you must show a code name, it goes on the [Names](/reference/names) page, nowhere else. Say what is true today. No dates, no promises about later, no ticket ids, no notes about how it was tested.
  </Step>

  <Step title="End with Related">
    Every page ends with a `## Related` list of at least one link: the explanation page for its chapter, the system pages it touches, or the reference tables it leans on.
  </Step>

  <Step title="Put it in the menu">
    Add the path to `docs.json` under the right tab and group. A page not in the menu fails the check.
  </Step>

  <Step title="Run the check">
    ```bash theme={null}
    bash scripts/check.sh
    ```

    It reads every page. It fails on a missing title or kind, a page not in the menu, a broken link, a code name outside the Names page, a robotic phrase, a Title Case Heading, a date, a ticket id or a test note, or anything that looks like a secret.
  </Step>
</Steps>

## How you know it worked

`scripts/check.sh` prints `ok`, and `mint dev` shows the page in the menu where you expect it.

## When a page changes

When the system changes, the page changes in the same change or the same sitting. A page that describes what the system used to do is worse than no page.

## Related

* [Using these docs](/handbook/how-to-use-these-docs)
* [Names](/reference/names)
* [Repos and links](/reference/repos-and-links)