Skip to content

Commit 2cbdf39

Browse files
authored
Add agent guidance (#205)
1 parent dc4387e commit 2cbdf39

1 file changed

Lines changed: 127 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
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

Comments
 (0)