docs: define system administrator lifecycle story

docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md

@@ -0,0 +1,169 @@
+# System Administrator Lifecycle User Story
+
+## Story
+
+> As a system administrator, I can execute one shell command that downloads a
+> verified GovOPlaN distribution and starts a completely configured Core control
+> plane without optional modules. In the WebUI I can browse compatible signed
+> module releases, select the modules for this installation, and follow every
+> download, validation, migration, installation, activation, and health-check
+> step. When an update is available, I can review its impact and confirm it.
+>
+> I can add API or worker replicas on containers or other servers without
+> copying mutable local state. I can operate development, test, and production
+> systems, transfer a versioned configuration through the WebUI, undo an applied
+> configuration version, test an update in one environment, and then apply the
+> same immutable update recipe to another environment.
+
+This is a product-level story owned by the GovOPlaN platform rather than by an
+individual domain module. It joins installation, module lifecycle, operations,
+configuration packages, and release provenance into one administrator journey.
+The canonical backlog item is
+[GovOPlaN #13](https://git.add-ideas.de/add-ideas/govoplan/issues/13).
+
+## Terms
+
+- **Core control plane:** the smallest bootable distribution: Core API, Core
+  WebUI, PostgreSQL, Redis, installer worker, migration runner, and durable
+  storage configuration. No optional GovOPlaN module package is installed.
+- **Bootstrap administrator:** a single-use, time-limited installation identity
+  that may access only first-run and module-lifecycle functions. It is retired
+  when the selected identity/access configuration becomes healthy.
+- **Module release:** an immutable, signed package plus manifest, compatibility
+  contract, migrations, WebUI contribution, checksums, and SBOM references.
+- **Configuration revision:** an immutable, schema-versioned export of
+  non-secret system/module settings, policies, compositions, and secret
+  references. Secret values are never exported.
+- **Update recipe:** the reviewed, immutable plan containing exact Core/module
+  versions, configuration revision, migration order, preflight results,
+  maintenance/drain requirements, health checks, and permitted rollback or
+  forward-recovery actions.
+
+## Acceptance journeys
+
+### One-command first installation
+
+1. The administrator runs one documented command on a supported host.
+2. The bootstrapper verifies a signed distribution manifest before executing or
+   starting downloaded artifacts.
+3. It checks container/runtime, ports, storage, entropy, memory, architecture,
+   and connectivity requirements; generates deployment-local secrets with
+   restrictive permissions; and never prints them.
+4. It starts PostgreSQL, Redis, Core API/WebUI, one installer worker, and the
+   migration runner. Readiness does not pass until migrations and durable
+   dependencies are healthy.
+5. It prints the local URL and one-time bootstrap credential. Re-running the
+   command is idempotent and shows or repairs the existing installation rather
+   than creating another identity or database.
+6. No optional module is installed or enabled at this point.
+
+### Module selection, installation, and update
+
+1. Core reads an approved signed catalog and trusted keyring through the shared
+   outbound-network policy.
+2. The WebUI shows available, installed, compatible, blocked, withdrawn, and
+   update-available releases with their channel, provenance, contracts,
+   migrations, permissions, configuration requirements, and release notes.
+3. Selecting modules produces a dependency/compatibility plan before any
+   mutation. The administrator can amend the selection or confirm the plan.
+4. Installation executes durably in a worker. The UI receives persisted step
+   state and can reconnect without losing progress.
+5. Package signature/checksum, version alignment, contract closure, migration
+   graph, configuration schema, and health checks are mandatory gates.
+6. A failed or interrupted operation reaches a visible retry, forward-recovery,
+   rollback, or manual-intervention state. It never reports success merely
+   because the initiating request returned.
+7. An available update follows the same preview and confirmation path. Exact
+   repeated requests are idempotent.
+
+### Horizontal scaling
+
+1. API, WebUI, installer, scheduler, and ordinary worker roles are stateless
+   with respect to local container disks. Durable state uses PostgreSQL, Redis,
+   and configured shared file/object storage.
+2. A documented command can add API or queue-specific worker replicas. The
+   default Compose profile supports local scale-out; an orchestrator profile
+   supplies equivalent health/readiness probes and rolling replacement.
+3. Only one migration or module-lifecycle mutation may own the deployment lock,
+   while any healthy replica can serve read and normal domain traffic.
+4. Workers announce identity, queues, software composition, heartbeat, and
+   drain state. Operators can see skew and safely retire a replica.
+5. Sessions, throttling, idempotency, jobs, installer progress, and scheduled
+   work remain correct when requests move between replicas.
+
+### Development, test, and production promotion
+
+1. The administrator exports a configuration revision from development through
+   the WebUI. The package is versioned, checksummed, attributable, and contains
+   secret references or required-secret declarations, never secret values.
+2. Test imports the package into a preview area. Core reports environment-bound
+   values, missing capabilities/secrets, compatibility changes, and the exact
+   apply plan.
+3. Applying creates a new revision; the previous effective revision remains
+   addressable. Undo is a new audited revision that restores the earlier
+   configuration where contracts permit it.
+4. After tests and health checks pass, Core emits an update recipe with exact
+   immutable release and configuration identifiers.
+5. Production validates the recipe against its own environment, requires a new
+   confirmation, and executes the same ordered plan. Environment-specific
+   secret bindings and endpoints remain local.
+6. Promotion never copies tenant/business data implicitly. Data migration,
+   anonymized fixtures, and backup/restore are separate explicit operations.
+
+## Safety and governance requirements
+
+- Catalogs, artifacts, recipes, and configuration revisions have signatures,
+  checksums, provenance, expiry/revocation semantics, and audit evidence.
+- The installer has a dedicated narrow authority; normal domain permissions do
+  not imply host/package-management access.
+- The UI distinguishes reversible configuration rollback from database or
+  package migrations that require forward recovery.
+- Cluster-wide mutations use fencing/leases so an expired worker cannot later
+  commit a stale result.
+- Update plans declare availability impact, worker draining, backup/restore
+  prerequisites, database compatibility windows, and post-change probes.
+- Deployment profiles set secure headers, trusted proxies/hosts, body limits,
+  outbound-network policy, storage, TLS/cookie posture, and observability.
+- Release publication requires aligned backend/frontend/manifest versions and
+  machine-readable dependency/SBOM provenance.
+
+## Implementation slices
+
+1. **Reproducible Core-only distribution.** Publish pinned multi-architecture
+   images, signed distribution manifest, Core-only Compose profile, bootstrap
+   preflight, generated secrets, readiness, and idempotent rerun/repair.
+2. **First-run control plane.** Add the restricted bootstrap administrator,
+   one-time enrollment, initial catalog/keyring configuration, and retirement
+   after durable administrator access is established.
+3. **Read-only online module directory.** Move the existing catalog and module
+   directory contracts into the installed Core WebUI with compatibility,
+   provenance, release-note, and update-state presentation.
+4. **Durable module plan and install.** Reuse the existing installer queue,
+   locks, signed-package validator, rollback drill, and run evidence behind a
+   plan/confirm/progress UI. Add initial catalog-entry synthesis and artifact
+   acquisition where the current release console still assumes local sources.
+5. **Safe module update.** Add drain/maintenance coordination, backup gate,
+   migration compatibility window, reconnectable progress, health verification,
+   retry/recovery, and update notification.
+6. **Stateless replica profile.** Remove remaining local-runtime assumptions,
+   expose role-specific commands/images, implement worker registration/drain,
+   and prove multiple API and worker replicas against shared dependencies.
+7. **Configuration revision model.** Define provider export/import schemas,
+   canonical serialization, secret references, validation/diff, immutable
+   revision storage, audit, apply, and undo-as-new-revision.
+8. **Environment promotion and recipes.** Add source/target fingerprints,
+   preview, environment bindings, acceptance evidence, exact recipe generation,
+   signed transfer, and independently confirmed application.
+9. **Operational proof.** Exercise interrupted installs, stale locks, unavailable
+   catalogs, revoked keys, failed migrations, replica loss, configuration undo,
+   and development-to-test-to-production promotion in release CI and target
+   drills.
+
+## Explicit non-goals for the first distribution slice
+
+- Shipping optional modules in the Core image.
+- Exporting secrets or production business data with configuration.
+- Pretending every schema migration can be reversed automatically.
+- Building a proprietary orchestrator instead of supporting Compose and a
+  standard cluster scheduler through the same role/readiness contracts.
+- Allowing the browser process to execute arbitrary shell commands.