|
| 1 | + |
| 2 | +# OpenRemote Documentation - Agent Instructions |
| 3 | + |
| 4 | +This repository contains the documentation for [OpenRemote](https://github.com/openremote/core), a 100% open-source IoT platform for device management, automation, data integration, and visualization. |
| 5 | + |
| 6 | +The documentation website is built using [Docusaurus](https://docusaurus.io/) and published at https://docs.openremote.io/. |
| 7 | + |
| 8 | +## Project references |
| 9 | + |
| 10 | +- [Documentation README](README.md) - Primary source of instructions for this documentation repository, including writing conventions, versioning, development, testing, and deployment. |
| 11 | +- [OpenRemote Core](https://github.com/openremote/core) - Main OpenRemote platform source code. |
| 12 | +- [OpenRemote Core README](https://github.com/openremote/core/blob/main/README.md) - Product overview, architecture, and development information. |
| 13 | +- [OpenRemote Keycloak](https://github.com/openremote/keycloak) - Customized Keycloak Docker image and OpenRemote authentication theme. |
| 14 | +- [OpenRemote Custom Project](https://github.com/openremote/custom-project) - Template for developing custom OpenRemote projects and extensions. |
| 15 | +- [OpenRemote Proxy](https://github.com/openremote/proxy) - HAProxy Docker image and reverse proxy configuration. |
| 16 | + |
| 17 | +**Always read this repository's [README.md](README.md) before making documentation changes.** |
| 18 | +It is the authoritative reference for documentation-specific instructions and workflows. |
| 19 | + |
| 20 | +This `AGENTS.md` defines additional restrictions for AI agents. |
| 21 | +Where its restrictions conflict with maintenance procedures in the README, agents must follow the restrictions in this file. |
| 22 | + |
| 23 | +Use the other repositories as references for product implementation details, configuration, APIs, deployment, and integration behavior. |
| 24 | +Their README files describe their respective components and do not replace this repository's documentation instructions. |
| 25 | + |
| 26 | +## Repository structure |
| 27 | + |
| 28 | +- `docs/` - Documentation for the next OpenRemote release (Next). |
| 29 | +- `versioned_docs/` - Documentation snapshots of released versions. |
| 30 | +- `versioned_sidebars/` - Sidebar configurations for released versions. |
| 31 | +- `versions.json` - Released versions included in the website. |
| 32 | +- `api/` - Externally managed OpenAPI specifications. |
| 33 | +- `static/` - Static website assets. |
| 34 | +- `src/` - Docusaurus components, pages, and styling. |
| 35 | +- `sidebars.ts` - Documentation navigation. |
| 36 | +- `docusaurus.config.ts` - Docusaurus configuration. |
| 37 | + |
| 38 | +## Documentation changes and versioning |
| 39 | + |
| 40 | +- Make ordinary documentation changes only in `docs/`, which contains the Next documentation. |
| 41 | +- Treat `versioned_docs/`, `versioned_sidebars/`, and `versions.json` as read-only unless the task explicitly requires changes to released documentation or documentation versioning. |
| 42 | +- Do not automatically propagate changes from `docs/` to released documentation versions. |
| 43 | +- If a correction also applies to a released version, mention the potential need for a backport rather than performing it automatically. |
| 44 | +- Ensure documented functionality is appropriate for the OpenRemote release being described. |
| 45 | +- Do not create new documentation versions unless explicitly requested. |
| 46 | +- Keep changes focused on the requested documentation. Avoid unrelated formatting changes, file moves, and reorganizations. |
| 47 | + |
| 48 | +## Writing guidelines |
| 49 | + |
| 50 | +- Use US English spelling, grammar, and terminology for all new or modified documentation. |
| 51 | +- Do not rewrite unrelated documentation solely to standardize spelling or terminology. |
| 52 | +- Follow the existing documentation structure, terminology, and writing style. |
| 53 | +- Write clear, concise, technically accurate documentation using Markdown or MDX. |
| 54 | +- Prefer Markdown syntax over HTML tags whenever Markdown provides equivalent functionality. Use HTML or MDX components only when necessary. |
| 55 | +- Prefer direct language and active voice. Avoid unnecessary repetition and promotional language. |
| 56 | +- Prefer one sentence per source line in new or substantially edited Markdown prose to produce cleaner diffs. Keep sentences belonging to the same paragraph together without blank lines. |
| 57 | +- Do not reformat unrelated existing paragraphs solely to apply the one-sentence-per-line convention. |
| 58 | +- Format Markdown tables with consistently aligned columns and properly aligned separator rows to keep them readable in the source. Preserve existing table formatting when making unrelated changes. |
| 59 | +- Use descriptive headings, short paragraphs, and practical examples where useful. |
| 60 | +- Use consistent OpenRemote terminology and preserve the exact names of UI elements, configuration properties, APIs, and commands. |
| 61 | +- Use inline code formatting for filenames, paths, commands, configuration properties, and code identifiers. |
| 62 | +- Use fenced code blocks with appropriate language identifiers. |
| 63 | +- When documenting procedures, include prerequisites, steps, and expected results where appropriate. |
| 64 | +- Prefer updating existing pages over introducing duplicate documentation. |
| 65 | +- Preserve existing technical content and wording when it is already accurate and clear. Avoid unnecessary stylistic rewrites. |
| 66 | +- Preserve existing front matter, document identifiers, URLs, and heading anchors unless changes are necessary. |
| 67 | +- Follow existing file and directory naming conventions, including numeric prefixes used for sidebar ordering. |
| 68 | +- Follow existing autogenerated sidebar conventions and use `_category_.json` metadata where appropriate. |
| 69 | +- Do not modify `sidebars.ts` merely to add a page that is already included through autogenerated navigation. |
| 70 | +- Use Docusaurus admonitions for important notes, tips, and warnings when appropriate, but avoid overusing them. |
| 71 | + |
| 72 | +## Technical accuracy |
| 73 | + |
| 74 | +- Use the relevant OpenRemote source repositories as the primary references for implementation details. |
| 75 | +- Verify documented commands, configuration properties, API endpoints, and code examples against the implementation when possible. |
| 76 | +- When documenting a released version, consult the corresponding release tag or version of the relevant OpenRemote source repository where available. |
| 77 | +- Do not assume that behavior on the `main` branch also applies to older releases. |
| 78 | +- Do not invent configuration options, API behavior, product capabilities, or compatibility information. |
| 79 | +- If a technical detail cannot be verified, report the uncertainty rather than presenting an assumption as fact. |
| 80 | +- Preserve technically meaningful details when simplifying or rewriting existing documentation. |
| 81 | +- Never include private credentials, API tokens, secrets, or personal information. |
| 82 | +- Use placeholders in examples unless documenting publicly known default or demo credentials, which must be clearly identified as such. |
| 83 | + |
| 84 | +## Links and images |
| 85 | + |
| 86 | +- Use relative Markdown links to other documentation files, including their `.md` or `.mdx` extensions. |
| 87 | +- Do not use absolute `docs.openremote.io` URLs or site-root paths for internal documentation links. |
| 88 | +- Verify that relative links and image references resolve correctly. |
| 89 | +- Use descriptive link text rather than generic phrases such as "click here". |
| 90 | +- Use relative paths for images and keep them close to the documentation that uses them. |
| 91 | +- Include meaningful alternative text for images. |
| 92 | +- Optimize new images before committing them to avoid unnecessarily increasing repository size across documentation versions. |
| 93 | + |
| 94 | +See the README for detailed guidance on Docusaurus links, images, and Markdown features. |
| 95 | + |
| 96 | +## Generated API documentation |
| 97 | + |
| 98 | +The REST and provisioning API documentation is generated from OpenAPI specifications managed outside this repository. |
| 99 | + |
| 100 | +- Treat `api/`, `docs/rest-api/`, `docs/provisioning-api/`, and their corresponding directories under `versioned_docs/` as read-only. |
| 101 | +- Do not modify OpenAPI specifications or generated API documentation. |
| 102 | +- Do not run OpenAPI documentation generation or cleanup commands. |
| 103 | +- These restrictions also apply when the README describes API generation procedures for maintainers. |
| 104 | +- If a task requires changes to these files, report that they are externally managed rather than modifying them. |
| 105 | + |
| 106 | +These files may be read and referenced when verifying technical documentation. |
| 107 | + |
| 108 | +## Docusaurus configuration and dependencies |
| 109 | + |
| 110 | +- Avoid modifying Docusaurus configuration, sidebars, dependencies, or build tooling unless required by the task. |
| 111 | +- Do not modify generated build output or dependency directories such as `build/`, `.docusaurus/`, or `node_modules/`. |
| 112 | +- Use the Yarn version configured in `package.json`. |
| 113 | +- Do not modify `yarn.lock` manually. Use Yarn to update dependencies and the lockfile when dependency changes are explicitly requested. |
| 114 | + |
| 115 | +## Validation |
| 116 | + |
| 117 | +- Review changed files for correctness, consistency, and unintended modifications. |
| 118 | +- Run `git status --short` to identify new, modified, and unexpected files. |
| 119 | +- Run `git diff --check` to detect whitespace errors. |
| 120 | +- Check changed links, image references, headings, and code examples. |
| 121 | +- Routine Markdown changes can normally rely on the GitHub Actions CI build. |
| 122 | +- Run `yarn build` for substantial structural, navigational, configuration, or versioning changes when feasible. |
| 123 | +- Use `yarn start` to preview Next documentation and `yarn serve` to inspect a production build when useful. |
| 124 | +- Do not claim that CI or local validation succeeded unless it was actually performed successfully. |
| 125 | +- Report validation that could not be performed. |
| 126 | + |
| 127 | +Refer to the [Documentation README](README.md) for additional development, validation, and release procedures. |
0 commit comments