chore: add Cursor IDE configuration and development tools

.cursor/BUGBOT.md

@@ -0,0 +1,85 @@
+# Code Review Guidance
+
+## Quick Reference
+
+Verify: code compiles, tests pass, JavaDoc updated, no generated code edits, proper exception handling, input validation, adequate test coverage.
+
+## Code Quality Review
+
+### Documentation
+- Update JavaDoc near changed code. Include `@throws` for all exceptions. Use `<pre>{@code ... }</pre>` for public API examples. Document parameter constraints and validation rules. JavaDoc must describe actual behavior, not intended behavior.
+- All public methods/classes/interfaces need complete JavaDoc. Provide examples for complex APIs. Document parameters and return values clearly.
+
+### Exception Handling
+- Use custom exceptions from `io.pinecone.exceptions`: `PineconeValidationException` for invalid inputs, `PineconeBadRequestException` for bad requests. Avoid generic exceptions.
+- Error messages must be descriptive, actionable, and reference docs when appropriate. When wrapping exceptions, preserve cause: `new Exception(message, cause)`.
+- Map HTTP status codes to exceptions using `HttpErrorMapper` patterns. Ensure consistent error handling.
+
+### Validation
+- Validate inputs early in public methods. Throw `PineconeValidationException` with clear messages. Use static validation methods (e.g., `validatePodIndexParams`) for reusable logic. Explicitly check null and empty strings.
+- Handle edge cases (null, empty, max values) with appropriate error messages.
+
+### Code Generation
+- Never edit `org.openapitools.*` files directly. Update source OpenAPI/Proto files in `codegen/` and regenerate. Verify regeneration results.
+
+### Testing
+- Capture all major requirements as tests. Unit tests cover validation and error paths. Integration tests cover end-to-end workflows (sparingly). Test success and failure scenarios including edge cases. Use descriptive test method names.
+- Tests must be readable, maintainable, follow coding standards, avoid unnecessary complexity, use mocks appropriately.
+
+### Thread Safety
+- Identify shared mutable state (e.g., `ConcurrentHashMap` for connections). Document thread-safety guarantees in JavaDoc. Use thread-safe collections for shared data. Verify concurrent access is safe.
+
+### Resource Management
+- Reuse `OkHttpClient` instances. Document resource lifecycle in JavaDoc. Ensure cleanup in error scenarios. Verify no resource leaks in normal and error paths.
+
+### Code Style
+- Code must be readable, follow Java idioms, prefer clarity over cleverness. Use descriptive names. Break up files over 800 lines. Classes should have single responsibility.
+- Avoid breaking public interfaces. If unavoidable, provide migration path and deprecation strategy. Document breaking changes in PR description.
+
+## Pull Request Review
+
+### PR Title and Description
+- Title: Use Conventional Commits 1.0.0 format (e.g., `fix: handle null pointer exception in query method`). Clearly describe PR purpose.
+- Description: Problem and solution, GitHub/Linear issue references, usage examples, value summary (concise), relevant links.
+
+### Code Changes
+- Scope: Single concern per PR. Focused changes. Separate unrelated changes.
+- Backward compatibility: Maintain when possible. Document and justify breaking changes. Add deprecation warnings for removed functionality.
+- Dependencies: No unnecessary additions. Justify and document new dependencies. Ensure version compatibility.
+
+## Common Issues
+
+- Missing null checks (especially public APIs)
+- Incomplete error handling
+- Missing tests for new functionality
+- Outdated JavaDoc
+- Resource leaks (use try-with-resources, not manual close())
+- Thread safety violations
+- Breaking changes without notice
+- Editing generated code directly
+- String comparison with `==` (use `.equals()`)
+- Exception swallowing (log or rethrow, avoid empty catch blocks)
+- Incorrect `equals()/hashCode()` (implement together, critical for collections)
+- Collection modification during iteration (use `iterator.remove()` or collect first)
+- Mutable objects as map keys (ensure immutability or proper `hashCode()`)
+- String concatenation in loops (use `StringBuilder`, not `+`)
+- Raw types instead of generics (use `List<String>`, not `List`)
+- Incorrect Optional usage (don't use for null checks when null is valid; don't use as method parameters)
+- Not preserving exception cause (use `new Exception(message, cause)`)
+- Date/time API misuse (use `java.time.*`, not `java.util.Date`/`Calendar`)
+- Boxing/unboxing overhead (prefer primitives in performance-critical code)
+- Incorrect synchronization (avoid synchronizing on non-final objects or String literals)
+- Memory leaks with listeners (remove listeners/callbacks/observers)
+- Not validating collection contents (validate elements, not just reference)
+- Object comparison with `==` (use `.equals()`)
+- Ignoring checked exceptions (handle or rethrow, avoid `catch (Exception e) { /* ignore */ }`)
+
+## Review Focus by Change Type
+
+**Bug Fixes**: Address root cause, not symptoms. No regressions. Handle related edge cases. Tests demonstrate fix.
+
+**New Features**: Complete and functional. Well-designed public API with documentation. Tests cover happy path and errors. No breaking changes unless intentional.
+
+**Refactoring**: Behavior unchanged (verify with tests). More maintainable/readable. No performance regressions. Update docs if needed.
+
+**Performance Improvements**: Measurable and significant. No correctness regressions. Tests verify improvement. Document trade-offs.

.cursor/commands/create-bug.md

@@ -0,0 +1,31 @@
+# create-bug
+
+Create a Linear issue for this work in the "SDK Maintenance" project.
+
+Give the issue these labels:
+- sdk:java
+- Bug
+
+Include the plan and any relevant context in the issue description.
+
+If the plan was made to address a GitHub issue, be sure to include a link to the original GitHub issue in the description.
+
+Every Linear issue created should include these additional instructions at the end of the description.
+
+```
+When the planned code changes are complete, the agent should take the following steps:
+
+1. **Code Quality Review**
+   - Review JavaDoc strings near the changed code to ensure they are still up to date
+   - Ensure the code compiles and that unit tests pass
+   - Ensure changes are adequately tested
+
+2. **Create Pull Request**
+   - Create a PR in draft mode
+   - Rename the PR with a title that follows the Conventional Commits 1.0.0 format
+   - Update the PR description with:
+     - A clear description of the problem and solution
+     - A reference to the related Github issue, if any, as well as the Linear issue number.
+     - Examples showing how to use the code that was changed
+     - A summary of the value and approach taken in the work (without overwhelming detail - reviewers can read the code for specifics)
+```

.cursor/commands/create-improvement.md

@@ -0,0 +1,31 @@
+# create-improvement
+
+Create a Linear issue for this work in the "SDK Maintenance" project.
+
+Give the issue these labels:
+- sdk:java
+- Improvement
+
+Include the plan and any relevant context in the issue description.
+
+If the plan was made to address a GitHub issue, be sure to include a link to the original GitHub issue in the description.
+
+Every Linear issue created should include these additional instructions at the end of the description.
+
+```
+When the planned code changes are complete, the agent should take the following steps:
+
+1. **Code Quality Review**
+   - Review JavaDoc strings near the changed code to ensure they are still up to date
+   - Ensure the code compiles and that unit tests pass
+   - Ensure changes are adequately tested
+
+2. **Create Pull Request**
+   - Create a PR in draft mode
+   - Rename the PR with a title that follows the Conventional Commits 1.0.0 format
+   - Update the PR description with:
+     - A clear description of the problem and solution
+     - A reference to the related Github issue, if any, as well as the Linear issue number.
+     - Examples showing how to use the code that was changed
+     - A summary of the value and approach taken in the work (without overwhelming detail - reviewers can read the code for specifics)
+```

.cursor/commands/create-subplan.md

@@ -0,0 +1,15 @@
+# create-subplan
+
+Create a detailed implementation plan focused on a specific feature or change.
+
+Make sure the plan includes:
+- Consideration for performance, security, maintainability
+- The proposed changes should avoid breaking changes to public interfaces
+- If breaking changes are unavoidable, include a migration path and deprecation strategy
+- The proposed changes should ideally preserve flexibility/extensibility for future changes
+- The proposed changes should follow Java idioms and best practices
+- Error handling strategy and exception design
+- All changes should be thoroughly tested:
+    - Use unit tests for the bulk of testing, including errors and edge cases. 
+    - Use integration tests sparingly to confirm a feature is working end-to-end but without delving into all edge cases.
+- All interfaces need high-quality JavaDoc strings

.cursor/commands/github-triage.md

@@ -0,0 +1,141 @@
+# github-triage
+
+Quick triage and routing of GitHub issues. This is the **first step** for handling new or updated GitHub issues.
+
+**IMPORTANT: This command must be idempotent.** Before taking any action, check the current state to avoid duplicates:
+
+- Check if a Linear issue already exists for this GitHub issue (search by GitHub issue URL or number)
+- Check if comments requesting information have already been posted
+- Check if the issue has already been closed
+- Check existing labels before adding or removing any
+
+**When to use this command:**
+- Initial triage of new GitHub issues
+- Quick assessment and routing
+- Requesting missing information
+- Managing issue lifecycle (labels, closing stale issues)
+
+**When NOT to use this command:**
+- For deep code analysis or root cause investigation (use `investigate-github-issue` instead)
+- When you need to understand complex technical details before routing
+
+## Triage Process
+
+1. **Categorize the issue**
+   - Determine if it's a bug, feature request, question, documentation issue, or other
+   - Assess priority based on severity, impact, and user needs (surface-level assessment)
+   - Check if it's a duplicate of existing issues (GitHub or Linear)
+   - **Update labels**: Ensure appropriate labels are applied:
+     - Type labels: `bug`, `enhancement`, `question`, `documentation`, etc.
+     - Status labels: `needs-info`, `needs-reproduction`, `needs-investigation`, `in-progress`, etc.
+     - Priority labels: `priority:high`, `priority:medium`, `priority:low`, etc.
+     - Component/area labels if applicable
+     - **Check first**: Review existing labels before adding new ones
+     - **Only add**: Labels that are missing and appropriate
+     - **Remove**: Incorrect or outdated labels (e.g., remove `needs-info` if information has been provided)
+
+2. **Extract key information**
+   - Summarize the problem or request clearly
+   - Identify affected components or areas of the codebase (high-level)
+   - Note any relevant context (OS, Java version, SDK version, etc.)
+   - Extract any code examples or error messages
+
+3. **Quick verification**
+   - **Check first**: Review existing comments to see if verification has already been attempted
+   - For bug reports: Do a quick check if the issue seems reproducible based on provided information
+   - If reproduction seems straightforward and information is complete, note this
+   - If the issue is complex, unclear, or needs deeper analysis, add `needs-investigation` label
+   - **Update labels**: 
+     - Add `needs-reproduction` if reproduction steps are missing or unclear
+     - Add `needs-investigation` if deeper technical analysis is needed
+     - Remove `needs-reproduction` if reproduction steps are clear and complete
+
+4. **Request additional information (if needed)**
+   - **Check first**: Review existing comments to see if information has already been requested
+   - **Skip if**: A similar information request comment already exists from a maintainer
+   - If key information is missing (version, OS, code example, error logs, etc.), draft a response requesting:
+     - Specific details needed to reproduce or understand the issue
+     - Code examples or minimal reproduction cases
+     - Error messages or stack traces
+     - Environment details (Java version, SDK version, OS, etc.)
+   - Be polite, specific, and helpful in the request
+   - **Update labels**: Add `needs-info` label if not already present
+
+5. **Handle incomplete issues**
+   - **Check first**: Verify the issue is still open (don't attempt to close if already closed)
+   - **Check first**: Verify that an information request was made and enough time has passed
+   - **Skip if**: The issue has already been closed for this reason
+   - If an issue has been open for an extended period without the requested information:
+     - Check if enough time has passed since the information request
+     - Draft a closing comment explaining why the issue is being closed
+     - Offer to reopen if the information becomes available
+     - Close the issue with an appropriate label (e.g., "needs-info", "stale")
+
+6. **Route to next step**
+   - **Check first**: Search Linear for an existing issue linked to this GitHub issue before creating a new one
+   - **Skip if**: A Linear issue already exists for this GitHub issue
+   - **Route based on issue state:**
+     - **Clear bug with reproduction steps**: Create Linear bug issue using `create-bug` command
+     - **Clear feature request**: Create Linear improvement issue using `create-improvement` command
+     - **Needs investigation** (complex, unclear root cause, or needs code analysis): 
+       - Add `needs-investigation` label
+       - Recommend using `investigate-github-issue` command for deep analysis
+     - **Question**: Provide a helpful answer or direct to documentation (only if not already answered)
+     - **Missing information**: Wait for user response (already handled in step 4)
+
+7. **Link tracking**
+   - Always include the GitHub issue URL when creating Linear issues
+   - Maintain bidirectional references between GitHub and Linear
+   - If a Linear issue already exists, update it with any new information rather than creating a duplicate
+
+## Workflow Integration
+
+**Typical workflow:**
+1. Run `github-triage` for initial assessment and routing
+2. If triage determines `needs-investigation`, run `investigate-github-issue` for deep analysis
+3. Based on investigation results, create appropriate Linear issues (`create-bug`, `create-improvement`, or `create-investigation`)
+
+**When multiple issues are provided**, prioritize them and suggest a triage order based on:
+- Severity and user impact
+- Dependencies between issues
+- Effort required to resolve
+
+## Batch Processing Workflow
+
+To triage all GitHub issues iteratively:
+
+### Option 1: Manual Iteration
+1. Fetch a list of open GitHub issues (use GitHub CLI or API):
+   ```bash
+   gh issue list --state open --limit 100
+   ```
+2. For each issue, invoke this command with the issue URL or number:
+   - Provide the GitHub issue URL: `https://github.com/owner/repo/issues/123`
+   - Or provide the issue number and repository context
+3. Process issues one at a time, allowing the command to be idempotent (it will skip already-processed issues)
+
+### Option 2: Automated Batch Processing
+When processing multiple issues:
+1. **Fetch all open issues** first (using GitHub API or CLI)
+2. **Prioritize the list** based on:
+   - Issues without labels (untriaged)
+   - Issues with `needs-info` that have received responses
+   - Issues with `needs-reproduction` that now have reproduction steps
+   - Recently updated issues
+   - High-priority labels
+3. **Process in batches** (e.g., 5-10 at a time) to avoid overwhelming the system
+4. **Review results** after each batch before proceeding
+
+### Option 3: Focused Triage
+To triage specific subsets:
+- **Untriaged issues**: `gh issue list --label "status:needs-triage" --state open`
+- **Issues needing info**: `gh issue list --label "needs-info" --state open`
+- **Issues needing reproduction**: `gh issue list --label "needs-reproduction" --state open`
+- **Recently updated**: `gh issue list --state open --limit 20 --sort updated`
+
+### Best Practices for Batch Triage
+- Start with untriaged issues (no status labels)
+- Process high-priority issues first
+- Review the command output for each issue to ensure proper routing
+- If an issue needs investigation, mark it and move on (investigate separately)
+- Keep a log of issues that need follow-up (e.g., waiting for user response)