docs: enhance package comment for internal/beads package

[julianknutsen]

Summary

Enhanced the package documentation for internal/beads to provide clearer guidance on package purpose and usage patterns.

Related Issue

Relates to gt-bi7nb

Changes

• Expanded the brief package comment to include:
  • Description of what the beads package wraps (bd CLI)
  • Overview of main operations (listing, creating, updating, syncing)
  • Documentation of main types and constructor functions

Testing

• Unit tests pass (go test ./...)
• Build succeeds (go build ./...)

Checklist

• Code follows project style
• Documentation updated
• No breaking changes

[github-actions]

Code Coverage Report

Overall Coverage: 20.3%

Package	Coverage
cmd/gt	0.0%
internal/activity	100.0%
internal/agent	86.7%
internal/beads	27.2%
internal/boot	0.0%
internal/checkpoint	94.6%
internal/claude	0.0%
internal/cmd	9.6%
internal/config	68.2%
internal/connection	21.5%
internal/constants	0.0%
internal/crew	34.6%
internal/daemon	9.4%
internal/deacon	31.4%
internal/deps	39.6%
internal/dog	0.8%
internal/events	0.0%
internal/feed	67.3%
internal/formula	68.2%
internal/git	29.2%
internal/keepalive	60.7%
internal/lock	84.4%
internal/mail	36.0%
internal/mayor	0.0%
internal/mq	100.0%
internal/opencode	76.9%
internal/plugin	37.9%
internal/polecat	32.8%
internal/protocol	81.4%
internal/refinery	17.4%
internal/rig	41.6%
internal/runtime	82.9%
internal/session	76.6%
internal/shell	61.8%
internal/state	67.6%
internal/style	2.0%
internal/suggest	97.1%
internal/swarm	13.8%
internal/templates	31.0%
internal/tmux	34.6%
internal/townlog	46.9%
internal/tui/convoy	0.0%
internal/tui/feed	0.0%
internal/ui	13.5%
internal/util	47.1%
internal/version	0.0%
internal/web	26.4%
internal/wisp	80.7%
internal/witness	19.1%
internal/workspace	45.8%
internal/wrappers	0.0%

---

Generated by CI