Package mapping doc

[SharpRake]

Type of change

Documentation improvement

This PR adds comprehensive internal documentation for the package mappings documentation system and makes minor content improvements to the user-facing documentation.

What should this PR do?

resolves https://github.com/chainguard-dev/internal/issues/5417

Why are we making this change?

The package mappings documentation feature is a complex system involving Hugo shortcodes, auto-updating data from the dfc repository, and Bootstrap 5 collapsible tables. This change creates a detailed README (README-PACKAGE-MAPPINGS.md) to preserve context about:

• Implementation decisions and design constraints (especially AEO/LLM optimization)
• How the automatic update system works
• Technical gotchas (Bootstrap 5 syntax, Hugo data access patterns)
• Local development setup
• Troubleshooting guidance

This documentation ensures future maintainers (both human and AI assistants) can understand and extend the system without rediscovering solutions to already-solved problems.

What are the acceptance criteria?

• README-PACKAGE-MAPPINGS.md provides complete context about the implementation
• Documents all key decisions made during development (Option 2 choice, auto-updates, section ordering, Bootstrap collapse approach)
• Includes technical details about Bootstrap 5 syntax requirements and Hugo data access patterns
• Provides clear troubleshooting steps for common issues

How should this PR be tested?

1. Read through the README: Review README-PACKAGE-MAPPINGS.md to ensure it comprehensively documents the system
2. Verify documentation accuracy: Check that technical details match the actual implementation in /layouts/shortcodes/package-mappings/ and workflow files
3. Local development test (optional): Follow the README's "Local Development" section to ensure instructions work correctly
4. Ensure automation functions as expected

preview link

[netlify]

✅ Deploy Preview for ornate-narwhal-088216 ready!

Name	Link
🔨 Latest commit	4d4ef81
🔍 Latest deploy log	https://app.netlify.com/projects/ornate-narwhal-088216/deploys/690cce12b62d3f0008c06ddd
😎 Deploy Preview	https://deploy-preview-2714--ornate-narwhal-088216.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.