feat: extend pass vault guide for secrets

[aadam-shopware]

This pull request adds comprehensive documentation to the secrets-vault-guide.md for Shopware PaaS, clarifying the distinction between system-managed and user-managed secrets, safe handling practices, and maintenance guidelines. It introduces best practices for secret management, details on permissions, and steps for recovery and support, helping users avoid common pitfalls and platform outages.

Secret Management & Ownership:

• Added detailed explanations distinguishing system-managed secrets (critical for platform operation and not user-editable) from user-managed secrets, with a reference table describing common secrets, their purpose, and editability.
• Included clear warnings and best practices to prevent deletion or modification of system-managed secrets, outlining the consequences and escalation steps if issues arise.

Secret Maintenance & Cleanup:

• Provided a recommended process for auditing, backing up, and deleting unused or legacy secrets, including how to handle typo or deprecated secrets.
• Added instructions for filtering secrets by application and maintaining documentation of secret ownership and usage.

Safety, Recovery & Support:

• Outlined safety measures such as regular backups, credential rotation, and limiting access, along with step-by-step guidance for recovering from accidental deletions.
• Documented the escalation process for unresolved issues, including what

[shyim]

why can the user see them and delete them if they are system managed. we should just have here an list of environment variables which cannot be set because we set them 🤔

[Copilot]

Pull request overview

Extends the Shopware PaaS Vault guide with additional documentation around secret ownership (system-managed vs user-managed), safe maintenance/cleanup practices, and recovery/support guidance.

Changes:

• Added a “Default Secrets & Ownership” section including a reference table and guidance on identifying system-managed secrets.
• Added operational guidance for permissions/behavior, housekeeping of legacy/typo secrets, and recovery/escalation steps.
• Updated the spelling wordlist to include “NATS”.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
products/paas/shopware/guides/secrets-vault-guide.md	Adds extended documentation for secret ownership, maintenance, safety, and recovery.
.wordlist.txt	Adds “NATS” to the repository wordlist.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

::: warning Important uses a title-style admonition syntax that isn't used elsewhere in this docs repo (other pages consistently use ::: warning / ::: info without an inline title, e.g. products/paas/shopware/fundamentals/secrets.md:49). This may render incorrectly or break the docs build depending on the markdown plugin. Use the same admonition syntax as the rest of the docs (e.g. ::: warning and move “Important” into the body text).

Suggested change

	::: warning Important
	Shopware PaaS does not maintain version history for secrets. Once a secret is modified or deleted, the previous value cannot be recovered through the platform.
	::: warning
	**Important:** Shopware PaaS does not maintain version history for secrets. Once a secret is modified or deleted, the previous value cannot be recovered through the platform.

[Copilot]

This section states that sw-paas vault list shows secrets "across all applications" and suggests filtering with --application-id. However, the existing Shopware PaaS docs describe Vault secrets as organization-global and reusable across applications (products/paas/shopware/fundamentals/secrets.md:11–12), which conflicts with the idea of per-application filtering. Please align the wording with the actual Vault scope/CLI behavior (either clarify what “application” means here or remove/adjust the --application-id filtering guidance if secrets aren’t app-scoped).

Suggested change

	### Filtering Secrets by Application
	By default, `sw-paas vault list` shows secrets across all applications in your organization, which can lead to duplicate entries if multiple apps use the same secret names.
	To view secrets for a specific application:
	```sh
	sw-paas vault list --application-id YOUR-APP-ID
	```
	To find your application ID:
	```sh
	sw-paas application list
	```
	### Understanding Organization-wide Secrets
	The `sw-paas vault list` command shows all secrets stored in your organization’s Vault. Because secrets are organization-global and reusable, the same secret values can be referenced by multiple applications using the same secret name.
	If multiple applications in your organization use a secret with the same name, they are all referring to the same underlying Vault secret, not separate per-application copies.
	This means you manage each secret once at the organization level, and then reference it from the applications that need it.

[Copilot]

The doc describes system-managed secrets as "read-only" (implying the platform prevents edits/deletes) but also warns that deleting them will cause outages. This is internally inconsistent. Please clarify whether deletion/editing is technically blocked by the platform/CLI, or whether it’s possible but forbidden/unsupported (and adjust wording accordingly).

Suggested change

	System-managed secrets are read-only and should not be modified or deleted. They are essential for:
	System-managed secrets must be treated as read-only and must not be modified or deleted via the CLI, UI, or API. The platform does not technically prevent you from changing or removing these secrets, but doing so is unsupported and will break critical platform functionality. They are essential for: