📝 docs(lib): add detailed documentation for library features

- add gmail query syntax guide
- provide performance and limits information
- explain logging functionality
- describe security considerations
- include troubleshooting section
- add "see also" links

docs/lib.md

@@ -231,3 +231,105 @@ async fn main() -> cull_gmail::Result<()> {
 }
 ```
 
+## Gmail Query Syntax
+
+The library supports Gmail's search syntax for message queries:
+
+```rust path=null start=null
+// Date-based queries
+client.set_query("older_than:1y");           // Older than 1 year
+client.set_query("newer_than:30d");          // Newer than 30 days
+client.set_query("after:2023/1/1");          // After specific date
+
+// Label-based queries
+client.set_query("label:promotions");        // Has promotions label
+client.set_query("-label:important");        // Does NOT have important label
+
+// Content queries
+client.set_query("subject:newsletter");      // Subject contains "newsletter"
+client.set_query("from:noreply@example.com"); // From specific sender
+
+// Combined queries
+client.set_query("label:promotions older_than:6m -is:starred");
+```
+
+## Performance & Limits
+
+### Pagination
+
+- Default page size: 200 messages
+- Use `client.set_max_results(n)` to adjust
+- Use `client.get_messages(0)` to get all pages
+- Use `client.get_messages(n)` to limit to n pages
+
+### Rate Limits
+
+- The library uses the official `google-gmail1` crate
+- Built-in retry logic for transient errors
+- Respects Gmail API quotas and limits
+
+### Batch Operations
+
+- Batch delete/trash operations are more efficient than individual calls
+- Operations are atomic - either all succeed or all fail
+
+## Logging
+
+The library uses the `log` crate for logging:
+
+```rust path=null start=null
+use env_logger;
+
+// Initialize logging
+env_logger::init();
+
+# Set log level via environment variable
+# RUST_LOG=cull_gmail=debug cargo run
+```
+
+Log levels:
+- `error`: Critical errors
+- `warn`: Warnings (e.g., missing labels, dry-run mode)
+- `info`: General information (e.g., message subjects, action results)
+- `debug`: Detailed operation info
+- `trace`: Very detailed debugging info
+
+## Security Considerations
+
+### OAuth2 Token Storage
+- Tokens are stored in `~/.cull-gmail/gmail1` by default
+- Tokens are automatically refreshed when expired
+- Revoke access in [Google Account settings](https://myaccount.google.com/permissions)
+
+### Required Scopes
+The library requires the `https://mail.google.com/` scope for full Gmail access.
+
+### Credential File Security
+- Store credential files securely (not in version control)
+- Use restrictive file permissions (600)
+- Consider using environment variables in production
+
+## Troubleshooting
+
+### Authentication Issues
+1. Verify credential file path and format
+2. Check OAuth2 client is configured for "Desktop Application"
+3. Ensure redirect URI matches configuration
+4. Clear token cache: `rm -rf ~/.cull-gmail/gmail1`
+
+### No Messages Found
+1. Verify label names exist: `client.show_label()`
+2. Test query syntax in Gmail web interface
+3. Check for typos in label names or query strings
+
+### Rate Limiting
+1. Reduce page size: `client.set_max_results(100)`
+2. Add delays between operations
+3. Check [Gmail API quotas](https://developers.google.com/gmail/api/reference/quota)
+
+## See Also
+
+- [CLI Documentation](main.md) - Complete guide to the command-line interface
+- [Examples Directory](../examples/) - Additional code examples and sample configurations
+- [API Documentation](https://docs.rs/cull-gmail) - Generated API reference
+- [Repository](https://github.com/jerus-org/cull-gmail) - Source code and issue tracking