[bacluc-agent]

Summary

Documentation-only change (bacluc-agent/agent-vshn-todo#80):

• Rewrite docs/modules/ROOT/pages/index.adoc: overview of per-namespace opt-in PVC backups via k8up + espejote backed by AppCat ObjectBucket → S3, what the component creates (Argo CD Application with ServerSideApply=true, ServiceAccount/RBAC, espejote ManagedResource rendering ObjectBucket + k8up Schedule per opted-in namespace), prerequisites, and links.
• New how-to docs/modules/ROOT/pages/how-tos/enable-backups.adoc: both required namespace labels (opt-in + encryption-secret label naming the Secret with the restic password under key password), kubectl label / kubectl create secret examples, verification steps, teardown behaviour.
• New how-to docs/modules/ROOT/pages/how-tos/customize-backups.adoc: schedule/retention overrides, s3.endpoint with %(region)s, bucket name prefix, namespace settings, all as inventory fragments under parameters: solution_backup:.
• New explanation docs/modules/ROOT/pages/explanations/how-it-works.adoc: reconciliation model (watchContextResource trigger vs backup_namespaces context), wantsBackup guard, slug computation, naming table, endpoint resolution, teardown, and a Multiple component instances section.
• Rewrite of docs/modules/ROOT/pages/references/parameters.adoc in the established style (per-key type::/default::, prose, example block). Corrects the stale namespace default (syn-solution-backup → ${_instance}).
• docs/modules/ROOT/partials/nav.adoc: how-tos and explanation entries added, index + Parameters kept, tutorials empty.

Facts are taken from class/defaults.yml, class/solution-backup.yml, component/main.jsonnet, and the render test inputs/goldens.

Update 2026-11-05 (branch merged with master)

• Merged upstream master into this branch (merge commit ba38516), picking up upstream PR class: fix multi instance behaviour #7 class: fix multi instance behaviour (merged 2026-11-04): main.jsonnet now compiles to output_path: ${_instance} in class/solution-backup.yml, so compile output lands per instance instead of a shared solution-backup/ directory. The docs now document the multi-instance behaviour: _metadata.multi_instance: true, solution-backup as <instance> declaration, per-instance namespace default ${_instance}, instance slug (first 8 hex chars of SHA-256 of the instance name) in pvc-backup-<instanceSlug> resource names / backup-bucket-creds-<instanceSlug> / bucket names, and per-instance Argo CD Applications.
• Corrected the teardown description in explanations/how-it-works.adoc and how-tos/enable-backups.adoc: espejote (version pinned to 0.22.0 in CI) does not prune objects that drop out of the render — removing the namespace labels stops rendering only; the ObjectBucket and k8up Schedule must be deleted manually, or get garbage-collected with the namespace by Kubernetes.
• references/parameters.adoc: documented that s3.region is also set as the region on each AppCat ObjectBucket, that objectbucket.name_prefix only affects the S3 bucket name (resource names keep the fixed pvc-backup- prefix), that the whole schedule.retention map passes through verbatim into spec.prune.retention (other k8up retention keys allowed), and that all defaults live in class/defaults.yml with the compile layout in class/solution-backup.yml.
• No example inventory YAML exists in index.adoc; the valid parameters: solution_backup: example lives in references/parameters.adoc (verified key-by-key against class/defaults.yml), so the index cross-references it rather than duplicating it.

Notes

• Pushed directly to issue-80-document-usage was blocked: the bacluc-agent token has pull-only access to this third-party repo (Permission denied … 403). Fall back to forking per standard outsider flow: branch lives in the bacluc-agent/component-solution-backup fork.
• Only files under docs/ were changed (verified: git diff upstream/master...HEAD --name-only lists exactly the 6 docs files).

Test evidence

Local verification (run against head b37d800):

• make lint_adoc → ✔ 0 errors, 0 warnings and 0 suggestions in 0 files. (repo .vale.ini defines no styles, so vale scans 0 files by design)
• make golden-diff and make golden-diff-all → exit 0 for defaults, override-schedules, override-labels; no rendered-output drift
• Independent espejote render rerun: bash tests/render/run.sh (espejote 0.22.0 as pinned by .github/workflows/espejote.yaml) → exit 0, 6 scenarios, git status --porcelain tests/render/expected/ clean
• make docs-serve → Antora site built; all 5 pages HTTP 200; scripted link check over the built HTML found 126/126 internal links and anchors resolving, nav lists all 5 pages, no unresolved xrefs; content spot-checks (dict types, ${_instance} defaults, teardown wording) rendered correctly.

CI evidence:

• Fork CI on issue-80-document-usage @ b37d800: Espejote render workflow run 42123881500 — job success, in particular the "Render and diff expected files" step (step 4) succeeded.
• Upstream CI runs on this PR for head b37d800 are action_required (fork-PR workflows await maintainer approval, so their status does not yet say "passed"): Pull Request, Espejote render, Autorelease.