# Writing documentation

> Small Markdown files. One consistent reading experience.

## Edit a page in Markdown

Documentation lives in `resources/docs`. Each page is a normal `.md` file rendered by Laravel’s installed CommonMark parser. A content edit appears on the next request; it does not need a frontend rebuild.

```text
resources/docs/
  introduction.md
  quickstart.md
  connect-hermes.md
  contacts.md
  mcp-tools.md
```

Page titles, descriptions, order, and navigation groups live in `config/docs.php`. The title is rendered by the page shell, so begin the Markdown body with a level-two heading.

## Add a page

1. Create a Markdown file, such as `resources/docs/imports.md`.
2. Add an `imports` entry to `config/docs.php` with a title, description, and group.
3. Use `/docs/imports` to link to it from another page.
4. If configuration is cached, rebuild it during deployment.

The navigation, search index, previous/next links, and page route use this explicit registry. Unregistered filenames are never exposed.

## Supported formatting

Use paragraphs, headings, links, ordered and unordered lists, tables, and fenced code blocks. Level-two and level-three headings automatically become table-of-contents links, with unique anchors.

For callouts, use a blockquote with a bold opening label:

```markdown
> **Good to know**
> Markdown changes are rendered on the next request.
```

Put a language after a code fence, such as `sh`, `json`, `yaml`, or `php`. The reading interface adds a language label and a copy button. Raw HTML and unsafe link protocols are disabled.

## Search and appearance

Search runs locally in the browser against a small index of the registered documentation pages. It never queries contact records or other workspace data. Use the search button or Command/Ctrl K.

Readers can choose a light or dark theme. The preference is saved in their browser; without a saved preference, the system colour scheme is used.

## Build the presentation

Styles and interactions live in `resources/css/app.css` and `resources/js/app.js`. Run `npm run dev` while editing them, then `npm run build` for production. Neither Markdown editing nor search requires another hosted service.

Update the relevant guides and tool reference in the same commit as any change to tools, fields, permissions, validation, setup, or behaviour. Update the Hermes tool allowlist, capability discovery, README, and roadmap status when affected. Document only capabilities that are implemented; keep planned work explicitly labelled.

Keep examples fictional, never include credentials, and distinguish implemented features from planned ones. Public documentation is not the place for workspace records or deployment secrets.

Duskworks attribution uses the approved outlined artwork in `resources/views/partials/duskworks-brand.blade.php`, shared by the welcome page and documentation. It links to the main Duskworks website and inherits the active colour theme. Preserve the artwork proportions when adjusting its size.

## Documentation for agents

Orbit publishes `/llms.txt` as a concise, grouped index of the guides and `/llms-full.txt` as their complete Markdown content. Each registered guide is also available at `/docs/PAGE.md`; the introduction uses `/docs/index.md`. HTML documentation advertises its Markdown alternative and the index through link metadata.

These responses are generated from `config/docs.php` and `resources/docs/*.md` on request. Edit the normal guides; there is no separate text export to maintain or build command to run. Register a new page to include it automatically. Only registered guides are exposed, and links use the serving instance's origin. Do not put credentials, private records or installation secrets into these public source files.

The files complement MCP: documentation explains how Orbit works, while authenticated MCP tools discover current capabilities and operate on workspace records. Reading documentation does not connect an agent, grant permissions, or authorise external actions. Client support for automatic discovery varies; you can explicitly point an agent to `/llms.txt` or a specific Markdown guide.

When building the separate public Orbit website, publish these same curated guides there. Its documentation hostname must not be treated as a user's private MCP endpoint.

## Automatic checks and review

The `Orbit checks` GitHub Actions workflow runs on every push and pull request. It builds the frontend and runs the full test suite with PHP 8.5 and a disposable PostgreSQL 14 database, without production credentials.

Documentation tests check that every registered guide renders, the tool reference and Hermes allowlist match contributor tool discovery, and the generated Markdown and LLM responses include the registered guides without exposing private records. There are no separate `llms.txt` copies to update.

For each behaviour change, edit its guides in the same commit and complete the pull request's documentation checklist. Automated checks cannot determine whether every explanation or example accurately describes a changed feature; that remains part of review. Cosmetic changes do not require unrelated documentation edits.

The workflow reports failures on GitHub. To prevent merges when checks fail, configure the `Application and documentation` check as required in the repository's branch rules. Local hooks are optional conveniences and are not required for these checks to run.