Writing docs

The rule

Every change to the code updates this documentation, in entrosity-docs, pushed together with the code change. A change is not done until the docs describe it.

If you change…	Update
A portal page, a form, a label or a workflow	The page under user-guide/ or administration/
A role or an access rule (rbac, portal/access.go)	Roles and permissions
api/openapi.yaml of a backend	Nothing for the endpoint reference (it is rendered from specs/, refreshed automatically); update Portal API or Hub API if conventions change
An error code (apperr.New, job or push codes)	Error codes
An RMM_* or PLATFORM_* variable or compose settings	Configuration (and Installation for production .env)
A migration	Data model, including the migrations table
A protocol message, job type or payload (entrosity-shared-go/proto)	Protocol, Agent or Connector
Agent or connector CLI, MSI properties, files	Agent, Connector
Deploy scripts, workflows, monitoring (entrosity-infra)	The page under operations/ and CI workflows
An Entrosity Edge page, form, label or workflow (entrosity-edge.frontend)	The page under edge/
An Edge role, error code, EDGE_* variable, migration or retention window (entrosity-edge.backend)	Edge roles, Error codes, Running Entrosity Edge
An Edge protocol message, job or payload (entrosity-shared-go/proto/edge), the Edge connector's CLI, MSI or simulator	Edge connector protocol, Edge connector, Trying Edge with the simulator
A Sphere role, access rule, error code, SPHERE_* variable, migration, job or retention window (entrosity-sphere.backend), or its media server settings (entrosity-infra deploy/mediamtx.yml)	Sphere roles, Error codes, Running Entrosity Sphere
A Sphere protocol message, job or payload (entrosity-shared-go/proto/sphere), the Sphere connector's CLI, MSI, drivers or simulator	Sphere connector protocol, Sphere connector, Trying Sphere with the simulator
An Entrosity Matrix page, form, label or workflow (entrosity-matrix.frontend)	The page under matrix/
A Matrix role, access rule, error code, MATRIX_* variable, migration, job, retention window or the import-stop-internet command (entrosity-matrix.backend), or its deployment (entrosity-infra, compose profile matrix)	Matrix roles, Error codes, Running Entrosity Matrix
A Matrix protocol message, job, payload or authorization rule (entrosity-shared-go/proto/matrix), the Matrix connector's CLI, guard, check, MSI or simulator	Matrix connector protocol, Matrix connector, Trying Matrix with the simulator
A Vertex role, access rule, error code, VERTEX_* variable, migration or retention window (entrosity-vertex.backend), or the Axis side of Vertex (RMM_VERTEX_*, RMM_INTERNAL_ADDR, the relay)	Vertex roles, Vertex troubleshooting, Running Entrosity Vertex
A Vertex protocol message, operation or payload (entrosity-shared-go/proto/vertex), or the connector's Vertex script, guard or vertex guard CLI	Vertex protocol, The connector's local guard, Site connector
A Make target	Make targets
A repository, or how they depend on each other	Repositories
Anything user-visible	CHANGELOG.md in this repository (the Changelog page is generated from it)
Any page under docs/	Its Bulgarian copy under i18n/bg/ (see Translations)

Every repository's CLAUDE.md carries the same rule for AI-assisted changes.

The site

• Repository: entrosity-docs (Docusaurus 3, TypeScript config).
• Content: docs/**/*.md. Sidebar order: sidebars.ts (every page must be listed there).
• The API references at /api-reference (Axis), /hub-api-reference (Hub), /edge-api-reference (Edge), /sphere-api-reference (Sphere), /matrix-api-reference (Matrix) and /vertex-api-reference (Vertex) are rendered by Redocusaurus from specs/axis-openapi.yaml, specs/hub-openapi.yaml, specs/edge-openapi.yaml, specs/sphere-openapi.yaml, specs/matrix-openapi.yaml and specs/vertex-openapi.yaml, snapshots of the backends' api/openapi.yaml. pnpm fetch:specs [ref] refreshes them; the openapi-updated.yml workflow does it when a backend changes its spec on main.
• The changelog page is generated from CHANGELOG.md by scripts/sync-changelog.mjs before start and build; do not edit docs/changelog.md (it is git-ignored).
• Diagrams are Mermaid code blocks (```mermaid).
• Search is local (@easyops-cn/docusaurus-search-local); the index is built by pnpm build, so search works in the built site, not in pnpm start.

pnpm install
pnpm start    # http://localhost:3000 with live reload
pnpm build    # fails on broken links and anchors
pnpm serve    # serve the built site

Translations

The site is published in English (the default, at the root) and Bulgarian (under /bg/). Readers switch with the language menu in the navbar.

What	English	Bulgarian
Pages	docs/**/*.md	i18n/bg/docusaurus-plugin-content-docs/current/**/*.md, same paths
Sidebar category labels	sidebars.ts	i18n/bg/docusaurus-plugin-content-docs/current.json
Navbar and footer	docusaurus.config.ts	i18n/bg/docusaurus-theme-classic/navbar.json, footer.json
Theme and search strings	built in	i18n/bg/code.json

• English is the source. Change the English page first, then its Bulgarian copy in the same commit. A page without a Bulgarian copy falls back to English on the Bulgarian site.
• Headings in Bulgarian pages carry the English anchor as an explicit ID (## Инсталиране {#installation}), so links and anchors are the same in both languages. pnpm i18n:scaffold docs/<page>.md copies a new English page into i18n/bg/ with those IDs, ready to translate. pnpm i18n:check reports pages without a Bulgarian copy and headings whose IDs differ between the two.
• Keep UI element names in English, exactly as the portal shows them (the portal is English-only). Code, paths, variables, codes and API names are never translated.
• Entrosity Edge and Entrosity Matrix are the exception: their apps are translated, so the Bulgarian pages under edge/ and matrix/ name UI elements with the app's own Bulgarian labels (the bg messages in entrosity-edge.frontend/src/**/messages.ts and entrosity-matrix.frontend/src/**/messages.ts).
• The changelog is English only; the Bulgarian site shows the same page under a translated title.
• New labels in sidebars.ts or docusaurus.config.ts: pnpm docusaurus write-translations --locale bg adds them to the JSON files (existing translations are kept); translate the new entries.
• pnpm start serves one language at a time; pnpm start --locale bg serves the Bulgarian site. pnpm build builds both.

Publishing

The site is served at https://hub.entrosity.com/docs/ by the web image's Caddy.

This repository's ci.yml builds the site with DOCS_BASE_URL=/docs/, pushes the static image ghcr.io/entrosity/docs:main on main and sends deploy to entrosity-infra, whose deploy workflow rebuilds the web image and deploys it (Continuous deployment): deploy/Dockerfile.web copies the site to /srv/docs, and deploy/Caddyfile serves /docs/* with its own Content-Security-Policy (the portal's policy forbids the inline scripts Docusaurus needs).

Locally the site runs at the root (http://localhost:3000/). DOCS_URL (default https://hub.entrosity.com) and DOCS_BASE_URL (default /) change the published address. DOCS_LINK_CHECK=warn downgrades broken links to warnings.

Style

• Write for the reader of that section: task-first in the user guide, exact and complete in the reference.
• .md files are plain CommonMark (braces and angle brackets are safe). Use .mdx only for pages that need React components.
• Name UI elements exactly as the portal shows them, in bold.
• Put code, paths, variables and codes in backticks. Name the repository when a path is not in this one (entrosity-axis.backend/internal/...).
• Use admonitions (:::note, :::tip, :::warning, :::danger) for what readers must not miss.
• Link between pages with relative .md paths so the build checks them.
• Check facts against the code, not against older documents.

Engineering records

engineering/ in this repository keeps the implementation plan, the phase plans, the roadmap checklists and the performance reports. Those are records of how the product was built; this site is the documentation of what it is.