diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md
new file mode 100644
index 00000000..24e512ff
--- /dev/null
+++ b/.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.
diff --git a/.cursor/commands/create-bug.md b/.cursor/commands/create-bug.md
new file mode 100644
index 00000000..39a0bfb3
--- /dev/null
+++ b/.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)
+```
\ No newline at end of file
diff --git a/.cursor/commands/create-improvement.md b/.cursor/commands/create-improvement.md
new file mode 100644
index 00000000..d89e327a
--- /dev/null
+++ b/.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)
+```
\ No newline at end of file
diff --git a/.cursor/commands/create-subplan.md b/.cursor/commands/create-subplan.md
new file mode 100644
index 00000000..15c296e2
--- /dev/null
+++ b/.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
\ No newline at end of file
diff --git a/.cursor/commands/github-triage.md b/.cursor/commands/github-triage.md
new file mode 100644
index 00000000..06bcbd22
--- /dev/null
+++ b/.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)
\ No newline at end of file
diff --git a/.cursor/commands/investigate-github-issue.md b/.cursor/commands/investigate-github-issue.md
new file mode 100644
index 00000000..f4cb3e50
--- /dev/null
+++ b/.cursor/commands/investigate-github-issue.md
@@ -0,0 +1,158 @@
+# investigate-github-issue
+
+Conduct a thorough, deep investigation of a GitHub issue to understand root causes, verify behavior, and produce actionable next steps.
+
+**When to use this command:**
+- After `github-triage` has determined the issue needs investigation (has `needs-investigation` label)
+- When you need to understand root causes before creating a fix plan
+- When an issue is complex or unclear and needs code analysis
+- When you need to assess impact and scope before prioritizing
+
+**When NOT to use this command:**
+- For initial triage (use `github-triage` instead)
+- For simple, clear-cut bugs with obvious fixes
+- For straightforward feature requests that don't need technical analysis
+
+**IMPORTANT: This command must be idempotent.** Before starting, check:
+- If a Linear investigation issue already exists for this GitHub issue
+- If an investigation has already been completed and documented
+- The current state of the GitHub issue (open/closed, labels, comments)
+- If `github-triage` has already been run (if not, run it first for proper labeling)
+
+## Investigation Process
+
+### 1. **Understand the Issue**
+   - Read the GitHub issue title, description, and all comments thoroughly
+   - Extract key information:
+     - Problem description and expected vs actual behavior
+     - Code examples, error messages, stack traces
+     - Environment details (Java version, SDK version, OS, dependencies)
+     - Steps to reproduce (if provided)
+     - Related issues or PRs mentioned
+   - Identify what type of issue this is (bug, feature request, question, etc.)
+   - Note any ambiguity or missing information
+
+### 2. **Codebase Analysis**
+   - Search for relevant code using semantic search:
+     - Identify components/modules mentioned in the issue
+     - Find code paths that handle the described functionality
+     - Locate error handling or validation logic related to the issue
+     - Find tests that might be relevant
+   - Read and analyze the relevant source code:
+     - Understand the current implementation
+     - Identify potential root causes
+     - Check for similar patterns or related code
+     - Review error handling and edge cases
+   - Check test coverage:
+     - Find existing tests for the affected functionality
+     - Identify gaps in test coverage
+     - Review test cases that might be related
+
+### 3. **Reproduction and Verification**
+   - **Note**: This is deeper than triage-level verification. Focus on understanding the technical conditions.
+   - If reproduction steps are provided:
+     - Trace through the code paths that would be executed during reproduction
+     - Analyze the code to understand what conditions are required
+     - Identify edge cases or specific configurations needed
+     - Document the exact code flow that leads to the issue
+   - If reproduction steps are missing:
+     - Analyze the code to determine what minimal information would be needed
+     - Suggest specific reproduction cases based on code analysis
+     - Identify what code paths need to be exercised
+   - Check for similar issues:
+     - Search GitHub issues for similar problems
+     - Check Linear for related investigations or bugs
+     - Look for patterns across multiple issues
+     - Analyze if this is part of a broader problem
+
+### 4. **Root Cause Analysis**
+   - Analyze the code to identify potential causes:
+     - Logic errors or bugs
+     - Missing validation or error handling
+     - Race conditions or concurrency issues
+     - API contract violations
+     - Configuration or environment issues
+   - Consider edge cases:
+     - Boundary conditions
+     - Error scenarios
+     - Integration points
+   - Review related code:
+     - Dependencies and how they interact
+     - Recent changes that might have introduced the issue
+     - Design decisions that might be relevant
+
+### 5. **Impact Assessment**
+   - Determine the severity and scope:
+     - How many users might be affected?
+     - Is this a regression or a long-standing issue?
+     - What's the impact on functionality?
+   - Identify affected areas:
+     - Which components/modules are involved?
+     - Are there related features that might be affected?
+     - What are the dependencies?
+
+### 6. **Document Findings**
+   Create a comprehensive investigation report that includes:
+
+   **Summary**
+   - Brief overview of the issue
+   - Type of issue (bug, feature request, etc.)
+   - Severity assessment
+
+   **Analysis**
+   - Key findings from codebase analysis
+   - Root cause hypothesis (if identified)
+   - Relevant code references with explanations
+   - Related issues or patterns found
+
+   **Reproduction Status**
+   - Can the issue be reproduced? (Yes/No/Needs Info)
+   - Reproduction steps (if available or if created)
+   - What information is still needed (if any)
+
+   **Impact**
+   - Severity and scope
+   - Affected components
+   - User impact
+
+   **Next Steps**
+   - Recommended actions:
+     - If bug: Create Linear bug issue with fix plan using the create-bug command
+     - If feature: Create Linear improvement issue with implementation plan via the create-improvement command
+     - If needs more info: Document what's needed and suggest follow-up
+     - If question: Provide answer or documentation reference
+   - Suggested priority
+   - Estimated effort (if determinable)
+   - Dependencies or blockers
+
+### 8. **Update GitHub Issue (If Appropriate)**
+   - If new information was discovered, consider adding a comment:
+     - Share key findings and root cause analysis
+     - Provide code references with explanations
+     - Suggest next steps and recommended actions
+     - Request additional information if needed (only if not already requested in triage)
+   - Update labels if investigation reveals new information:
+     - Remove `needs-investigation` if investigation is complete
+     - Add `reproduced` if reproduction was successful
+     - Update priority labels if impact assessment changed
+   - Only comment if it adds value and hasn't been covered in existing comments
+
+## Output Format
+
+The investigation should produce a structured report that can be:
+- Used to create a Linear issue (if needed)
+- Used as a basis for creating bug or improvement issues (preferred if investigation is complete)
+- Shared with the team for decision-making
+- Referenced when implementing fixes
+
+Focus on actionable insights and clear next steps rather than just summarizing the issue.
+
+## Workflow Integration
+
+**This command typically follows `github-triage`:**
+1. `github-triage` → Quick assessment, labels issue as `needs-investigation`
+2. `investigate-github-issue` → Deep analysis (this command)
+3. Based on findings → Create Linear issue (`create-bug`, `create-improvement`, or `create-investigation`)
+
+**This command can also be used standalone** when you already know an issue needs deep investigation.
+
diff --git a/.cursor/commands/list-github-issues.md b/.cursor/commands/list-github-issues.md
new file mode 100644
index 00000000..53905026
--- /dev/null
+++ b/.cursor/commands/list-github-issues.md
@@ -0,0 +1,57 @@
+# list-github-issues
+
+List GitHub issues for batch triage or review. This helper command fetches issues and prepares them for processing with `github-triage`.
+
+## Usage
+
+This command helps you get a list of GitHub issues to process. You can then use the issue URLs/numbers with `github-triage` for iterative processing.
+
+## Output Format
+
+The command should provide:
+- Issue numbers and URLs
+- Current labels (especially status labels)
+- Last updated date
+- Issue title
+- Priority suggestion based on labels and recency
+
+## Filtering Options
+
+When listing issues, consider filtering by:
+- **State**: `open`, `closed`
+- **Labels**: `status:needs-triage`, `needs-info`, `needs-reproduction`, `needs-investigation`
+- **Sort order**: `created`, `updated`, `comments`
+- **Limit**: Number of issues to fetch (start with 20-50 for manageable batches)
+
+## Suggested Workflow
+
+1. **List untriaged issues**:
+   ```
+   List open issues with no status labels or with "status:needs-triage" label
+   ```
+
+2. **Prioritize the list**:
+   - Issues without any status labels (highest priority)
+   - Issues with `needs-info` that have new comments
+   - Issues with `needs-reproduction` that have new information
+   - Recently updated issues
+
+3. **Process iteratively**:
+   - Take the first N issues from the prioritized list
+   - For each issue, run `github-triage` with the issue URL/number
+   - Review results before proceeding to the next batch
+
+4. **Track progress**:
+   - Note which issues were processed
+   - Identify issues that need follow-up (investigation, waiting for info, etc.)
+   - Update your list to exclude already-processed issues
+
+## Integration with github-triage
+
+After listing issues, use the issue URLs/numbers with `github-triage`:
+- Provide issue URLs: `https://github.com/owner/repo/issues/123`
+- Or provide issue numbers with repository context
+- Process one at a time or in small batches
+
+The `github-triage` command is idempotent, so you can safely re-run it on issues that have already been processed.
+
diff --git a/.cursor/rules/best-practices.mdc b/.cursor/rules/best-practices.mdc
new file mode 100644
index 00000000..73967790
--- /dev/null
+++ b/.cursor/rules/best-practices.mdc
@@ -0,0 +1,42 @@
+---
+alwaysApply: true
+---
+
+## Documentation
+- When changing code, review nearby JavaDoc strings to ensure they are up to date
+- Include `@throws` tags in JavaDoc for all exceptions that methods can throw
+- Provide usage examples in JavaDoc using `<pre>{@code ... }</pre>` blocks for public APIs
+- Document parameter constraints and validation rules in JavaDoc
+
+## Exception Handling
+- Use appropriate custom exception types from `io.pinecone.exceptions` package (e.g., `PineconeValidationException`, `PineconeBadRequestException`)
+- Include descriptive error messages that help users understand what went wrong
+- When wrapping exceptions, preserve the original cause using the constructor that accepts `Throwable`
+- Map HTTP status codes to appropriate exception types using `HttpErrorMapper` patterns
+
+## Validation
+- Validate input parameters early in public methods, throwing `PineconeValidationException` for invalid inputs
+- Provide clear, actionable error messages that reference documentation when appropriate
+- Use static validation methods (like `validatePodIndexParams`) for complex validation logic that may be reused
+- Validate null and empty strings explicitly before use
+
+## Code Generation
+- Never manually edit files in `org.openapitools.*` packages - these are auto-generated
+- If changes are needed to generated code, update the source OpenAPI/Proto files in `codegen/` and regenerate
+
+## Testing
+- Ensure all major requirements are captured as test cases
+- Write unit tests for validation logic and error handling paths
+- Include integration tests for end-to-end workflows
+- Test both success and failure scenarios, including edge cases
+- Use descriptive test method names that clearly indicate what is being tested
+
+## Thread Safety
+- Be aware of shared mutable state (e.g., `ConcurrentHashMap` for connections)
+- Document thread-safety guarantees in JavaDoc for classes that maintain shared state
+- Use thread-safe collections when sharing data across threads
+
+## Resource Management
+- Reuse `OkHttpClient` instances rather than creating new ones for each request
+- Document resource lifecycle and cleanup requirements in JavaDoc
+- Ensure proper cleanup of connections and resources in error scenarios