docs: tips for agents on running integration tests

[theosanderson]

This is just used by my claude - it's the way it found to manage to get integration tests to work locally. With this addition it consistently manages to use the integration tests to test local changes (I'm running it on a linux box).

🚀 Preview: Add preview label to enable

[claude]

Claude finished @theosanderson's task in 1m 7s —— View job

---

Code Review Complete ✓

Todo List

• Read the modified AGENTS.md file
• Review the git diff to see exact changes
• Analyze documentation quality and clarity
• Provide comprehensive review feedback

Summary

This PR significantly improves the integration test documentation by solving a critical networking issue with k3d local testing. The changes replace the problematic --use-localhost-ip approach with host.k3d.internal, which properly handles the dual-access requirements for services like MinIO.

Strengths:

• Solves a real problem: The host.k3d.internal approach elegantly handles the challenge of services generating URLs that need to work from both browser and pod contexts
• Clear explanation: The "Why host.k3d.internal?" callout effectively explains the rationale and contrasts it with the old approach
• Comprehensive troubleshooting: The new troubleshooting section anticipates common failure modes and provides actionable debugging steps
• Good structure: Instructions flow logically and are easy to follow

Minor improvements suggested (see inline comments):

• The hardcoded --branch main could be clarified or made dynamic
• The /etc/hosts append command could benefit from duplicate prevention
• Cleanup instructions for /etc/hosts modification would be helpful

Overall, this is a valuable addition that will help developers (and AI agents!) successfully run integration tests locally. The documentation quality is high and the technical approach is sound.

[claude]

The --sha flag is computed from the current HEAD, but the --branch main is hardcoded. This could be confusing when testing local changes on a different branch. Consider either:

1. Making the branch dynamic: --branch $(git branch --show-current)
2. Adding a comment explaining why main is always used here, even when on a feature branch

[claude]

Using tee -a (append mode) could result in duplicate entries if this command is run multiple times. Consider either:

1. Using a one-liner that checks first: grep -q 'host.k3d.internal' /etc/hosts || echo '127.0.0.1 host.k3d.internal' | sudo tee -a /etc/hosts
2. Adding a note to warn users about running this multiple times
3. Updating the troubleshooting section to mention checking for duplicates