surfer: Improve error handling and reporting strategy

[quirogas]

The current error handling strategy in the generator often halts execution with technical error messages that may be hard for contributors to understand or act upon. We need a more robust approach that distinguishes between critical errors and skippable issues.

Context & Rationale

• Contributor Experience: Error messages should guide the user to the root cause (e.g., missing annotation, invalid configuration) rather than just reporting an internal failure.
• Resilience: In some cases, it may be preferable to skip a problematic field or method and continue generating the rest of the surface, logging a warning instead of crashing.
• Reviewer Feedback: "Our error messages are hard to follow for contributors. We want to think about when we error out and when we skip over."

Implementation Considerations

• Define a policy for "Error vs. Warn".
• Enhance error wrapping to include context (Method name, Field name, expected state).
• Consider integrating with a structured logging interface or a diagnostic report system.

Proposed Solution

• Audit all return err paths in builder.go and generate.go.
• Replace technical errors with actionable messages where possible.
• Implement "soft failure" mechanisms for non-critical components.

Relevant files

• internal/surfer/gcloud/builder.go
• internal/surfer/gcloud/generate.go