Refactor secrets inventory into docs + machine-readable JSON

docs/deployment-prerequisites.md

@@ -0,0 +1,49 @@
+# Deployment Prerequisites
+
+Before running compose operations, provision local secret material.
+
+## 1) Create non-committed secret env file
+
+```bash
+cp secrets/.env.secrets.example secrets/stack-secrets.env
+chmod 600 secrets/stack-secrets.env
+```
+
+## 2) Create required Docker secret files
+
+All files below are expected locally and are gitignored:
+
+- `secrets/nextcloud_db_root_password.txt`
+- `secrets/nextcloud_db_password.txt`
+- `secrets/nextcloud_admin_password.txt`
+- `secrets/nextcloud_smtp_password.txt`
+- `secrets/nextcloud_redis_password.txt`
+- `secrets/passbolt_db_password.txt`
+- `secrets/influxdb_init_password.txt`
+- `secrets/prometheus_kuma_basic_auth_password.txt`
+
+Recommended permissions:
+
+```bash
+chmod 600 secrets/*.txt
+```
+
+## 3) Validate composed configuration
+
+Use the repository composition entrypoint:
+
+```bash
+./services-up.sh --profile all config
+```
+
+This confirms compose rendering with shared env/network inputs before any runtime operation.
+
+## 4) Rotate previously committed credentials
+
+If migrating from older states where secrets were committed, rotate upstream values immediately (DB credentials, app passwords, auth keys, and API tokens).
+
+## Related docs
+
+- [`./security-secrets.md`](./security-secrets.md)
+- [`./docker-environment.md`](./docker-environment.md)
+- [`./source-of-truth.md`](./source-of-truth.md)

docs/docker-environment.md

@@ -46,7 +46,7 @@ Use this when focused on one service family.
 
 ### Deployment prerequisites
 
-Before runtime operations, follow [DEPLOYMENT.md](../DEPLOYMENT.md) to create required local secret files.
+Before runtime operations, follow [deployment-prerequisites.md](deployment-prerequisites.md) to create required local secret files.
 
 ## What not to do
 

docs/repo-structure.md

@@ -17,8 +17,8 @@ This page explains where to find authoritative files quickly.
 - `services-up.sh` — runtime composition entrypoint for multi-compose environment.
 - `default-network.yml` — shared docker network definitions used across compose files.
 - `default-environment.env` — non-secret default env values for compose rendering.
-- `DEPLOYMENT.md` — prerequisite setup before runtime operations.
-- `SECURITY_SECRETS_INVENTORY.md` — tracked secret-variable inventory and usage map.
+- `docs/deployment-prerequisites.md` — prerequisite setup before runtime operations.
+- `docs/security-secrets.md` — secrets documentation and inventory model.
 
 ## Terraform layout
 

docs/security-secrets.md

@@ -0,0 +1,52 @@
+# Security Secrets
+
+## Overview
+
+This page explains how secret material is organized in this repository and where to find both human-readable and machine-readable references.
+
+For machine-readable inventory metadata, use [`../secrets/inventory.json`](../secrets/inventory.json).
+
+## Scope and authority
+
+- Canonical example template: [`../secrets/.env.secrets.example`](../secrets/.env.secrets.example)
+- Runtime-loaded secret env file (local, non-committed): `../secrets/stack-secrets.env`
+- Docker secret files (local, non-committed): `../secrets/*.txt`
+
+Treat the example template as the canonical shape for expected environment variables.
+
+## Secret material types
+
+1. **Template variables in `.env.secrets.example`**
+   - Document expected variable names and usage expectations.
+2. **Local runtime env file (`stack-secrets.env`)**
+   - Holds local runtime secret values loaded during compose rendering.
+3. **Local Docker secret files (`*.txt`)**
+   - Hold password/token material consumed via `*_FILE` style configuration.
+4. **Externally managed secret inputs**
+   - Some values are managed outside shared templates and provided through file mounts or environment substitution.
+
+## Machine-readable inventory
+
+- Primary automation source: [`../secrets/inventory.json`](../secrets/inventory.json)
+- Human guidance source: this page
+
+Automation should parse `secrets/inventory.json` directly rather than scraping Markdown tables.
+
+## Setup and deployment prerequisites
+
+Before running compose operations, follow [`./deployment-prerequisites.md`](./deployment-prerequisites.md).
+
+## Commit safety rules
+
+Never commit:
+
+- `secrets/stack-secrets.env`
+- real `secrets/*.txt` secret files
+- real Terraform `.tfvars` files containing credentials
+- Terraform state files with sensitive runtime metadata
+
+## Related docs
+
+- [`./deployment-prerequisites.md`](./deployment-prerequisites.md)
+- [`./docker-environment.md`](./docker-environment.md)
+- [`./source-of-truth.md`](./source-of-truth.md)

docs/source-of-truth.md

@@ -9,7 +9,7 @@ This repository has multiple layers. Knowing the authority for each layer preven
 | Application/runtime container composition | `services-up.sh` + Compose files under `core/`, `apps/`, `monitoring/` | What runs in the Docker environment and how services are wired. |
 | Docker shared baseline inputs | `default-network.yml`, `default-environment.env`, `secrets/stack-secrets.env` | Shared network/env material applied during compose rendering. |
 | Infrastructure inventory and reconciliation | Terraform under `infrastructure/terraform/` | Codified inventory of existing infrastructure and relationships, especially Proxmox VMs and selected Docker mirrors. |
-| Secret policy and inventory | `SECURITY_SECRETS_INVENTORY.md` + local secret files in `secrets/` | What secrets exist and where they are expected. |
+| Secret policy and inventory | `docs/security-secrets.md` + `secrets/inventory.json` + local secret files in `secrets/` | What secrets exist, where they are expected, and what automation should parse. |
 
 ## Practical meaning