docs: require workspace installation manuals

2026-08-03 20:57:53 +02:00
parent fef7a7614e
commit a6e6bc6800
1 changed files with 6 additions and 1 deletions
@@ -534,7 +534,10 @@ Migration never copies secret values into Git. Existing absolute roots become in
 - Workspace schema reference with field descriptions and examples.
 - Generated documentation for every workspace.
 - Generated `.env.example` for every workspace.
- Docker Compose examples for server and local installations.
+- A detailed local-installation manual for Docker Desktop on macOS and for a local Docker engine on PC. It must cover prerequisites, clone/checkout or remote bootstrap, local Git credentials, persistent volumes, installation bindings, secret files, Docker Compose startup, first pull, workspace diagnostics, local publish, update, backup, and rollback.
+- A detailed server-installation manual. It must cover service account and filesystem ownership, persistent registry volume, remote Git and Gitea configuration, HTTPS/SSH Git credentials, CA and known-hosts mounts, secret-file layout and permissions, Compose deployment, first bootstrap, firewall and outbound Git requirements, same-origin reverse-proxy exposure, health/status verification, pull/publish operations, upgrade, backup, degraded-mode recovery, and rollback to a prior validated snapshot.
+- The two manuals must distinguish values that are shared in Git from installation-local bindings and secret files. Both must include complete direct PostgreSQL, REST, and SSH-tunnel examples and a troubleshooting table keyed by the stable diagnostic error codes.
+- Docker Compose examples for server and local installations, referenced by the corresponding manual and tested as runnable examples.
 - Direct PostgreSQL, REST, and SSH-tunnel examples.
 - Vector/embedding compatibility explanation.
 - Git remote setup for HTTPS and SSH.
@@ -557,6 +560,7 @@ Migration never copies secret values into Git. Existing absolute roots become in
 - End-to-end tests using a local Git remote and simulated connectors.
 - Deployment tests proving persistent checkout and last-valid-snapshot fallback across container replacement.
 - Session tests proving revision pinning and resume after a newer workspace publish.
+- Documentation verification that executes the manual's local and server Compose examples in isolated test fixtures, including initial bootstrap and recovery from an unavailable Git remote.

 ## 21. Acceptance criteria

@@ -571,4 +575,5 @@ The feature is complete when:
 - vector collection and embedding compatibility is enforced;
 - a remote outage leaves the last valid snapshot usable;
 - every new session records and resumes with an immutable workspace revision;
+- detailed, tested installation manuals exist for local PC/Mac Docker deployments and for server deployments;
 - existing PSD configuration can be migrated without embedding PSD-specific behavior in the core schema.