Maintain and publish documentation
The documentation is a separate Docusaurus product under docs-site/. Public guides are English; the Suite interface supports English and Italian. Describe the current implemented behavior and use English UI labels in procedures. Internal incident, restore, and credential-custody procedures remain in the repository's root docs/ directory.
Update a guide
- Inspect the page, its data actions, and server authorization before describing a feature. A visible button, a role helper, and an accepted API request are different evidence.
- Update the relevant Markdown page under
docs-site/docs/. State the audience, prerequisites, actions, expected result, and error handling. - Register new pages in
sidebars.ts, link them from the relevant overview, and update the permissions table and troubleshooting when behavior changes. - Preserve old page URLs and headings where useful, or update every link to a renamed section.
- Run
npm run docs:buildfrom the repository root. Preview navigation and changed layouts withnpm run docs:serve.
Keep user procedures focused on decisions and controls. Put implementation details in Operating the Suite and link to them when useful. Do not describe a future fix as available, or an unsupported workflow as self-service.
Coverage by user task
| Task | Guide |
|---|---|
| First access, recovery, navigation, role limits | Getting started, permissions |
| Find, create, and maintain drone records, types and configuration codes | Drone list and details |
| Files, paged flight logs, sessions and arming activity, maintenance evidence | Records and maintenance |
| Gallery files, Client sharing, QR access | Media and sharing |
| Enrolment, replacement, vehicle access and SSH | Setup, remote link, SSH |
| Fleet map, telemetry, stations, parameter exports | Connect and monitor |
| Mission read/export/upload and flight actions | Missions |
| Saved sources, playback, gimbal, zoom | Video and cameras |
| Current camera-launch limitation for Clients and offline vehicles | Video and cameras, permissions |
| Provider credentials and SIM usage | SIM configuration |
| Organizations, contacts, customer logins, internal users | Administration |
| Customer Client creation and replacement temporary passwords | Client accounts |
| Harlock remote-control grants and separate LTE-off authorization | Users and access, API |
| Phone/tablet navigation, compact rows and action menus | Sign in and navigate |
| Licence/device lifecycle and adoption | Licenses, My licenses |
| Installer selection and download eligibility | Software |
| Suite maintenance, profile, preferences and sign-out | Maintenance mode, Account |
| Symptoms, unavailable controls, reporting | Troubleshooting, glossary |
| Hosting, configuration, identity and integration | This sidebar's architecture, deployment, environment, OIDC, API, and testing guides |
Use this map when changing navigation or adding an action; a new destination or role-specific flow needs a guide or an explicit link to one.
Generated references
The build regenerates the selected TypeScript reference from typedoc.json and typedoc.tsconfig.json. Their entry-point lists must agree; generated TypeScript pages are not committed.
The HTTP route index is regenerated from all explicit app/api/**/route.ts exports. Its committed output makes inventory changes reviewable. Both local @swagger and @openapi annotations are recognized. An inventory or a successful build does not prove that every schema or permission description is correct.
Refresh screenshots and verify roles
Stop any local Suite development server first. From the repository root run:
node docs-site/scripts/capture-suite-screenshots.mjs
The script uses a temporary SQLite database under .local/, synthetic identities and records, a random session secret, and a loopback-only Next server. Remote storage, release credentials, and vehicle provisioning are disabled. It captures the actual Suite interface in English/dark mode at desktop and phone widths; each image's viewport is recorded in the manifest. It verifies selected Administrator, Operator, and Client permissions, including customer-account actions, three saved camera slots, maintenance mode, and continued health-API access.
The video check records the current UI limitation: saved-camera launch buttons are disabled without connected telemetry, including for Clients whose media authorization remains valid. It is not a statement that Clients should lose playback permission. When that behavior changes, update the capture check, video guide, permissions matrix, troubleshooting, and screenshots together. The preview uses no real video or telemetry and cannot validate aircraft control or radio handover.
It uses the installed Microsoft Edge by default. Set DOCS_BROWSER_CHANNEL=chrome if Chrome is the installed supported browser. Stop on a failed role assertion, inspect the implementation, and correct the guide or report an application regression; do not weaken the expected access policy just to capture an image.
Images and capture-manifest.json are saved under static/img/screenshots/. Inspect each changed image, identify the demonstrated role in its caption, and keep credentials, enrolment commands, real customer data, and live flight operations out of screenshots. Synthetic records are illustrations, not evidence of hardware compatibility or measured performance.
Package and publish
npm --prefix docs-site run worker:check
This builds and packages dist/suite/, checks that assets remain under /suite/, and performs a Wrangler dry run. The documentation workflow verifies changes on develop/main and normally publishes production from main through the suite-docs-production environment. A documentation release owns only docs.sabrobotix.com/suite/*; the Harlock namespace has its own release.
Release documentation through its approved workflow. When develop contains unrelated application work, do not promote that application work as a side effect of publishing documentation. After publication, run the shared-portal smoke check and open the changed pages. The build and local role checks do not prove that the public deployment succeeded.
Publish documentation from develop without an application release
For an explicitly authorized documentation-only publication, run Documentation → Run workflow, select develop, and set publish_docs to true. From the CLI, use:
gh workflow run docs.yml --ref develop -f publish_docs=true
The workflow still requires verification before deployment and uses the same production environment and shared-portal smoke check. Its condition refuses automatic develop deployments and manual publication from arbitrary branches. The environment's deployment-branch policy must also permit develop: an authorized administrator can grant a temporary branch exception for the publication and remove that exception after the deploy job completes. Do not replace the protected environment or move its credentials into an unprotected job.
This publishes only documentation. It does not merge main, create an application release, or deploy the Suite server. When the guide describes development features not yet in production, state that edition on the introduction page and review it when the application catches up.
Check the source branch and the public deployment separately. A successful push-triggered Documentation run on develop skips deployment. Publication evidence requires the deploy job to have completed successfully, whether from main or an explicitly requested manual develop run. A reviewed local branch or commit is not authorization to push, merge, or publish it.