@cubis/foundry 0.3.30 → 0.3.32

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/saas-builder/steering/billing-and-payments.md

@@ -0,0 +1,165 @@
+---
+inclusion: always
+---
+
+# Billing and Payments
+
+## Money Handling Rules
+
+### Never Use Floats for Money
+- Use integers for all monetary amounts (cents, not dollars)
+- Store: `amount_cents: 1999` (represents $19.99)
+- Display: Convert to decimal only in UI layer
+- Calculate: All math in cents, round at the end
+- Currency: Always store currency code with amount (`USD`, `EUR`, etc.)
+
+### Data Types
+- Backend: Integer type for cents (int64/bigint for large amounts)
+- Database: Integer column, never DECIMAL or FLOAT
+- API: Send as integer cents in JSON: `{"amount": 1999, "currency": "USD"}`
+- Frontend: Convert to display format: `(1999 / 100).toFixed(2)` → "$19.99"
+
+## Payment Integration
+
+### Use Payment Service Providers
+- Never store credit card numbers (PCI compliance nightmare)
+- Use Stripe, Paddle, or similar for payment processing
+- Store only: customer ID, subscription ID, payment method ID (tokens)
+- Let provider handle: card storage, PCI compliance, fraud detection
+
+### Idempotency
+- All payment operations MUST be idempotent
+- Use idempotency keys for charge/refund operations
+- Store operation results to prevent duplicate charges
+- Handle webhook retries gracefully (same event may arrive multiple times)
+
+### Webhook Security
+- Verify webhook signatures (Stripe signature, etc.)
+- Use HTTPS endpoints only
+- Process webhooks asynchronously (return 200 immediately, process in background)
+- Store raw webhook payload for debugging
+- Implement retry logic for failed webhook processing
+
+## Subscription Management
+
+### Subscription States
+Track subscription lifecycle per tenant:
+- `trial` - Free trial period
+- `active` - Paid and current
+- `past_due` - Payment failed, grace period
+- `canceled` - User canceled, end of billing period
+- `expired` - Subscription ended
+
+### Grace Periods
+- Don't immediately disable on payment failure
+- Provide grace period (3-7 days) with notifications
+- Degrade gracefully: read-only mode before full lockout
+- Allow reactivation without data loss
+
+### Proration
+- Calculate prorated amounts when changing plans mid-cycle
+- Use provider's proration logic (Stripe handles this)
+- Show preview of charges before plan changes
+- Document proration policy clearly to users
+
+## Usage-Based Billing
+
+### Metering Pattern
+```
+1. Track usage events in real-time
+2. Aggregate usage per tenant per billing period
+3. Calculate charges based on usage tiers
+4. Generate invoice at end of billing period
+5. Charge payment method on file
+```
+
+### Usage Tracking
+- Publish usage events to EventBridge immediately
+- Store aggregated usage in DynamoDB (tenant + period)
+- Include metadata: tenant ID, user ID, resource type, quantity, timestamp
+- Make usage data queryable for customer dashboards
+
+### Quota Enforcement
+- Check quota before expensive operations
+- Return 429 with clear message when quota exceeded
+- Offer upgrade path in error response
+- Track quota usage in real-time (cache in Lambda memory)
+
+## Invoicing
+
+### Invoice Generation
+- Generate invoices automatically at billing cycle end
+- Include: line items, usage details, taxes, discounts
+- Store invoices in S3 (PDF) and metadata in DynamoDB
+- Send invoice email with PDF attachment
+- Provide invoice history in customer portal
+
+### Tax Handling
+- Use tax calculation service (Stripe Tax, TaxJar)
+- Never calculate tax manually (complex, jurisdiction-specific)
+- Store tax rate and amount with each transaction
+- Support tax-exempt customers (store exemption certificate)
+
+## Financial Reporting
+
+### Audit Trail
+- Log all financial operations: charges, refunds, credits
+- Include: timestamp, tenant ID, amount, reason, operator
+- Immutable logs (append-only)
+- Retain for 7+ years (compliance requirement)
+
+### Revenue Recognition
+- Track MRR (Monthly Recurring Revenue) per tenant
+- Calculate churn rate and LTV (Lifetime Value)
+- Store subscription start/end dates for cohort analysis
+- Separate one-time charges from recurring revenue
+
+## Security & Compliance
+
+### PCI Compliance
+- Never log credit card numbers (even partial)
+- Use tokenization for stored payment methods
+- Encrypt sensitive financial data at rest
+- Limit access to financial data (RBAC)
+
+### Fraud Prevention
+- Monitor for unusual patterns: rapid plan changes, high-value transactions
+- Implement velocity limits (max charges per hour)
+- Require additional verification for large amounts
+- Use provider's fraud detection (Stripe Radar)
+
+### Refund Policy
+- Implement clear refund policy
+- Track refund reasons for analysis
+- Partial refunds for prorated cancellations
+- Automate refunds where possible, manual review for large amounts
+
+## Multi-Currency Support
+
+### Currency Handling
+- Store prices in multiple currencies if needed
+- Use exchange rates from reliable source (provider or ECB)
+- Lock exchange rate at time of charge
+- Display prices in customer's currency
+- Bill in customer's currency to avoid FX fees
+
+### Localization
+- Format currency according to locale: `$1,999.99` (US) vs `1.999,99 €` (EU)
+- Use Intl.NumberFormat in frontend for formatting
+- Store locale preference per tenant
+
+## Testing
+
+### Test Mode
+- Use payment provider's test mode for development
+- Test cards: successful charges, declined cards, 3D Secure
+- Test webhooks with provider's CLI tools
+- Never use real payment methods in development
+
+### Edge Cases to Test
+- Payment failure during subscription renewal
+- Plan upgrade/downgrade mid-cycle
+- Refund after partial usage
+- Subscription cancellation with immediate vs end-of-period
+- Webhook delivery failures and retries
+- Currency conversion edge cases

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/saas-builder/steering/implementation-patterns.md

@@ -0,0 +1,156 @@
+---
+inclusion: always
+---
+
+# Implementation Patterns
+
+## Frontend Stack
+- React with TypeScript (strict mode)
+- Tailwind CSS for styling
+- Functional components with hooks only
+
+## API Design
+
+### RESTful Conventions
+- Use plural nouns for collections: `/api/v1/users`, `/api/v1/users/{id}`
+- HTTP methods: GET (retrieve), POST (create), PUT/PATCH (update), DELETE (delete)
+- Version APIs: `/v1/`, `/v2/`
+- Avoid RPC-style endpoints like `/doEverything`
+- Use query parameters for filtering, not custom endpoints
+
+### Request/Response Models
+- Define schemas in `schema/` (language-agnostic format preferred)
+- Validate at API boundary with appropriate validation library
+- Success: Return JSON object or array
+- Error: `{ "error": { "code": "...", "message": "..." } }`
+- Never expose internal database fields directly
+- Document with OpenAPI specification
+
+### Error Handling
+- Use proper HTTP status codes:
+  - 400: Client input errors
+  - 401/403: Auth errors
+  - 404: Not found
+  - 500: Server errors
+- Log errors internally (CloudWatch), return friendly messages to clients
+- Implement global exception handlers
+- Never leak stack traces or raw exceptions
+
+### Authentication & Authorization
+- Require auth on all endpoints (except rare public ones)
+- Use JWTs or OAuth tokens (Auth0, AWS Cognito)
+- Verify tokens in Lambda authorizer
+- Lambda authorizer injects tenant ID and user roles into request context
+- Use scopes/roles for sensitive operations
+- Enforce tenant context for data segregation
+- Never rely on client-side auth checks
+- Never accept tenant ID from request body - only from authorizer
+
+### Pagination & Filtering
+- Enforce pagination for large lists
+- Use `?page=` and `?pageSize=` or cursor-based `?nextToken=`
+- Provide filters: `/orders?status=pending&created_after=2024-01-01`
+- Refuse to return extremely large payloads
+- All queries automatically scoped to tenant (no cross-tenant results)
+
+### Rate Limiting
+- Use API Gateway throttling quotas per tenant
+- Document limits to users
+- Protect expensive operations with application-level limits
+- Degrade gracefully under load
+- Consider per-tenant rate limits based on subscription tier
+
+### Usage Tracking & Metering
+- Track billable events at API boundary
+- Publish usage events to EventBridge for billing system
+- Include tenant ID, user ID, operation type, timestamp
+- Check tenant quota before expensive operations
+- Return 429 (Too Many Requests) when quota exceeded
+
+## AWS Patterns
+
+### DynamoDB
+- Composite keys: `pk: ${tenantId}#${entityType}#${id}`, `sk: metadata | #{relationType}#${relatedId}`
+- GSI for queries: `GSI1PK: ${tenantId}`, `GSI1SK: ${entityType}#${timestamp}`
+- Always prefix keys with tenant ID for isolation
+- Design access patterns upfront to minimize queries
+- Use appropriate SDK for your backend language
+
+### Lambda Functions
+- Multi-Tenant Pattern
+Every Lambda function should follow this pattern:
+
+1. **Extract tenant context** from authorizer claims (injected by Lambda authorizer)
+2. **Extract user roles** from authorizer claims
+3. **Validate required parameters** at function entry
+4. **Check user roles/permissions** before performing operations (RBAC)
+5. **Prefix all database operations** with tenant ID
+6. **Return proper HTTP status codes** (403 for unauthorized, etc.)
+7. **Log errors with tenant context** for debugging
+8. **Never trust tenant ID from request body** - only from authorizer
+
+Example flow:
+```
+handler(event) {
+  tenantId = event.requestContext.authorizer.tenantId
+  userRoles = event.requestContext.authorizer.roles
+  
+  if (!hasRequiredRole(userRoles, 'admin')) {
+    return 403 Forbidden
+  }
+  
+  // All DB queries use tenantId prefix
+  result = db.get(pk: `${tenantId}#User#${userId}`)
+  
+  return 200 OK
+}
+```
+
+### Environment Configuration
+- Use environment variables for runtime config
+- Use AWS Secrets Manager for sensitive values
+- Never hard-code credentials or secrets
+
+## Frontend Code Style (React + TypeScript)
+
+### React Components
+- Functional components with hooks only
+- Keep under 100 lines when possible
+- TypeScript interfaces for props (strict mode)
+- Prefer local state over global state
+- Use Tailwind utility classes
+- Mobile-first responsive design
+
+### Naming Conventions
+- Components: PascalCase (`UserProfile.tsx`)
+- Hooks: camelCase with `use` prefix (`useAuth.ts`)
+- Files: Match component name
+
+### Multi-Tenant Frontend Patterns
+- Store tenant context in React Context or auth state
+- Include tenant ID in all API requests (from auth token)
+- Handle tenant-specific branding/theming
+- Support feature flags for tenant-specific features
+- Display tenant-scoped data only
+- Handle quota exceeded errors gracefully (show upgrade prompts)
+
+### Frontend Best Practices
+- Descriptive variable names (self-documenting)
+- Proper error handling with try-catch
+- Avoid comments - code should be self-documenting
+- Only comment complex logic when necessary
+
+## Backend Code Style (Language-Agnostic)
+
+### General Principles
+- Descriptive variable and function names
+- Proper error handling
+- Structured logging (errors only, with context)
+- Consistent terminology across codebase
+- Follow language-specific conventions (PEP8 for Python, etc.)
+
+### Libraries & Dependencies
+- Minimize third-party libraries
+- Prefer AWS SDKs and built-in language features
+- Pin versions to avoid breakages
+- Use libraries packaged in Lambda runtime when possible

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/saas-builder/steering/repository-structure.md

@@ -0,0 +1,132 @@
+---
+inclusion: always
+---
+
+# Repository Structure
+
+## Root Layout
+
+```
+/
+├── frontend/          # React + TypeScript + Tailwind
+├── backend/           # Serverless functions (language-agnostic)
+├── schema/            # Shared API contracts and types
+├── .kiro/             # Kiro configuration
+└── README.md          # Project documentation
+```
+
+## frontend/
+
+React + TypeScript + Tailwind CSS application (Vite or Next.js)
+
+```
+frontend/
+├── src/
+│   ├── features/          # Feature-oriented structure (e.g., billing/, auth/)
+│   ├── components/        # Shared UI components
+│   ├── hooks/             # Custom React hooks
+│   ├── utils/             # Helper functions
+│   └── styles/            # Tailwind config and global CSS
+```
+
+### Conventions
+- PascalCase for components: `UserProfile.tsx`
+- camelCase for hooks: `useAuth.ts`, `useTenant.ts`
+- Import types from `schema/` - never duplicate
+- Store API URLs in `.env` files - never commit secrets
+- Feature-oriented structure: group by domain (e.g., `features/billing/`, `features/tenants/`)
+- Tenant context available via React Context or auth state
+
+## backend/
+
+Serverless functions (language-agnostic: Python, Node.js, Go, Java, etc.)
+
+```
+backend/
+├── functions/         # Lambda function handlers
+│   ├── authorizer/    # Lambda authorizer (validates JWT, injects tenant context)
+│   ├── api/           # API endpoint handlers
+│   ├── billing/       # Usage tracking and metering functions
+│   └── admin/         # Tenant management functions
+├── lib/               # Business logic modules (or services/)
+│   ├── auth/          # RBAC and permission checks
+│   ├── tenants/       # Tenant isolation logic
+│   └── usage/         # Usage metering utilities
+├── db/                # Data access layer (tenant-aware queries)
+└── infrastructure/    # IaC (CDK, SAM, Terraform)
+    ├── api.yaml       # API Gateway definition
+    ├── database.yaml  # DynamoDB tables
+    └── auth.yaml      # Cognito/Auth0 config
+```
+
+### Conventions
+- Follow language-specific conventions (PEP8 for Python, etc.)
+- Import schemas from `schema/` for validation
+- Keep handlers thin - business logic in `lib/` or `services/`
+- Stateless design - no global state
+- Consistent naming with frontend (e.g., both use "Order", not "Order" vs "Purchase")
+- All functions extract tenant context from authorizer claims
+- All database operations prefixed with tenant ID
+
+## schema/
+
+Shared API contracts and types (language-agnostic)
+
+```
+schema/
+├── openapi.yaml       # API specification (primary source of truth)
+├── types/             # Generated or shared types
+│   ├── User.ts        # TypeScript types for frontend
+│   ├── Tenant.ts
+│   └── Subscription.ts
+└── events/            # Event schemas for EventBridge
+    └── usage-events.json
+```
+
+### Conventions
+- Use OpenAPI spec as single source of truth
+- Generate language-specific types from OpenAPI (TypeScript for frontend, etc.)
+- No business logic - only structure
+- Include tenant-related models (Tenant, Subscription, Usage)
+- Keep in sync with API implementation
+
+## Monorepo Setup (Optional)
+
+If using TypeScript/Node.js for backend, use Yarn Workspaces or PNPM:
+
+```json
+{
+  "workspaces": ["frontend", "backend", "schema"]
+}
+```
+
+For other backend languages, schema sharing happens via:
+- OpenAPI spec generation/consumption
+- Shared proto files (gRPC)
+- Code generation tools
+
+## Key Principles
+
+- Clean separation: frontend (UI), backend (logic), schema (contracts)
+- No duplication: API contracts defined once in `schema/`
+- Consistent naming across all layers
+- Multi-tenant by default: organize code by tenant-aware patterns
+- Optimize for low cost: static frontend, serverless backend
+- Use local emulators (DynamoDB Local, LocalStack) for development
+
+## SaaS-Specific Organization
+
+### Tenant Management
+- Authorizer function validates JWT and injects tenant context
+- Tenant CRUD operations in `backend/functions/admin/`
+- Tenant configuration cached in Lambda memory
+
+### Billing & Usage
+- Usage tracking functions in `backend/functions/billing/`
+- EventBridge events for metering in `schema/events/`
+- Quota enforcement at API Gateway and function level
+
+### Feature Flags
+- Tenant-specific feature flags stored in DynamoDB
+- Checked at API boundary or in business logic
+- Frontend consumes feature flags from API

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/sentry-automation/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: sentry-automation
+description: "Automate Sentry tasks via Rube MCP (Composio): manage issues/events, configure alerts, track releases, monitor projects and teams. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+---
+
+# Sentry Automation via Rube MCP
+
+Automate Sentry error tracking and monitoring operations through Composio's Sentry toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Sentry connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `sentry`
+- 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 `sentry`
+3. If connection is not ACTIVE, follow the returned auth link to complete Sentry OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Investigate Issues
+
+**When to use**: User wants to find, inspect, or triage error issues
+
+**Tool sequence**:
+1. `SENTRY_LIST_AN_ORGANIZATIONS_ISSUES` - List issues across the organization [Required]
+2. `SENTRY_GET_ORGANIZATION_ISSUE_DETAILS` - Get detailed info on a specific issue [Optional]
+3. `SENTRY_LIST_AN_ISSUES_EVENTS` - View individual error events for an issue [Optional]
+4. `SENTRY_RETRIEVE_AN_ISSUE_EVENT` - Get full event details with stack trace [Optional]
+5. `SENTRY_RETRIEVE_ISSUE_TAG_DETAILS` - Inspect tag distribution for an issue [Optional]
+
+**Key parameters**:
+- `organization_id_or_slug`: Organization identifier
+- `issue_id`: Numeric issue ID
+- `query`: Search query (e.g., `is:unresolved`, `assigned:me`, `browser:Chrome`)
+- `sort`: Sort order (`date`, `new`, `freq`, `priority`)
+- `statsPeriod`: Time window for stats (`24h`, `14d`, etc.)
+
+**Pitfalls**:
+- `organization_id_or_slug` is the org slug (e.g., 'my-org'), not the display name
+- Issue IDs are numeric; do not confuse with event IDs which are UUIDs
+- Query syntax uses Sentry's search format: `is:unresolved`, `assigned:me`, `!has:release`
+- Events within an issue can have different stack traces; inspect individual events for details
+
+### 2. Manage Project Issues
+
+**When to use**: User wants to view issues scoped to a specific project
+
+**Tool sequence**:
+1. `SENTRY_RETRIEVE_ORGANIZATION_PROJECTS` - List projects to find project slug [Prerequisite]
+2. `SENTRY_RETRIEVE_PROJECT_ISSUES_LIST` - List issues for a specific project [Required]
+3. `SENTRY_RETRIEVE_ISSUE_EVENTS_BY_ID` - Get events for a specific issue [Optional]
+
+**Key parameters**:
+- `organization_id_or_slug`: Organization identifier
+- `project_id_or_slug`: Project identifier
+- `query`: Search filter string
+- `statsPeriod`: Stats time window
+
+**Pitfalls**:
+- Project slugs are different from project display names
+- Always resolve project names to slugs via RETRIEVE_ORGANIZATION_PROJECTS first
+- Project-scoped issue lists may have different pagination than org-scoped lists
+
+### 3. Configure Alert Rules
+
+**When to use**: User wants to create or manage alert rules for a project
+
+**Tool sequence**:
+1. `SENTRY_RETRIEVE_ORGANIZATION_PROJECTS` - Find project for the alert [Prerequisite]
+2. `SENTRY_RETRIEVE_PROJECT_RULES_BY_ORG_AND_PROJECT_ID` - List existing rules [Optional]
+3. `SENTRY_CREATE_PROJECT_RULE_FOR_ALERTS` - Create a new alert rule [Required]
+4. `SENTRY_CREATE_ORGANIZATION_ALERT_RULE` - Create org-level metric alert [Alternative]
+5. `SENTRY_UPDATE_ORGANIZATION_ALERT_RULES` - Update existing alert rules [Optional]
+6. `SENTRY_RETRIEVE_ALERT_RULE_DETAILS` - Inspect specific alert rule [Optional]
+7. `SENTRY_GET_PROJECT_RULE_DETAILS` - Get project-level rule details [Optional]
+
+**Key parameters**:
+- `name`: Alert rule name
+- `conditions`: Array of trigger conditions
+- `actions`: Array of actions to perform when triggered
+- `filters`: Array of event filters
+- `frequency`: How often to trigger (in minutes)
+- `actionMatch`: 'all', 'any', or 'none' for condition matching
+
+**Pitfalls**:
+- Project-level rules (CREATE_PROJECT_RULE) and org-level metric alerts (CREATE_ORGANIZATION_ALERT_RULE) are different
+- Conditions, actions, and filters use specific JSON schemas; check Sentry docs for valid types
+- `frequency` is in minutes; setting too low causes alert fatigue
+- `actionMatch` defaults may vary; explicitly set to avoid unexpected behavior
+
+### 4. Manage Releases
+
+**When to use**: User wants to create, track, or manage release versions
+
+**Tool sequence**:
+1. `SENTRY_LIST_ORGANIZATION_RELEASES` - List existing releases [Optional]
+2. `SENTRY_CREATE_RELEASE_FOR_ORGANIZATION` - Create a new release [Required]
+3. `SENTRY_UPDATE_RELEASE_DETAILS_FOR_ORGANIZATION` - Update release metadata [Optional]
+4. `SENTRY_CREATE_RELEASE_DEPLOY_FOR_ORG` - Record a deployment for a release [Optional]
+5. `SENTRY_UPLOAD_RELEASE_FILE_TO_ORGANIZATION` - Upload source maps or files [Optional]
+
+**Key parameters**:
+- `version`: Release version string (e.g., '1.0.0', commit SHA)
+- `projects`: Array of project slugs this release belongs to
+- `dateReleased`: Release timestamp (ISO 8601)
+- `environment`: Deployment environment name (e.g., 'production', 'staging')
+
+**Pitfalls**:
+- Release versions must be unique within an organization
+- Releases can span multiple projects; use the `projects` array
+- Deploying a release is separate from creating it; use CREATE_RELEASE_DEPLOY
+- Source map uploads require the release to exist first
+
+### 5. Monitor Organization and Teams
+
+**When to use**: User wants to view org structure, teams, or member lists
+
+**Tool sequence**:
+1. `SENTRY_GET_ORGANIZATION_DETAILS` or `SENTRY_GET_ORGANIZATION_BY_ID_OR_SLUG` - Get org info [Required]
+2. `SENTRY_LIST_TEAMS_IN_ORGANIZATION` - List all teams [Optional]
+3. `SENTRY_LIST_ORGANIZATION_MEMBERS` - List org members [Optional]
+4. `SENTRY_GET_PROJECT_LIST` - List all accessible projects [Optional]
+
+**Key parameters**:
+- `organization_id_or_slug`: Organization identifier
+- `cursor`: Pagination cursor for large result sets
+
+**Pitfalls**:
+- Organization slugs are URL-safe identifiers, not display names
+- Member lists may be paginated; follow cursor pagination
+- Team and member visibility depends on the authenticated user's permissions
+
+### 6. Manage Monitors (Cron Monitoring)
+
+**When to use**: User wants to update cron job monitoring configuration
+
+**Tool sequence**:
+1. `SENTRY_UPDATE_A_MONITOR` - Update monitor configuration [Required]
+
+**Key parameters**:
+- `organization_id_or_slug`: Organization identifier
+- `monitor_id_or_slug`: Monitor identifier
+- `name`: Monitor display name
+- `schedule`: Cron schedule expression or interval
+- `checkin_margin`: Grace period in minutes for late check-ins
+- `max_runtime`: Maximum expected runtime in minutes
+
+**Pitfalls**:
+- Monitor slugs are auto-generated from the name; use slug for API calls
+- Schedule changes take effect immediately
+- Missing check-ins trigger alerts after the margin period
+
+## Common Patterns
+
+### ID Resolution
+
+**Organization name -> Slug**:
+```
+1. Call SENTRY_GET_ORGANIZATION_DETAILS
+2. Extract slug field from response
+```
+
+**Project name -> Slug**:
+```
+1. Call SENTRY_RETRIEVE_ORGANIZATION_PROJECTS
+2. Find project by name, extract slug
+```
+
+### Pagination
+
+- Sentry uses cursor-based pagination with `Link` headers
+- Check response for cursor values
+- Pass cursor in next request until no more pages
+
+### Search Query Syntax
+
+- `is:unresolved` - Unresolved issues
+- `is:resolved` - Resolved issues
+- `assigned:me` - Assigned to current user
+- `assigned:team-slug` - Assigned to a team
+- `!has:release` - Issues without a release
+- `first-release:1.0.0` - Issues first seen in release
+- `times-seen:>100` - Seen more than 100 times
+- `browser:Chrome` - Filter by browser tag
+
+## Known Pitfalls
+
+**ID Formats**:
+- Organization: use slug (e.g., 'my-org'), not display name
+- Project: use slug (e.g., 'my-project'), not display name
+- Issue IDs: numeric integers
+- Event IDs: UUIDs (32-char hex strings)
+
+**Permissions**:
+- API token scopes must match the operations being performed
+- Organization-level operations require org-level permissions
+- Project-level operations require project access
+
+**Rate Limits**:
+- Sentry enforces per-organization rate limits
+- Implement backoff on 429 responses
+- Bulk operations should be staggered
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List org issues | SENTRY_LIST_AN_ORGANIZATIONS_ISSUES | organization_id_or_slug, query |
+| Get issue details | SENTRY_GET_ORGANIZATION_ISSUE_DETAILS | organization_id_or_slug, issue_id |
+| List issue events | SENTRY_LIST_AN_ISSUES_EVENTS | issue_id |
+| Get event details | SENTRY_RETRIEVE_AN_ISSUE_EVENT | organization_id_or_slug, event_id |
+| List project issues | SENTRY_RETRIEVE_PROJECT_ISSUES_LIST | organization_id_or_slug, project_id_or_slug |
+| List projects | SENTRY_RETRIEVE_ORGANIZATION_PROJECTS | organization_id_or_slug |
+| Get org details | SENTRY_GET_ORGANIZATION_DETAILS | organization_id_or_slug |
+| List teams | SENTRY_LIST_TEAMS_IN_ORGANIZATION | organization_id_or_slug |
+| List members | SENTRY_LIST_ORGANIZATION_MEMBERS | organization_id_or_slug |
+| Create alert rule | SENTRY_CREATE_PROJECT_RULE_FOR_ALERTS | organization_id_or_slug, project_id_or_slug |
+| Create metric alert | SENTRY_CREATE_ORGANIZATION_ALERT_RULE | organization_id_or_slug |
+| Create release | SENTRY_CREATE_RELEASE_FOR_ORGANIZATION | organization_id_or_slug, version |
+| Deploy release | SENTRY_CREATE_RELEASE_DEPLOY_FOR_ORG | organization_id_or_slug, version |
+| List releases | SENTRY_LIST_ORGANIZATION_RELEASES | organization_id_or_slug |
+| Update monitor | SENTRY_UPDATE_A_MONITOR | organization_id_or_slug, monitor_id_or_slug |