Docs: add a troubleshooting section for common first-run failures

[iampopye]

The gap

When someone adopts these workflows and the first run fails, there is nowhere to look. Every failure below is predictable and has a known cause.

What to add

A ## Troubleshooting section in README.md (or a docs/troubleshooting.md linked from it) covering at least:

Symptom	Likely cause
Resource not accessible by integration	The calling workflow did not grant a permission the reusable workflow needs. Every example in examples/ shows the required permissions: block.
CodeQL fails immediately	The language input does not match the repo, or the language is unsupported. Set run_codeql: false for unsupported languages.
Gitleaks fails on an organisation repo	gitleaks-action may require a GITLEAKS_LICENSE for orgs. Free for personal accounts and public repos.
Kubernetes job fails at kubeconfig decode	The secret is not base64. Store it with base64 -w0 < ~/.kube/config.
Docker scan fails with an image not found	Multi-arch build with push: false is never loaded locally. Push it, build a single platform, or set scan_image: false.
Terraform apply never runs	apply defaults to false by design. Set it explicitly.
AI workflow errors on an unknown provider	provider must be one of the eight supported values, and model is required with no default.

Why this is a good first contribution

You do not need to write any YAML. If you hit one of these yourself while trying the workflows, you are exactly the right person to write the entry — you will remember what was actually confusing.

Adding a symptom that is not on the list is very welcome.