feat: Add fine-grained permissions support and tool permissions docs (Phase 2)

[SamMorrowDrums]

Summary

This PR adds fine-grained permission types to the scopes package and creates comprehensive tool permissions documentation.

Changes

Extended pkg/scopes/scopes.go

Added support for fine-grained personal access token permissions:

New Types:

• Permission - Fine-grained permission constants (e.g., PermActions, PermContents, PermIssues, PermPullRequests)
• PermissionLevel - Access levels (PermissionRead, PermissionWrite, PermissionAdmin)
• FineGrainedPermission - Struct combining permission and level

New Functions:

• WithScopesAndPermissions() - Create Meta with both OAuth scopes and fine-grained permissions
• AddPermissions() - Add permissions to existing Meta map
• GetPermissionsFromMeta() - Extract permissions from tool Meta
• ReadPerm(), WritePerm(), AdminPerm() - Convenience constructors
• Perm() - General permission constructor

New docs/tool-permissions.md

Comprehensive documentation covering:

• OAuth Scope Hierarchy - Shows which scopes include others
• Fine-Grained Permission Levels - Explains read/write/admin levels
• Tools by Category - Tables mapping each tool to required:
  • OAuth scope (for classic PATs)
  • Fine-grained permission (for fine-grained PATs)
• Minimum Required Scopes - Quick reference by use case
• Notes - Metadata permissions, notification limitations, etc.

Categories documented:

• Repository Tools (19 tools)
• Issue Tools (9 tools)
• Pull Request Tools (18 tools)
• Git Tools (2 tools)
• Actions Tools (14 tools)
• Label Tools (3 tools)
• Notification Tools (6 tools)
• Discussion Tools (4 tools)
• Project Tools (9 tools)
• Gist Tools (4 tools)
• Search Tools (4 tools)
• Security Tools (10 tools)
• Context Tools (3 tools)

Updated README.md

Added links to the new permissions documentation:

• In Prerequisites section (for PAT creation guidance)
• Before Tools section (callout note)

Testing

• All existing tests pass
• Added comprehensive tests for new fine-grained permission functions:
  • TestFineGrainedPermissionString
  • TestWithScopesAndPermissions
  • TestAddPermissions
  • TestAddPermissionsToNilMeta
  • TestGetPermissionsFromMeta
  • TestPermHelperFunctions

Part of OAuth Scopes Work (Phase 2 of 4)

• Phase 1 (PR #1485): Add OAuth scopes to tool metadata ✅
• Phase 2 (this PR): Add fine-grained permissions and documentation ✅
• Phase 3: Create script to list required scopes for enabled tools
• Phase 4: Export Go map for library usage