diff --git a/README.md b/README.md
index 261bcbd..0ccff34 100644
--- a/README.md
+++ b/README.md
@@ -2,69 +2,502 @@
 
 [![GitHub Actions Status](https://github.com/openremote/documentation/actions/workflows/ci_cd.yml/badge.svg?branch=main)](https://github.com/openremote/documentation/actions/workflows/ci_cd.yml)
 
-This repository contains the OpenRemote documentation hosted on https://docs.openremote.io/ as Markdown files in the [docs directory](docs).
+This repository contains the OpenRemote documentation published at [docs.openremote.io](https://docs.openremote.io/).
 
-The documentation website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
-The OpenAPI documentation is generated using the [Docusaurus OpenAPI Docs](https://docusaurus-openapi.tryingpan.dev/) plug-in.
+The documentation is written in Markdown and built using [Docusaurus](https://docusaurus.io/). The OpenAPI documentation is generated using the [Docusaurus OpenAPI Docs](https://docusaurus-openapi.tryingpan.dev/) plug-in.
 
-### Installation
+## Documentation versions
+
+The documentation website contains two kinds of documentation:
+
+- **Next** contains documentation for the next OpenRemote release. Its source files are stored in [`docs`](docs).
+- **Released versions** are snapshots created for published OpenRemote releases. Their source files are stored in [`versioned_docs`](versioned_docs).
+
+The latest released version is shown by default on the documentation website. Use the version dropdown in the navigation bar to view **Next** or an older release.
+
+The released versions that are currently included in the website are listed in [`versions.json`](versions.json).
+
+A documentation version is normally created after every **major or minor OpenRemote release**.
+
+A separate documentation version is not normally created for patch releases. Patch releases have a limited scope and generally do not introduce enough documentation changes to justify another complete documentation snapshot. Corrections that also apply to the current release can instead be added directly to its existing documentation version.
+
+For more information, see the [Docusaurus versioning documentation](https://docusaurus.io/docs/versioning).
+
+## Writing documentation
+
+Documentation pages are written using Markdown with additional features provided by Docusaurus and MDX.
+
+See the [Docusaurus Markdown features documentation](https://docusaurus.io/docs/markdown-features) for a complete overview.
+
+### Front matter
+
+A document can begin with optional YAML front matter enclosed by `---` lines:
+
+```markdown
+---
+title: Working with agents
+description: Configure agents and protocol integrations in OpenRemote.
+sidebar_label: Agents and protocols
+---
+
+# Working with agents
+```
+
+Useful front-matter properties include:
+
+- `title`: the document title used by Docusaurus and page metadata;
+- `description`: the page description used by search engines and link previews;
+- `sidebar_label`: an alternative, shorter title for the sidebar;
+- `sidebar_position`: an explicit position in an autogenerated sidebar;
+- `slug`: a custom URL for the page;
+- `keywords`: search-engine metadata for the page.
+
+Most OpenRemote documentation is placed in autogenerated sidebars. Numeric prefixes in file and directory names are used to keep pages in a predictable order. Use `sidebar_position` only when the normal file ordering is not sufficient.
+
+Avoid defining a custom `id` or `slug` unless there is a specific reason to change the generated document identifier or URL. Changing an existing identifier or URL can break incoming links.
+
+See the [Docusaurus docs front-matter reference](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter) for all supported properties.
+
+### Admonitions
+
+Use Docusaurus admonitions to highlight information that deserves special attention.
+
+Available types include `note`, `tip`, `info`, `warning`, and `danger`:
+
+```markdown
+:::note
+
+This information is useful but does not require immediate action.
+
+:::
+
+:::tip
+
+This is a recommended way to complete the task.
+
+:::
+
+:::warning
+
+Changing this setting may affect an existing deployment.
+
+:::
+
+:::danger
+
+This action permanently removes the stored data.
+
+:::
+```
+
+An optional title can be added after the admonition type:
+
+```markdown
+:::warning Back up your data
+
+Create a database backup before continuing.
+
+:::
+```
+
+Use admonitions sparingly. Important information should still be included in the normal flow of the documentation rather than placing most of a page inside highlighted blocks.
+
+See the [Docusaurus admonitions documentation](https://docusaurus.io/docs/markdown-features/admonitions) for more examples.
+
+### Internal links
+
+Use **relative Markdown file links including the `.md` or `.mdx` extension** when linking to another documentation page.
+
+For example, from a file in the same directory:
+
+```markdown
+[Preparing the environment](./010-preparing-the-environment.md)
+```
+
+To link to a document in another directory:
+
+```markdown
+[Quick start](../../quick-start.md)
+```
+
+To link to a specific heading:
+
+```markdown
+[Setting the working directory](./020-setting-up-an-ide.md#setting-the-working-directory)
+```
+
+Do not use a public `https://docs.openremote.io` URL for links between pages in this repository.
+
+For example, do not use:
+
+```markdown
+[Manager UI](https://docs.openremote.io/docs/user-guide/manager-ui/)
+```
+
+Also avoid site-root links such as:
+
+```markdown
+[Manager UI](/docs/user-guide/manager-ui/)
+```
+
+Instead, link to the source Markdown file using a relative path:
+
+```markdown
+[Manager UI](../020-manager-ui/10-manager-ui.md)
+```
+
+Docusaurus resolves relative file links during the build. This means that:
+
+- links work when viewing Markdown files on GitHub;
+- links work when serving the documentation locally;
+- links work when the website is deployed below a different base URL;
+- Docusaurus can validate whether the target exists;
+- custom document slugs can change without requiring every link to be updated;
+- a page in a released documentation version links to the corresponding page in that same version.
+
+The final point is particularly important for OpenRemote documentation. A link on a page in version `1.28.0` should normally open the corresponding page in version `1.28.0`, not the latest or Next version.
+
+A hard-coded `https://docs.openremote.io` link bypasses Docusaurus version-aware routing. It may send users away from the documentation version they are currently reading and makes local deployments harder to test.
+
+Use full URLs only for external websites:
+
+```markdown
+[Docusaurus](https://docusaurus.io/)
+```
+
+See the [Docusaurus Markdown links documentation](https://docusaurus.io/docs/markdown-features/links) for more information.
+
+### Images
+
+Reference documentation images using relative paths:
+
+```markdown
+![OpenRemote architecture](./img/architecture.jpg)
+```
+
+Keep images close to the documentation that uses them where practical. Ensure the relative path works from the source document rather than relying on the final website URL.
+
+Optimize images before committing them. The contents of `docs` are copied when a new documentation version is created, so unnecessarily large images may be duplicated across multiple versions and permanently increase the repository and checkout size.
+
+Use an appropriate optimizer for the image format, for example:
+
+- [`zopflipng`](https://github.com/google/zopfli) for lossless PNG compression;
+- `jpegoptim`, `jpegtran`, or MozJPEG for JPEG images;
+- `svgo` for SVG images.
+
+For a PNG image, a command could look like:
 
 ```shell
-$ yarn
+zopflipng image.png image-optimized.png
 ```
 
-### Local Development
+Verify the optimized image before replacing the original. Screenshots must remain readable, particularly where they contain small text or interface controls.
+
+Also consider cropping images to the relevant content and reducing excessive image dimensions.
+
+## Installation
+
+Install the dependencies:
 
 ```shell
-$ yarn start
+yarn
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+The required Yarn version is configured through the `packageManager` property in [`package.json`](package.json).
+
+## Local development
 
-### Build
+Start the local development server:
 
 ```shell
-$ yarn build
+yarn start
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+This opens the documentation website in a browser. Most changes are reflected without restarting the server.
 
-When the static content has been generated it can be tested using:
+For faster development, the local development server only includes the **Next** documentation from `docs`.
+
+## Build
+
+Create a production build containing all versions listed in `versions.json` and Next:
 
 ```shell
-$ yarn serve
+yarn build
 ```
 
-### OpenAPI Documentation
+The generated static website is written to the `build` directory.
+
+Serve the production build locally using:
+
+```shell
+yarn serve
+```
 
-To update the OpenAPI Documentation do the following:
+Use a production build when testing released documentation, version switching, generated REST API documentation, or changes to the complete website.
 
-1. Update the `api/openapi.yaml` specification.  
-   It can be downloaded from a running OpenRemote instance, e.g.:  
-   `wget -O api/openapi.yaml http://localhost:8080/api/master/openapi.yaml`
-2. Replace the server URL in `api/openapi.yaml` from `/api/{realm}` to `https://demo.openremote.io/api/{realm}`, e.g.:  
-   `sed -i 's#/api/{realm}/#https://demo.openremote.io/api/{realm}/#g' api/openapi.yaml`
-3. Remove the previously generated OpenAPI documentation using:  
-   `yarn clean-api-docs all`
-4. Regenerate the OpenAPI documentation using:  
-   `yarn gen-api-docs all`
+## Testing pull requests
 
-### Deployment
+The continuous-integration workflow builds documentation pull requests to check that the website can be generated successfully.
 
-The deployment is done automatically by a GitHub Actions workflow when commits are pushed to the "main" branch.
+Pull requests currently do not receive a publicly accessible documentation preview. Support for deployable pull-request previews is tracked in [issue #61: Add PR preview support](https://github.com/openremote/documentation/issues/61).
 
-It can also be done manually using the "deploy" command.
+Routine documentation changes normally do not need to be tested locally when the CI build succeeds. This includes correcting or adding text, adding or removing ordinary documentation pages or images, and updating simple internal links.
 
-Using SSH:
+Changes with a major impact should be tested and verified locally before they are merged. Examples include substantial navigation changes, Docusaurus configuration or styling changes, large documentation reorganizations, versioning changes, and large generated REST API documentation updates.
+
+For major changes affecting the complete or versioned website, run:
 
 ```shell
-$ USE_SSH=true yarn deploy
+yarn build
+yarn serve
 ```
 
-Not using SSH:
+Screenshots can be added to the pull-request description when they help reviewers assess visual changes that cannot yet be viewed through an online preview.
+
+## OpenAPI documentation
+
+The REST API documentation is generated from the OpenAPI specifications in the [`api`](api) directory.
+
+Updating and generating the REST API documentation is currently a manual process.
+
+To update it:
+
+1. Update the `api/openapi.yaml` specification.
+
+   It can be downloaded from a running OpenRemote instance, for example:
+
+   ```shell
+   wget -O api/openapi.yaml http://localhost:8080/api/master/openapi.yaml
+   ```
+
+2. Replace the server URL in `api/openapi.yaml` from `/api/{realm}` to `https://demo.openremote.io/api/{realm}`:
+
+   ```shell
+   sed -i 's#/api/{realm}/#https://demo.openremote.io/api/{realm}/#g' api/openapi.yaml
+   ```
+
+3. Remove the previously generated OpenAPI documentation:
+
+   ```shell
+   yarn clean-api-docs all
+   ```
+
+4. Regenerate the OpenAPI documentation:
+
+   ```shell
+   yarn gen-api-docs all
+   ```
+
+5. Verify the generated changes and create a production build:
+
+   ```shell
+   yarn build
+   ```
+
+Generated OpenAPI documentation under `docs` follows the same versioning rules as the other documentation. Changes under `docs` appear under **Next** until a new documentation version is created.
+
+Automating this process is planned and tracked in [issue #26: Automate REST API documentation generation](https://github.com/openremote/documentation/issues/26).
+
+## Creating a documentation version
+
+Creating a released documentation version is currently a manual process.
+
+Before creating a version:
+
+1. Confirm that the corresponding major or minor OpenRemote release has been published or is ready to be published.
+2. Make sure the contents of `docs` represent that OpenRemote release.
+3. Update and regenerate the REST API documentation.
+4. Make sure images and other large assets have been optimized.
+5. Make sure `yarn build` completes successfully.
+6. Make sure all intended changes have been merged.
+
+Create the new documentation version using:
+
+```shell
+yarn docusaurus docs:version <version>
+```
+
+For example:
+
+```shell
+yarn docusaurus docs:version 1.29.0
+```
+
+This creates:
+
+- `versioned_docs/version-<version>`, containing a snapshot of `docs`;
+- `versioned_sidebars/version-<version>-sidebars.json`, containing a snapshot of the sidebar;
+- a new entry in `versions.json`.
+
+### Removing an older version from the website
+
+Each version included in `versions.json` increases the production build time and memory usage.
+
+When adding a new released version, review whether the oldest version should be removed from the active documentation website. To do so, remove its entry from [`versions.json`](versions.json).
+
+Do **not** delete its files from:
+
+```text
+versioned_docs/version-<version>
+versioned_sidebars/version-<version>-sidebars.json
+```
+
+The historical Markdown snapshot remains in the repository even though it is no longer part of the deployed documentation website.
+
+We are investigating ways to make older archived versions available separately without requiring every historical version to be built as part of the main documentation website. This work is tracked in [issue #141: Archive old documentation versions as artifacts](https://github.com/openremote/documentation/issues/141).
+
+### Completing the release
+
+After creating the new version and updating `versions.json` where appropriate, run:
+
+```shell
+yarn build
+```
+
+Review the generated files and commit all changes.
+
+The new version becomes the latest released documentation after the changes are merged into `main` and the deployment workflow completes.
+
+Improvements to the release process are tracked in:
+
+- [issue #26: Automate REST API documentation generation](https://github.com/openremote/documentation/issues/26);
+- [issue #141: Archive old documentation versions as artifacts](https://github.com/openremote/documentation/issues/141);
+- [issue #166: Add documentation to Release Management docs](https://github.com/openremote/documentation/issues/166);
+- [issue #184: Document deployment of new commits without a version change](https://github.com/openremote/documentation/issues/184).
+
+The longer-term goal is to automate more of the REST API generation, documentation version creation, current-version update, and archival process. Until that automation is implemented, maintainers must perform and review these steps manually.
+
+## Deployment
+
+GitHub Actions builds the documentation for pull requests targeting `main`.
+
+Pull-request builds validate that the documentation can be generated successfully, but they are not deployed and do not currently provide a preview URL.
+
+When changes are pushed or merged into `main`, GitHub Actions automatically builds and deploys the website to GitHub Pages.
+
+The workflow can also be started manually from the **Actions** tab using the `workflow_dispatch` trigger.
+
+## Frequently asked questions
+
+### Why do I not see my merged changes on the documentation page?
+
+Changes made to files under `docs` belong to the unreleased **Next** documentation.
+
+The documentation website displays the latest released version by default. Select **Next** from the version dropdown to see the changes.
+
+After the next major or minor OpenRemote release, a new documentation version is created from the contents of `docs`. That version then becomes the default documentation.
+
+Also check that the pull request has been merged into `main`, the GitHub Actions deployment completed successfully, and you are viewing the expected documentation version.
+
+### Why was no documentation version created for a patch release?
+
+Documentation versions are normally created for major and minor OpenRemote releases, but not for patch releases.
+
+Patch releases have a limited scope and normally contain targeted bug fixes rather than significant new functionality. Creating and maintaining a complete documentation snapshot for every patch release would add build and maintenance overhead for relatively few documentation differences.
+
+Corrections relevant to the current release can be applied directly to its existing documentation version without creating a new version.
+
+### How do I make a documentation change available in the current release immediately?
+
+Update both:
+
+```text
+docs/<path-to-document>
+```
+
+and the corresponding file in the latest released version:
+
+```text
+versioned_docs/version-<latest-version>/<path-to-document>
+```
+
+Updating the released copy makes the change visible in the current documentation after it is merged into `main` and deployed.
+
+The copy under `docs` should normally be updated as well. Otherwise, the correction may disappear when the next documentation version is created.
+
+For structural changes, you may also need to update the corresponding file under `versioned_sidebars`.
+
+Always run `yarn build` when changing released documentation.
+
+### Should every change be added to the current released version?
+
+No.
+
+Add a change only to `docs` when it describes functionality intended for the next OpenRemote major or minor release but not available in the current release.
+
+Update both `docs` and the latest released version when correcting or clarifying documentation that also applies to the current release.
+
+Older released versions should normally remain unchanged unless the correction is also relevant to those versions.
+
+### Should a patch-release change be added to Next or the current version?
+
+When a patch release changes behaviour that users need to understand, update both the current released documentation version and `docs`.
+
+Do not create a separate Docusaurus documentation version solely for the patch release.
+
+### Why can I see my changes with `yarn start`, but not in the released documentation?
+
+The local development server only loads the **Next** documentation from `docs`.
+
+To test released documentation and the version dropdown, create and serve a production build:
 
 ```shell
-$ GIT_USER=<Your GitHub username> yarn deploy
+yarn build
+yarn serve
 ```
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+### Can I preview a pull request online?
+
+Not currently.
+
+The pull-request workflow checks that the documentation builds, but it does not deploy the result or provide a preview URL. Adding this functionality is tracked in [issue #61: Add PR preview support](https://github.com/openremote/documentation/issues/61).
+
+Only changes with a major visual, structural, navigational, generated-content, or versioning impact generally need to be tested locally. Routine documentation changes can normally rely on the CI build.
+
+### Why is my pull request not visible on the public documentation website?
+
+Pull requests are built for validation but are not deployed.
+
+The public website is updated only after changes have been merged into `main` and the deployment workflow has completed successfully.
+
+### Why does an internal link open the wrong documentation version?
+
+The link probably uses a public website URL or site-root path instead of a relative Markdown file path.
+
+Avoid links such as:
+
+```markdown
+[Manager UI](https://docs.openremote.io/docs/user-guide/manager-ui/)
+```
+
+Instead, link to the source Markdown file using a relative path:
+
+```markdown
+[Manager UI](../user-guide/020-manager-ui/10-manager-ui.md)
+```
+
+Docusaurus can then rewrite the link so it points to the target page in the currently viewed documentation version.
+
+### Why should images be optimized before committing them?
+
+Images stored alongside versioned documentation are copied when a new documentation version is created.
+
+An unnecessarily large image may therefore be stored repeatedly in `docs` and several `versioned_docs` directories. Optimizing the original before it is versioned avoids multiplying that overhead.
+
+Use a lossless optimizer such as `zopflipng` for PNG screenshots where possible, and verify that text and interface details remain readable.
+
+### Why are older versions removed from the version dropdown?
+
+Every version listed in `versions.json` must be included in the Docusaurus production build. Keeping every historical version active indefinitely increases build time and memory usage.
+
+When a new major or minor documentation version is created, an older version may therefore be removed from `versions.json`.
+
+Its Markdown and versioned sidebar files remain in the repository. We are investigating a separate archival mechanism so these older snapshots can be made available without rebuilding all of them as part of the main website. See [issue #141: Archive old documentation versions as artifacts](https://github.com/openremote/documentation/issues/141).
+
+### When should a new documentation version be created?
+
+Create a new documentation version after each major or minor OpenRemote release.
+
+Do not create a documentation version for every merged documentation pull request, ordinary corrections to existing documentation, or patch releases with limited documentation changes.
+
+Until the next major or minor release is published, ongoing changes remain available under **Next**.