Context

gro is currently read-only by design. This issue adds non-destructive organizational operations for Gmail — things humans do routinely without agonizing: labeling, archiving, starring, marking read, categorizing. This is the foundation PR that establishes shared infrastructure reused by Calendar, Drive, and Contacts in follow-up issues.

The name gro/google-readonly stays; docs get repositioned as "read-only + non-destructive organization."

Shared Infrastructure (built here, reused later)

A. internal/bulk/ package (new)

Shared ID resolution for 3 bulk input modes. All organizational commands across all domains will reuse this.

internal/bulk/resolve.go:

type Config struct {
    Args  []string // positional args
    Stdin bool     // --stdin flag
    Query string   // --query value
}

// ResolveIDs returns IDs from exactly one input source.
// queryFn is called when Query is set; caller provides domain-specific search.
// Returns error if zero or multiple sources provided.
func ResolveIDs(cfg Config, queryFn func(string) ([]string, error)) ([]string, error)

• --stdin, --query, and positional args are mutually exclusive (enforced by ResolveIDs)
• Stdin reading: bufio.Scanner, trim whitespace, skip empty lines
• resolve_test.go covers all three modes plus mutual-exclusion errors

internal/bulk/result.go:

type Result struct {
    Action  string   `json:"action"`
    IDs     []string `json:"ids"`
    Count   int      `json:"count"`
    DryRun  bool     `json:"dryRun"`
    Details any      `json:"details,omitempty"`
}

Text output: "Archived 5 message(s)." or "[dry-run] Would archive 5 message(s)."

B. Scope migration detection

Store granted scopes in config.json at auth time. On client construction, compare stored scopes against auth.AllScopes. If insufficient, return a clear error before making API calls:

This command requires additional permissions (gmail.modify).
Your current token only has read-only access.

Run 'gro init' to re-authenticate with the updated scopes.

New scope: Gmail Modify — allows labeling, archiving, starring, and
marking messages as read/unread. No send or delete access is granted.

Files:

• internal/config/config.go — add GrantedScopes []string to Config struct
• internal/auth/auth.go — add CheckScopesMigration() that compares AllScopes vs config's GrantedScopes; add ScopeDescriptions map for human-friendly explanations
• internal/cmd/initcmd/init.go — after successful token exchange, save granted scopes to config; show scope explanation when re-auth needed

C. Architecture test evolution

internal/architecture/architecture_test.go:

1. Rename TestAllScopesAreReadOnly → TestAllScopesAreNonDestructive — switch from "contains readonly" check to an allowlist:

   var allowedScopes = map[string]bool{
       gmail.GmailReadonlyScope:        true,
       gmail.GmailModifyScope:          true,  // label, archive, star, read/unread (NOT send/delete)
       calendar.CalendarReadonlyScope:  true,
       calendar.CalendarEventsScope:    true,  // RSVP, color (NOT delete)
       people.ContactsReadonlyScope:    true,
       people.ContactsScope:            true,  // group membership
       drive.DriveReadonlyScope:        true,
       drive.DriveMetadataScope:        true,  // star (metadata only, NOT content write)
   }

2. Rename TestNoWriteAPIMethodsInProductionCode → TestNoDestructiveAPIMethodsInProductionCode — update forbidden patterns:

   • Keep forbidden: .Send(, .Trash(, .Untrash(, .BatchDelete(
   • Remove from forbidden: .BatchModify( (needed for bulk label operations)

D. Documentation updates

• docs/golden-principles.md — Principle 5: "Read-only only" → "Non-destructive only"
• CLAUDE.md — update project description and key constraints
• README.md — add organizational operations section with bulk workflow examples
• integration-tests.md — add Gmail organizational test scenarios

Scope Change

internal/auth/auth.go: Replace gmail.GmailReadonlyScope with gmail.GmailModifyScope (superset — includes all read access plus modify).

New API Client Methods

internal/gmail/client.go:

// GetLabelID resolves a label display name to its ID. Calls FetchLabels if needed.
func (c *Client) GetLabelID(ctx context.Context, name string) (string, error)

// ModifyMessages modifies labels on one or more messages.
// For single messages uses Messages.Modify; for multiple uses Messages.BatchModify.
func (c *Client) ModifyMessages(ctx context.Context, ids []string, addLabels, removeLabels []string) error

// SearchMessageIDs returns only message IDs (no metadata fetch). Efficient for piping/bulk.
func (c *Client) SearchMessageIDs(ctx context.Context, query string, maxResults int64) ([]string, error)

ModifyMessages uses Messages.Modify() for single IDs and Messages.BatchModify() for multiple. Gmail limits batch to 1000 IDs — implement chunking.

GetLabelID adds a reverse lookup to the existing label cache. Add a labelsByName map[string]string field to Client, populated alongside labels in FetchLabels.

New Interface Methods

internal/cmd/mail/output.go — add to MailClient:

GetLabelID(ctx context.Context, name string) (string, error)
ModifyMessages(ctx context.Context, ids []string, addLabels, removeLabels []string) error
SearchMessageIDs(ctx context.Context, query string, maxResults int64) ([]string, error)

New Commands

All commands support: --json/-j, --dry-run/-n, --stdin, --query. All accept variadic message IDs as positional args.

Categories: personal, social, promotions, updates, forums → mapped to CATEGORY_PERSONAL, etc.

--ids Flag on Search

internal/cmd/mail/search.go — add --ids flag. Outputs bare message IDs (one per line). Mutually exclusive with --json. Uses SearchMessageIDs (efficient — no metadata fetch).

Bulk workflow examples:

# Direct IDs
gro mail archive msg123 msg456

# Piped from search (preview first, then act)
gro mail search "from:newsletter older_than:7d" --ids | gro mail archive --stdin

# Inline query (one-liner)
gro mail archive --query "from:noreply older_than:30d"

# Dry run to preview
gro mail label "Work" --query "from:boss is:unread" --dry-run

New Files

Files to Modify

Integration Tests

Archive

Star / Unstar

Mark Read / Unread

Label / Unlabel

Categorize

Piping Workflow

Scope Migration

Key Risks

• Gmail BatchModify 1000-ID limit — must implement chunking in ModifyMessages
• Label name resolution — GetLabelID needs reverse lookup; add labelsByName map populated in FetchLabels
• Category labels — when recategorizing, must remove existing CATEGORY_* labels and add the new one