@ngxtm/devkit 3.15.0 → 3.17.0

package/merged-commands/gitlab-automation.md

@@ -0,0 +1,259 @@
+---
+name: gitlab-automation
+description: "Automate GitLab project management, issues, merge requests, pipelines, branches, and user operations via Rube MCP (Composio). Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# GitLab Automation via Rube MCP
+
+Automate GitLab operations including project management, issue tracking, merge request workflows, CI/CD pipeline monitoring, branch management, and user administration through Composio's GitLab toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active GitLab connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `gitlab`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `gitlab`
+3. If connection is not ACTIVE, follow the returned auth link to complete GitLab OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Manage Issues
+
+**When to use**: User wants to create, update, list, or search issues in a GitLab project
+
+**Tool sequence**:
+1. `GITLAB_GET_PROJECTS` - Find the target project and get its ID [Prerequisite]
+2. `GITLAB_LIST_PROJECT_ISSUES` - List and filter issues for a project [Required]
+3. `GITLAB_CREATE_PROJECT_ISSUE` - Create a new issue [Required for create]
+4. `GITLAB_UPDATE_PROJECT_ISSUE` - Update an existing issue (title, labels, state, assignees) [Required for update]
+5. `GITLAB_LIST_PROJECT_USERS` - Find user IDs for assignment [Optional]
+
+**Key parameters**:
+- `id`: Project ID (integer) or URL-encoded path (e.g., `"my-group/my-project"`)
+- `title`: Issue title (required for creation)
+- `description`: Issue body text (max 1,048,576 characters)
+- `labels`: Comma-separated label names (e.g., `"bug,critical"`)
+- `add_labels` / `remove_labels`: Add or remove labels without replacing all
+- `state`: Filter by `"all"`, `"opened"`, or `"closed"`
+- `state_event`: `"close"` or `"reopen"` to change issue state
+- `assignee_ids`: Array of user IDs; use `[0]` to unassign all
+- `issue_iid`: Internal issue ID within the project (required for updates)
+- `milestone`: Filter by milestone title
+- `search`: Search in title and description
+- `scope`: `"created_by_me"`, `"assigned_to_me"`, or `"all"`
+- `page` / `per_page`: Pagination (default per_page: 20)
+
+**Pitfalls**:
+- `id` accepts either integer project ID or URL-encoded path; wrong IDs yield 4xx errors
+- `issue_iid` is the project-internal ID (shown as #42), different from the global issue ID
+- Labels in `labels` field replace ALL existing labels; use `add_labels`/`remove_labels` for incremental changes
+- Setting `assignee_ids` to empty array does NOT unassign; use `[0]` instead
+- `updated_at` field requires administrator or project/group owner rights
+
+### 2. Manage Merge Requests
+
+**When to use**: User wants to list, filter, or review merge requests in a project
+
+**Tool sequence**:
+1. `GITLAB_GET_PROJECT` - Get project details and verify access [Prerequisite]
+2. `GITLAB_GET_PROJECT_MERGE_REQUESTS` - List and filter merge requests [Required]
+3. `GITLAB_GET_REPOSITORY_BRANCHES` - Verify source/target branches [Optional]
+4. `GITLAB_LIST_ALL_PROJECT_MEMBERS` - Find reviewers/assignees [Optional]
+
+**Key parameters**:
+- `id`: Project ID or URL-encoded path
+- `state`: `"opened"`, `"closed"`, `"locked"`, `"merged"`, or `"all"`
+- `scope`: `"created_by_me"` (default), `"assigned_to_me"`, or `"all"`
+- `source_branch` / `target_branch`: Filter by branch names
+- `author_id` / `author_username`: Filter by MR author
+- `assignee_id`: Filter by assignee (use `None` for unassigned, `Any` for assigned)
+- `reviewer_id` / `reviewer_username`: Filter by reviewer
+- `labels`: Comma-separated label filter
+- `search`: Search in title and description
+- `wip`: `"yes"` for draft MRs, `"no"` for non-draft
+- `order_by`: `"created_at"` (default), `"title"`, `"merged_at"`, `"updated_at"`
+- `view`: `"simple"` for minimal fields
+- `iids[]`: Filter by specific MR internal IDs
+
+**Pitfalls**:
+- Default `scope` is `"created_by_me"` which limits results; use `"all"` for complete listings
+- `author_id` and `author_username` are mutually exclusive
+- `reviewer_id` and `reviewer_username` are mutually exclusive
+- `approved` filter requires the `mr_approved_filter` feature flag (disabled by default)
+- Large MR histories can be noisy; use filters and moderate `per_page` values
+
+### 3. Manage Projects and Repositories
+
+**When to use**: User wants to list projects, create new projects, or manage branches
+
+**Tool sequence**:
+1. `GITLAB_GET_PROJECTS` - List all accessible projects with filters [Required]
+2. `GITLAB_GET_PROJECT` - Get detailed info for a specific project [Optional]
+3. `GITLAB_LIST_USER_PROJECTS` - List projects owned by a specific user [Optional]
+4. `GITLAB_CREATE_PROJECT` - Create a new project [Required for create]
+5. `GITLAB_GET_REPOSITORY_BRANCHES` - List branches in a project [Required for branch ops]
+6. `GITLAB_CREATE_REPOSITORY_BRANCH` - Create a new branch [Optional]
+7. `GITLAB_GET_REPOSITORY_BRANCH` - Get details of a specific branch [Optional]
+8. `GITLAB_LIST_REPOSITORY_COMMITS` - View commit history [Optional]
+9. `GITLAB_GET_PROJECT_LANGUAGES` - Get language breakdown [Optional]
+
+**Key parameters**:
+- `name` / `path`: Project name and URL-friendly path (both required for creation)
+- `visibility`: `"private"`, `"internal"`, or `"public"`
+- `namespace_id`: Group or user ID for project placement
+- `search`: Case-insensitive substring search for projects
+- `membership`: `true` to limit to projects user is a member of
+- `owned`: `true` to limit to user-owned projects
+- `project_id`: Project ID for branch operations
+- `branch_name`: Name for new branch
+- `ref`: Source branch or commit SHA for new branch creation
+- `order_by`: `"id"`, `"name"`, `"path"`, `"created_at"`, `"updated_at"`, `"star_count"`, `"last_activity_at"`
+
+**Pitfalls**:
+- `GITLAB_GET_PROJECTS` pagination is required for complete coverage; stopping at first page misses projects
+- Some responses place items under `data.details`; parse the actual returned list structure
+- Most follow-up calls depend on correct `project_id`; verify with `GITLAB_GET_PROJECT` first
+- Invalid `branch_name`/`ref`/`sha` causes client errors; verify branch existence via `GITLAB_GET_REPOSITORY_BRANCHES` first
+- Both `name` and `path` are required for `GITLAB_CREATE_PROJECT`
+
+### 4. Monitor CI/CD Pipelines
+
+**When to use**: User wants to check pipeline status, list jobs, or monitor CI/CD runs
+
+**Tool sequence**:
+1. `GITLAB_GET_PROJECT` - Verify project access [Prerequisite]
+2. `GITLAB_LIST_PROJECT_PIPELINES` - List pipelines with filters [Required]
+3. `GITLAB_GET_SINGLE_PIPELINE` - Get detailed info for a specific pipeline [Optional]
+4. `GITLAB_LIST_PIPELINE_JOBS` - List jobs within a pipeline [Optional]
+
+**Key parameters**:
+- `id`: Project ID or URL-encoded path
+- `status`: Filter by `"created"`, `"waiting_for_resource"`, `"preparing"`, `"pending"`, `"running"`, `"success"`, `"failed"`, `"canceled"`, `"skipped"`, `"manual"`, `"scheduled"`
+- `scope`: `"running"`, `"pending"`, `"finished"`, `"branches"`, `"tags"`
+- `ref`: Branch or tag name
+- `sha`: Specific commit SHA
+- `source`: Pipeline source (use `"parent_pipeline"` for child pipelines)
+- `order_by`: `"id"` (default), `"status"`, `"ref"`, `"updated_at"`, `"user_id"`
+- `created_after` / `created_before`: ISO 8601 date filters
+- `pipeline_id`: Specific pipeline ID for job listing
+- `include_retried`: `true` to include retried jobs (default `false`)
+
+**Pitfalls**:
+- Large pipeline histories can be noisy; use `status`, `ref`, and date filters to narrow results
+- Use moderate `per_page` values to keep output manageable
+- Pipeline job `scope` accepts single status string or array of statuses
+- `yaml_errors: true` returns only pipelines with invalid configurations
+
+### 5. Manage Users and Members
+
+**When to use**: User wants to find users, list project members, or check user status
+
+**Tool sequence**:
+1. `GITLAB_GET_USERS` - Search and list GitLab users [Required]
+2. `GITLAB_GET_USER` - Get details for a specific user by ID [Optional]
+3. `GITLAB_GET_USERS_ID_STATUS` - Get user status message and availability [Optional]
+4. `GITLAB_LIST_ALL_PROJECT_MEMBERS` - List all project members (direct + inherited) [Required for member listing]
+5. `GITLAB_LIST_PROJECT_USERS` - List project users with search filter [Optional]
+
+**Key parameters**:
+- `search`: Search by name, username, or public email
+- `username`: Get specific user by username
+- `active` / `blocked`: Filter by user state
+- `id`: Project ID for member listing
+- `query`: Filter members by name, email, or username
+- `state`: Filter members by `"awaiting"` or `"active"` (Premium/Ultimate)
+- `user_ids`: Filter by specific user IDs
+
+**Pitfalls**:
+- Many user filters (admins, auditors, extern_uid, two_factor) are admin-only
+- `GITLAB_LIST_ALL_PROJECT_MEMBERS` includes direct, inherited, and invited members
+- User search is case-insensitive but may not match partial email domains
+- Premium/Ultimate features (state filter, seat info) are not available on free plans
+
+## Common Patterns
+
+### ID Resolution
+GitLab uses two identifier formats for projects:
+- **Numeric ID**: Integer project ID (e.g., `123`)
+- **URL-encoded path**: Namespace/project format (e.g., `"my-group%2Fmy-project"` or `"my-group/my-project"`)
+- **Issue IID vs ID**: `issue_iid` is the project-internal number (#42); the global `id` is different
+- **User ID**: Numeric; resolve via `GITLAB_GET_USERS` with `search` or `username`
+
+### Pagination
+GitLab uses offset-based pagination:
+- Set `page` (starting at 1) and `per_page` (1-100, default 20)
+- Continue incrementing `page` until response returns fewer items than `per_page` or is empty
+- Total count may be available in response headers (`X-Total`, `X-Total-Pages`)
+- Always paginate to completion for accurate results
+
+### URL-Encoded Paths
+When using project paths as identifiers:
+- Forward slashes must be URL-encoded: `my-group/my-project` becomes `my-group%2Fmy-project`
+- Some tools accept unencoded paths; check schema for each tool
+- Prefer numeric IDs when available for reliability
+
+## Known Pitfalls
+
+### ID Formats
+- Project `id` field accepts both integer and string (URL-encoded path)
+- Issue `issue_iid` is project-scoped; do not confuse with global issue ID
+- Pipeline IDs are project-scoped integers
+- User IDs are global integers across the GitLab instance
+
+### Rate Limits
+- GitLab has per-user rate limits (typically 300-2000 requests/minute depending on plan)
+- Large pipeline/issue histories should use date and status filters to reduce result sets
+- Paginate responsibly with moderate `per_page` values
+
+### Parameter Quirks
+- `labels` field replaces ALL labels; use `add_labels`/`remove_labels` for incremental changes
+- `assignee_ids: [0]` unassigns all; empty array does nothing
+- `scope` defaults vary: `"created_by_me"` for MRs, `"all"` for issues
+- `author_id` and `author_username` are mutually exclusive in MR filters
+- Date parameters use ISO 8601 format: `"2024-01-15T10:30:00Z"`
+
+### Plan Restrictions
+- Some features require Premium/Ultimate: `epic_id`, `weight`, `iteration_id`, `approved_by_ids`, member `state` filter
+- Admin-only features: user management filters, `updated_at` override, custom attributes
+- The `mr_approved_filter` feature flag is disabled by default
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List projects | `GITLAB_GET_PROJECTS` | `search`, `membership`, `visibility` |
+| Get project details | `GITLAB_GET_PROJECT` | `id` |
+| User's projects | `GITLAB_LIST_USER_PROJECTS` | `id`, `search`, `owned` |
+| Create project | `GITLAB_CREATE_PROJECT` | `name`, `path`, `visibility` |
+| List issues | `GITLAB_LIST_PROJECT_ISSUES` | `id`, `state`, `labels`, `search` |
+| Create issue | `GITLAB_CREATE_PROJECT_ISSUE` | `id`, `title`, `description`, `labels` |
+| Update issue | `GITLAB_UPDATE_PROJECT_ISSUE` | `id`, `issue_iid`, `state_event` |
+| List merge requests | `GITLAB_GET_PROJECT_MERGE_REQUESTS` | `id`, `state`, `scope`, `labels` |
+| List branches | `GITLAB_GET_REPOSITORY_BRANCHES` | `project_id`, `search` |
+| Get branch | `GITLAB_GET_REPOSITORY_BRANCH` | `project_id`, `branch_name` |
+| Create branch | `GITLAB_CREATE_REPOSITORY_BRANCH` | `project_id`, `branch_name`, `ref` |
+| List commits | `GITLAB_LIST_REPOSITORY_COMMITS` | project ID, branch ref |
+| Project languages | `GITLAB_GET_PROJECT_LANGUAGES` | project ID |
+| List pipelines | `GITLAB_LIST_PROJECT_PIPELINES` | `id`, `status`, `ref` |
+| Get pipeline | `GITLAB_GET_SINGLE_PIPELINE` | `project_id`, `pipeline_id` |
+| List pipeline jobs | `GITLAB_LIST_PIPELINE_JOBS` | `id`, `pipeline_id`, `scope` |
+| Search users | `GITLAB_GET_USERS` | `search`, `username`, `active` |
+| Get user | `GITLAB_GET_USER` | user ID |
+| User status | `GITLAB_GET_USERS_ID_STATUS` | user ID |
+| List project members | `GITLAB_LIST_ALL_PROJECT_MEMBERS` | `id`, `query`, `state` |
+| List project users | `GITLAB_LIST_PROJECT_USERS` | `id`, `search` |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/gitlab-ci-patterns.md

@@ -1,6 +1,8 @@
 ---
 name: gitlab-ci-patterns
-description: Build GitLab CI/CD pipelines with multi-stage workflows, caching, and distributed runners for scalable automation. Use when implementing GitLab CI/CD, optimizing pipeline performance, or setting up automated testing and deployment.
+description: "Build GitLab CI/CD pipelines with multi-stage workflows, caching, and distributed runners for scalable automation. Use when implementing GitLab CI/CD, optimizing pipeline performance, or setting up..."
+risk: unknown
+source: community
 ---
 
 # GitLab CI Patterns

package/merged-commands/gitops-workflow.md

@@ -1,6 +1,8 @@
 ---
 name: gitops-workflow
-description: Implement GitOps workflows with ArgoCD and Flux for automated, declarative Kubernetes deployments with continuous reconciliation. Use when implementing GitOps practices, automating Kubernetes deployments, or setting up declarative infrastructure management.
+description: "Implement GitOps workflows with ArgoCD and Flux for automated, declarative Kubernetes deployments with continuous reconciliation. Use when implementing GitOps practices, automating Kubernetes deplo..."
+risk: unknown
+source: community
 ---
 
 # GitOps Workflow

package/merged-commands/gmail-automation.md

@@ -0,0 +1,275 @@
+---
+name: gmail-automation
+description: "Automate Gmail tasks via Rube MCP (Composio): send/reply, search, labels, drafts, attachments. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# Gmail Automation via Rube MCP
+
+Automate Gmail operations through Composio's Gmail toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Gmail connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `gmail`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `gmail`
+3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Send an Email
+
+**When to use**: User wants to compose and send a new email
+
+**Tool sequence**:
+1. `GMAIL_SEARCH_PEOPLE` - Resolve contact name to email address [Optional]
+2. `GMAIL_SEND_EMAIL` - Send the email [Required]
+
+**Key parameters**:
+- `recipient_email`: Email address or 'me' for self
+- `subject`: Email subject line
+- `body`: Email content (plain text or HTML)
+- `is_html`: Must be `true` if body contains HTML markup
+- `cc`/`bcc`: Arrays of email addresses
+- `attachment`: Object with `{s3key, mimetype, name}` from prior download
+
+**Pitfalls**:
+- At least one of `recipient_email`, `cc`, or `bcc` required
+- At least one of `subject` or `body` required
+- Attachment `mimetype` MUST contain '/' (e.g., 'application/pdf', not 'pdf')
+- Total message size limit ~25MB after base64 encoding
+- Use `from_email` only for verified aliases in Gmail 'Send mail as' settings
+
+### 2. Reply to a Thread
+
+**When to use**: User wants to reply to an existing email conversation
+
+**Tool sequence**:
+1. `GMAIL_FETCH_EMAILS` - Find the email/thread to reply to [Prerequisite]
+2. `GMAIL_REPLY_TO_THREAD` - Send reply within the thread [Required]
+
+**Key parameters**:
+- `thread_id`: Hex string from FETCH_EMAILS (e.g., '169eefc8138e68ca')
+- `message_body`: Reply content
+- `recipient_email`: Reply recipient
+- `is_html`: Set `true` for HTML content
+
+**Pitfalls**:
+- `thread_id` must be hex string; prefixes like 'msg-f:' are auto-stripped
+- Legacy Gmail web UI IDs (e.g., 'FMfcgz...') are NOT supported
+- Subject is inherited from original thread; setting it creates a new thread instead
+- Do NOT include subject parameter to stay within thread
+
+### 3. Search and Filter Emails
+
+**When to use**: User wants to find specific emails by sender, subject, date, label, etc.
+
+**Tool sequence**:
+1. `GMAIL_FETCH_EMAILS` - Search with Gmail query syntax [Required]
+2. `GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID` - Get full message details for selected results [Optional]
+
+**Key parameters**:
+- `query`: Gmail search syntax (from:, to:, subject:, is:unread, has:attachment, after:YYYY/MM/DD, before:YYYY/MM/DD)
+- `max_results`: 1-500 messages per page
+- `label_ids`: System IDs like 'INBOX', 'UNREAD'
+- `include_payload`: Set `true` to get full message content
+- `ids_only`: Set `true` for just message IDs
+- `page_token`: For pagination (from `nextPageToken`)
+
+**Pitfalls**:
+- Returns max ~500 per page; follow `nextPageToken` via `page_token` until absent
+- `resultSizeEstimate` is approximate, not exact count
+- Use 'is:' for states (is:unread, is:snoozed, is:starred)
+- Use 'label:' ONLY for user-created labels
+- Common mistake: 'label:snoozed' is WRONG — use 'is:snoozed'
+- `include_payload=true` on broad searches creates huge responses; default to metadata
+- Custom labels require label ID (e.g., 'Label_123'), NOT label name
+
+### 4. Manage Labels
+
+**When to use**: User wants to create, modify, or organize labels
+
+**Tool sequence**:
+1. `GMAIL_LIST_LABELS` - List all labels to find IDs and detect conflicts [Required]
+2. `GMAIL_CREATE_LABEL` - Create a new label [Optional]
+3. `GMAIL_PATCH_LABEL` - Rename or change label colors/visibility [Optional]
+4. `GMAIL_DELETE_LABEL` - Delete a user-created label (irreversible) [Optional]
+
+**Key parameters**:
+- `label_name`: Max 225 chars, no commas, '/' for nesting (e.g., 'Work/Projects')
+- `background_color`/`text_color`: Hex values from Gmail's predefined palette
+- `id`: Label ID for PATCH/DELETE operations
+
+**Pitfalls**:
+- 400/409 error if name is blank, duplicate, or reserved (INBOX, SPAM, CATEGORY_*)
+- Color specs must use Gmail's predefined palette of 102 hex values
+- DELETE is permanent and removes label from all messages
+- Cannot delete system labels (INBOX, SENT, DRAFT, etc.)
+
+### 5. Apply/Remove Labels on Messages
+
+**When to use**: User wants to label, archive, or mark emails as read/unread
+
+**Tool sequence**:
+1. `GMAIL_LIST_LABELS` - Get label IDs for custom labels [Prerequisite]
+2. `GMAIL_FETCH_EMAILS` - Find target messages [Prerequisite]
+3. `GMAIL_BATCH_MODIFY_MESSAGES` - Bulk add/remove labels (up to 1000 messages) [Required]
+4. `GMAIL_ADD_LABEL_TO_EMAIL` - Single-message label changes [Fallback]
+
+**Key parameters**:
+- `messageIds`: Array of message IDs (max 1000)
+- `addLabelIds`: Array of label IDs to add
+- `removeLabelIds`: Array of label IDs to remove
+- `message_id`: 15-16 char hex string for single operations
+
+**Pitfalls**:
+- Max 1000 messageIds per BATCH call; chunk larger sets
+- Use 'CATEGORY_UPDATES' not 'UPDATES'; full prefix required for category labels
+- SENT, DRAFT, CHAT are immutable — cannot be added/removed
+- To mark as read: REMOVE 'UNREAD'. To archive: REMOVE 'INBOX'
+- `message_id` must be 15-16 char hex, NOT UUIDs or web UI IDs
+
+### 6. Handle Drafts and Attachments
+
+**When to use**: User wants to create, edit, or send email drafts, possibly with attachments
+
+**Tool sequence**:
+1. `GMAIL_CREATE_EMAIL_DRAFT` - Create a new draft [Required]
+2. `GMAIL_UPDATE_DRAFT` - Edit draft content [Optional]
+3. `GMAIL_LIST_DRAFTS` - List existing drafts [Optional]
+4. `GMAIL_SEND_DRAFT` - Send a draft (requires explicit user approval) [Optional]
+5. `GMAIL_GET_ATTACHMENT` - Download attachment from existing message [Optional]
+
+**Key parameters**:
+- `recipient_email`: Draft recipient
+- `subject`: Draft subject (omit for reply drafts to stay in thread)
+- `body`: Draft content
+- `is_html`: Set `true` for HTML content
+- `attachment`: Object with `{s3key, mimetype, name}`
+- `thread_id`: For reply drafts (leave subject empty to stay in thread)
+
+**Pitfalls**:
+- Response includes `data.id` (draft_id) AND `data.message.id`; use `data.id` for draft operations
+- Setting subject on a thread reply draft creates a NEW thread instead
+- Attachment capped at ~25MB; base64 overhead can push near-limit files over
+- UPDATE_DRAFT replaces entire content, not patches; include all fields you want to keep
+- HTTP 429 on bulk draft creation; use exponential backoff
+
+## Common Patterns
+
+### ID Resolution
+
+**Label name → Label ID**:
+```
+1. Call GMAIL_LIST_LABELS
+2. Find label by name in response
+3. Extract id field (e.g., 'Label_123')
+```
+
+**Contact name → Email**:
+```
+1. Call GMAIL_SEARCH_PEOPLE with query=contact_name
+2. Extract emailAddresses from response
+```
+
+**Thread ID from search**:
+```
+1. Call GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS
+2. Extract threadId (15-16 char hex string)
+```
+
+### Pagination
+
+- Set `max_results` up to 500 per page
+- Check response for `nextPageToken`
+- Pass token as `page_token` in next request
+- Continue until `nextPageToken` is absent or empty string
+- `resultSizeEstimate` is approximate, not exact
+
+### Gmail Query Syntax
+
+**Operators**:
+- `from:sender@example.com` - Emails from sender
+- `to:recipient@example.com` - Emails to recipient
+- `subject:"exact phrase"` - Subject contains exact phrase
+- `is:unread` - Unread messages
+- `is:starred` - Starred messages
+- `is:snoozed` - Snoozed messages
+- `has:attachment` - Has attachments
+- `after:2024/01/01` - After date (YYYY/MM/DD)
+- `before:2024/12/31` - Before date
+- `label:custom_label` - User-created label (use label ID)
+- `in:sent` - In sent folder
+- `category:primary` - Primary category
+
+**Combinators**:
+- `AND` - Both conditions (default)
+- `OR` - Either condition
+- `NOT` - Exclude condition
+- `()` - Group conditions
+
+**Examples**:
+- `from:boss@company.com is:unread` - Unread emails from boss
+- `subject:invoice has:attachment after:2024/01/01` - Invoices with attachments this year
+- `(from:alice OR from:bob) is:starred` - Starred emails from Alice or Bob
+
+## Known Pitfalls
+
+**ID Formats**:
+- Custom label operations require label IDs (e.g., 'Label_123'), not display names
+- Always call LIST_LABELS first to resolve names to IDs
+- Message IDs are 15-16 char hex strings
+- Do NOT use UUIDs, web UI IDs, or 'thread-f:' prefixes
+
+**Query Syntax**:
+- Use 'is:' for states (unread, snoozed, starred)
+- Use 'label:' ONLY for user-created labels
+- System labels use 'is:' or 'in:' (e.g., 'is:sent', 'in:inbox')
+
+**Rate Limits**:
+- BATCH_MODIFY_MESSAGES max 1000 messages per call
+- Heavy use triggers 403/429 rate limits
+- Implement exponential backoff for bulk operations
+
+**Response Parsing**:
+- Response data may be nested under `data_preview` or `data.messages`
+- Parse defensively with fallbacks
+- Timestamp `messageTimestamp` uses RFC3339 with 'Z' suffix
+- Normalize to '+00:00' for parsing if needed
+
+**Attachments**:
+- Attachment `s3key` from prior download may expire
+- Use promptly after retrieval
+- Mimetype must include '/' separator
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Send email | GMAIL_SEND_EMAIL | recipient_email, subject, body, is_html |
+| Reply to thread | GMAIL_REPLY_TO_THREAD | thread_id, message_body, recipient_email |
+| Search emails | GMAIL_FETCH_EMAILS | query, max_results, label_ids, page_token |
+| Get message details | GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID | message_id |
+| List labels | GMAIL_LIST_LABELS | (none) |
+| Create label | GMAIL_CREATE_LABEL | label_name, background_color, text_color |
+| Modify labels bulk | GMAIL_BATCH_MODIFY_MESSAGES | messageIds, addLabelIds, removeLabelIds |
+| Create draft | GMAIL_CREATE_EMAIL_DRAFT | recipient_email, subject, body, thread_id |
+| Send draft | GMAIL_SEND_DRAFT | draft_id |
+| Get attachment | GMAIL_GET_ATTACHMENT | message_id, attachment_id |
+| Search contacts | GMAIL_SEARCH_PEOPLE | query |
+| Get profile | GMAIL_GET_PROFILE | (none) |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/go-concurrency-patterns.md

@@ -1,6 +1,8 @@
 ---
 name: go-concurrency-patterns
-description: Master Go concurrency with goroutines, channels, sync primitives, and context. Use when building concurrent Go applications, implementing worker pools, or debugging race conditions.
+description: "Master Go concurrency with goroutines, channels, sync primitives, and context. Use when building concurrent Go applications, implementing worker pools, or debugging race conditions."
+risk: unknown
+source: community
 ---
 
 # Go Concurrency Patterns

package/merged-commands/go-playwright.md

@@ -0,0 +1,76 @@
+---
+name: go-playwright
+description: "Expert capability for robust, stealthy, and efficient browser automation using Playwright Go."
+risk: safe
+source: https://github.com/playwright-community/playwright-go
+---
+
+# Playwright Go Automation Expert
+
+## Overview
+This skill provides a comprehensive framework for writing high-performance, production-grade browser automation scripts using `github.com/playwright-community/playwright-go`. It enforces architectural best practices (contexts over instances), robust error handling, structured logging (Zap), and advanced human-emulation techniques to bypass anti-bot systems.
+
+## When to Use This Skill
+- Use when the user asks to "scrape," "automate," or "test" a website using Go.
+- Use when the target site has complex dynamic content (SPA, React, Vue) requiring a real browser.
+- Use when the user mentions "stealth," "avoiding detection," "cloudflare," or "human-like" behavior.
+- Use when debugging existing Playwright scripts.
+
+## Safety & Risk
+**Risk Level: 🔵 Safe**
+
+- **Sandboxed Execution:** Browser contexts are isolated; they do not persist data to the host machine unless explicitly saved.
+- **Resource Management:** Designed to close browsers and contexts via `defer` to prevent memory leaks.
+- **No External State-Change:** Default behavior is read-only (scraping/testing) unless the script is explicitly designed to submit forms or modify data.
+
+## Limitations
+- **Environment Dependencies:** Requires Playwright drivers and browsers to be installed (`go run github.com/playwright-community/playwright-go/cmd/playwright@latest install --with-deps`).
+- **Resource Intensity:** Launching full browser instances (even headless) consumes significant RAM/CPU. Use single-browser/multi-context architecture.
+- **Bot Detection:** While this skill includes stealth techniques, extremely strict anti-bot systems (e.g., rigorous Cloudflare settings) may still detect automation.
+- **CAPTCHAs:** Does not include built-in CAPTCHA solving capabilities.
+
+## Strategic Implementation Guidelines
+
+### 1. Architecture: Contexts vs. Browsers
+**CRITICAL:** Never launch a new `Browser` instance for every task.
+- **Pattern:** Launch the `Browser` *once* (singleton). Create a new `BrowserContext` for each distinct session or task.
+- **Why:** Contexts are lightweight and created in milliseconds. Browsers take seconds to launch.
+- **Isolation:** Contexts provide complete isolation (cookies, cache, storage) without the overhead of a new process.
+
+### 2. Logging & Observability
+- **Library:** Use `go.uber.org/zap` exclusively.
+- **Rule:** Do not use `fmt.Println`.
+- **Modes:**
+  - **Dev:** `zap.NewDevelopment()` (Console friendly)
+  - **Prod:** `zap.NewProduction()` (JSON structured)
+- **Traceability:** Log every navigation, click, and input with context fields (e.g., `logger.Info("clicking button", zap.String("selector", sel))`).
+
+### 3. Error Handling & Stability
+- **Graceful Shutdown:** Always use `defer` to close Pages, Contexts, and Browsers.
+- **Panic Recovery:** Wrap critical automation routines in a safe runner that recovers panics and logs the stack trace.
+- **Timeouts:** Never rely on default timeouts. Set explicit timeouts (e.g., `playwright.PageClickOptions{Timeout: playwright.Float(5000)}`).
+
+### 4. Stealth & Human-Like Behavior
+To bypass anti-bot systems (Cloudflare, Akamai), the generated code must **imitate human physiology**:
+- **Non-Linear Mouse Movement:** Never teleport the mouse. Implement a helper that moves the mouse along a Bezier curve with random jitter.
+- **Input Latency:** never use `Fill()`. Use `Type()` with random delays between keystrokes (50ms–200ms).
+- **Viewport Randomization:** Randomize the viewport size slightly (e.g., 1920x1080 ± 15px) to avoid fingerprinting.
+- **Behavioral Noise:** Randomly scroll, focus/unfocus the window, or hover over irrelevant elements ("idling") during long waits.
+- **User-Agent:** Rotate User-Agents for every new Context.
+
+### 5. Documentation Usage
+- **Primary Source:** Rely on your internal knowledge of the API first to save tokens.
+- **Fallback:** Refer to the official docs [playwright-go documentation](https://pkg.go.dev/github.com/playwright-community/playwright-go#section-documentation) ONLY if:
+  - You encounter an unknown error.
+  - You need to implement complex network interception or authentication flows.
+  - The API has changed significantly.
+
+## Resources
+- `resources/implementation-playbook.md` for detailed code examples and implementation patterns.
+
+
+### Summary Checklist for Agent
+ - Is Debug Mode on? -> `Headless=false`, `SlowMo=100+`.
+ - Is it a new user identity? -> `NewContext`, apply new Proxy, rotate `User-Agent`.
+ - Is the action critical? -> Wrap in `SafeAction` with Zap logging.
+ - Is the target guarded (Cloudflare/Akamai)? -> Enable `HumanType`, `BezierMouse`, and Stealth Scripts.