docs: update flow + diagrams + developer guide

[kalvinparker]

Adds detailed documentation for Watchtower's update flow and developer guide.

Summary

This PR adds developer-focused documentation that describes the end-to-end update flow, the function-level call chain, and the full data-shape mappings used by Watchtower. It also includes diagrams (PlantUML source + rendered SVG) and a small developer guide with commands to run tests and render diagrams locally.

Files added

• docs/update-flow.md — high-level flow, mermaid sequence diagram, security notes.
• docs/update-flow-detailed.md — function-level call chain, file references, and full data-shape listings for maintainers.
• docs/diagrams/update-flow.puml — PlantUML source for sequence diagram.
• docs/assets/images/update-flow.svg — rendered SVG diagram (from PlantUML).
• docs/developer-guide.md — local developer guide: go test, containerized -race steps, and PlantUML render instructions.

Why

• Provides a single authoritative reference for how internal/actions.Update orchestrates container discovery, digest checking, token auth and restart/cleanup flows.
• Helps new contributors and maintainers reason about changes to registry auth, token caching, and lifecycle hooks.
• Improves documentation for secure registry TLS configuration (--registry-ca, --registry-ca-validate) and developer testing steps.

Testing / Verification

These are docs-only additions. To validate locally:

1. Render PlantUML to SVG (optional):

docker run --rm -v "${PWD}:/work" -w /work plantuml/plantuml -tsvg docs/diagrams/update-flow.puml

2. Confirm the SVG exists and view it:

ls docs\assets\images\update-flow.svg
Start-Process docs\assets\images\update-flow.svg

3. (Optional) Build docs site locally with MkDocs:

pip install -r docs-requirements.txt
mkdocs build -f mkdocs.yml
mkdocs serve -f mkdocs.yml

Checklist

• Confirm the generated SVG renders correctly in the built site.
• Run mkdocs build or mkdocs serve and inspect the new pages under docs/.
• Assign reviewer(s) to validate accuracy of the flow and call-chain.
• Merge after approvals.

Suggested reviewers / labels

• Suggested reviewers: maintainers and contributors familiar with registry/auth (e.g. @containrrr/maintainers).
• Suggested labels: documentation, docs.

Notes

• These changes are documentation only and should not change runtime behavior.
• If you'd like me to open the PR, run the push commands and gh pr create steps previously provided. If you prefer, I can also generate a git patch file for manual application.

[github-actions]

Congratulations on opening your first pull request! We'll get back to you as soon as possible. In the meantime, please make sure you've updated the documentation to reflect your changes and have added test automation as needed. Thanks! 🙏🏼