[reyreavman]

Summary

Adds a step-by-step guide to the sign directive of stapel images, which was documented only as a reference section in the stapel imports page. The guide covers the whole setup a user has to work out: what to prepare in Vault, how to declare and verify signed files, how the key and the certificate reach CI, which commands need which of them, key rotation, moving signing out of a build stage, and troubleshooting.

What

• New page usage/build/signing_files.html in EN and RU, listed in both documentation sidebars after "SBOM roles and workflow".
• The guide states the Vault policy the signing role needs: update on <mount>/sign/<key>/sha2-256 and read on <mount>/keys/<key>, because werf matches the transit public key against the certificate.
• The guide states that a local key file must be the encrypted delivery-kit PEM (ENCRYPTED DELIVERY-KIT PRIVATE KEY, empty passphrase) and that a plain OpenSSL key fails with decrypt: ..., with a cosign-based conversion. VERIFIED: a werf build with a plain PKCS#8 key failed with decrypt: invalid character ...; the same key converted with cosign import-key-pair and the header rename built the signFiles stage.
• The guide states that a build passing a key logs in to Vault and reads the public key at startup even when the sign stage is cached, so jobs that only use built images should pass the certificate alone.
• The troubleshooting table quotes the error texts the code emits for a missing certificate or key, a missing or non-regular file, a mismatched or non-RSA certificate, a bad signature, partial Vault auth options and invalid sign lists.
• werf.yaml reference: sign.before/sign.after are described as optional, signing at the end of the image when neither is set.
• Stapel imports reference: links to the guide; the Vault auth paragraph now says the JWT, role and mount do not fall back to the authentication --sign-key uses, instead of "to the environment" — they do read their own WERF_SIGN_BUILD_FILE_VAULT_AUTH_* variables.
• Examples use neutral hosts and names only.

[reyreavman]

Verification

• Every factual claim of the EN guide was checked against the code by an independent reviewer (stage placement and visibility, Vault endpoints, commands registering the flags, error strings, digest inputs, Vault option fallback, EN/RU parity); its three findings — key file encoding, Vault login on cached builds, the JWT env wording — are fixed in this PR.
• Hand-run on macOS/Docker: the sign example without before/after builds a signFiles stage with a cosign-converted RSA key; a plain OpenSSL key fails at signer creation.
• Not run: task doc:check-broken-links locally — the jekyll/builder:4.2.0 image is amd64-only and does not run on the arm64 development host; the docs_check_links CI job covers it.