docs(service): add ConnectivityProber guide for provider authors

[alexgarzao]

Summary

• New docs/connectivity-prober-guide.md — contributor-facing guide for the executor.ConnectivityProber interface introduced in feat(service): provider-aware connectivity test with Midaz OIDC probe #23.
• One-line pointer added to CLAUDE.md under the Provider/Executor section so agents and humans land on the guide before adding new providers.

Why

After three iterations (#23 Midaz, #25 Tracer, S3 deferred via #26), the pattern is stable enough to document. Without a written guide, the next provider author has to reverse-engineer two existing implementations to figure out what's required, what's reusable, and what's an anti-pattern.

Scope

• Strictly documentation. No code changes.
• Stacked on feature/connectivity-prober-tracer so the guide can reference the Tracer implementation as the simplest reference (single base URL, header auth).

What the guide covers

1. When to implement — concrete criteria (multiple base URLs, non-trivial auth, root doesn't return 2xx, need to validate specific configured resource).
2. The interface — annotated ConnectivityProber and ProbeOutcome definitions.
3. Stage mapping table — full ProbeOutcome → (Connectivity, Authentication, End-to-End) decision matrix, including the deliberate partial overall status for "reached but creds wrong".
4. Implementation steps — wrap the provider, add connectivity_prober.go, pick the probe endpoint, write tests at all three layers.
5. Reusable utilities — libSSRF.ResolveAndValidate, pkg/executors/http/auth.NewFromConfig, the (forthcoming) pkg/ssrfopt.Options() shared helper.
6. Existing implementations table — Midaz + Tracer with endpoints and auth styles.
7. Anti-patterns — calling /health for the probe, side effects, panicking, skipping SSRF, lying about AuthRequired().

Note on the pkg/ssrfopt reference

The guide references pkg/ssrfopt.Options() as the canonical way to source SSRF options. That package is being introduced in a parallel refactor PR. If that PR doesn't land first, the reference in this guide will be aspirational for a brief window — acceptable trade-off since the guide is forward-looking and both PRs share the same parent branch.

Test plan

• markdownlint clean (no linter in this repo; manual review for structure/voice).
• Manual review of the rendered Markdown on GitHub before merge.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• develop

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8a2dc523-c285-4b8b-bdbe-9544f8e68f9a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}