From 9d8775b0a59d16f76ee1f8228d0bea1a2e494ac2 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 18:50:04 +0530
Subject: [PATCH 01/30] SK-2832 add Claude Code setup (CLAUDE.md, commands,
 workflows)

- Add CLAUDE.md with project conventions, version info, commit guidelines
- Add .claude/commands: code-review, code-smell, code-security, sdk-sample,
  test, commit (Jira-aware)
- Add .claude/hooks/checkstyle-on-edit.py for per-edit lint feedback
- Add .claude/settings.json with permissions and PostToolUse hook
- Add .claude/skills/requesting-code-review for context-fork reviews
- Add .github/workflows/claude-pr-review.yml: automated SDK + security review on PRs
- Add .github/workflows/claude-changelog.yml: auto-generated release notes on tag push
- Add .github/workflows/release-v1.yml: v1 public release targeting v1 branch
- Update .cspell.json with British English and project-specific terms

Requires ANTHROPIC_API_KEY secret in GitHub Actions for claude-* workflows.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/commands/code-review.md               | 107 ++++++++++++
 .claude/commands/code-security.md             |  69 ++++++++
 .claude/commands/code-smell.md                | 145 ++++++++++++++++
 .claude/commands/commit.md                    |  55 ++++++
 .claude/commands/sdk-sample.md                |  70 ++++++++
 .claude/commands/test.md                      |  73 ++++++++
 .claude/hooks/checkstyle-on-edit.py           |  19 +++
 .claude/settings.json                         |  30 ++++
 .../skills/requesting-code-review/SKILL.md    |  76 +++++++++
 .cspell.json                                  |  33 +++-
 .github/workflows/claude-changelog.yml        |  86 ++++++++++
 .github/workflows/claude-pr-review.yml        | 157 ++++++++++++++++++
 .github/workflows/release-v1.yml              |   0
 CLAUDE.md                                     | 148 +++++++++++++++++
 14 files changed, 1065 insertions(+), 3 deletions(-)
 create mode 100644 .claude/commands/code-review.md
 create mode 100644 .claude/commands/code-security.md
 create mode 100644 .claude/commands/code-smell.md
 create mode 100644 .claude/commands/commit.md
 create mode 100644 .claude/commands/sdk-sample.md
 create mode 100644 .claude/commands/test.md
 create mode 100644 .claude/hooks/checkstyle-on-edit.py
 create mode 100644 .claude/settings.json
 create mode 100644 .claude/skills/requesting-code-review/SKILL.md
 create mode 100644 .github/workflows/claude-changelog.yml
 create mode 100644 .github/workflows/claude-pr-review.yml
 create mode 100644 .github/workflows/release-v1.yml
 create mode 100644 CLAUDE.md

diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md
new file mode 100644
index 00000000..498fcfac
--- /dev/null
+++ b/.claude/commands/code-review.md
@@ -0,0 +1,107 @@
+---
+name: code-review
+description: Full code review — SDK patterns, naming, test coverage, then runs /code-smell and /code-security.
+paths:
+  - src/main/java/**/*.java
+  - src/test/java/**/*.java
+---
+
+You are a senior engineer performing a thorough code review on the Skyflow Java SDK.
+
+## Scope
+
+Use `$ARGUMENTS` to determine scope:
+- `full review` — scan all files under `src/main/java/com/skyflow/` recursively (exclude `generated/`)
+- A file or directory path — review only that path
+- Empty / default — review files changed on current branch vs `main`:
+  ```bash
+  git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+  ```
+
+**Skip entirely:** `src/main/java/com/skyflow/generated/` — Fern-generated REST client, read-only.
+
+---
+
+## Step 1 — SDK Pattern Review
+
+Check the files in scope against the rules below.
+
+### 1. Request / Response / Options patterns
+
+- Request builders are plain data holders — validation happens in `Validations.validateXxxRequest()` inside the controller, not in `build()`. Flag if validation logic is duplicated outside `Validations`.
+- Response getters returning `ArrayList<HashMap<String, Object>>` is the established SDK pattern — do not flag these as violations.
+- All response classes must have `getErrors()` returning `null` (not absent) when no errors.
+- No separate `*Options` classes exist — options are fields on the request builder itself.
+- SDK must not add field-level null/empty validation on top of what the backend enforces. Only structural checks (`table == null`, `values == null`) are permitted.
+
+### 2. Error handling
+
+- All public methods must declare `throws SkyflowException`
+- `SkyflowException` must be thrown (not swallowed) on invalid input
+- No `System.out.println` or bare `e.printStackTrace()` — use `LogUtil`
+- Catch blocks must not silently drop exceptions
+- `catch (Exception e)` without re-throw or explicit handling is a critical issue
+
+### 3. Naming conventions and response field normalisation
+
+Follow the conventions in CLAUDE.md under "Naming Conventions". Key enforcement points:
+- Acronyms as words: `skyflowId`, `tokenUri`, `clientId` — never uppercase abbreviations
+- Builder setters: `setFooId()` not `setFooID()`; constants: `UPPER_SNAKE_CASE`; classes: `PascalCase`
+- Response maps: `skyflowId` (camelCase) only — never `skyflow_id`; `getErrors()` must be present on every response class
+- Deprecated methods: `@Deprecated(since = "x.x", forRemoval = true)` + `@deprecated` Javadoc with `{@link}` to replacement
+
+### 5. Test coverage
+
+- Every public method must have at least one positive and one negative test
+- Tests must use `Assert.assertEquals` / `Assert.assertNull` — not just `Assert.fail` guards
+- No mocking of the production class under test
+- Reflection-based tests on private methods are acceptable only when no public API exercises the method
+
+### 6. Code quality
+
+- No magic strings for API field names — use `Constants` or `ErrorMessage` enums
+- No duplicate validation logic across request classes — belongs in `Validations`
+- No `@SuppressWarnings` without a comment explaining why
+- `LogUtil.printWarningLog` must be used for deprecation warnings, not `System.err`
+
+### Output for Step 1
+
+Group findings by file:
+
+```
+### path/to/File.java
+
+| Severity   | Line | Finding                                                    |
+|------------|------|------------------------------------------------------------|
+| Critical   | 42   | SkyflowException swallowed in catch block                  |
+| Bug        | 87   | skyflow_id not normalised to skyflowId                     |
+| Quality    | 103  | Magic string "records" — use Constants                     |
+```
+
+**Severities:**
+| Level | Meaning |
+|---|---|
+| **Critical** | Data loss, silent failure, security risk — must fix before merge |
+| **Bug** | Wrong behaviour, incorrect output — must fix before merge |
+| **Edge Case** | Unhandled input that will cause runtime failure — fix before merge |
+| **Quality** | Maintainability issue, naming violation, missing pattern — fix before merge |
+
+---
+
+## Step 2 — Code Smell Analysis
+
+Read the file `.claude/commands/code-smell.md` and follow all of its instructions for the same files in scope. Produce its full output (per-file smell table + smell summary + recommendation).
+
+---
+
+## Step 3 — Security Audit
+
+Read the file `.claude/commands/code-security.md` and follow all of its instructions for the same files in scope. Produce its full output (per-finding blocks + summary table + overall risk rating).
+
+---
+
+## Final Verdict
+
+After all three steps, close with:
+1. A tech-debt summary table grouped by category (SDK Patterns / Error Handling / Naming / Tests / Smells / Security)
+2. A verdict: `APPROVE` / `APPROVE WITH FIXES` / `REQUEST CHANGES`
diff --git a/.claude/commands/code-security.md b/.claude/commands/code-security.md
new file mode 100644
index 00000000..0fa69923
--- /dev/null
+++ b/.claude/commands/code-security.md
@@ -0,0 +1,69 @@
+---
+name: code-security
+description: Security audit — credential exposure, input validation, path traversal, HTTP security, token lifecycle, dependency CVEs.
+paths:
+  - src/main/java/com/skyflow/serviceaccount/**/*.java
+  - src/main/java/com/skyflow/config/**/*.java
+  - src/main/java/com/skyflow/utils/**/*.java
+  - src/main/java/com/skyflow/vault/controller/**/*.java
+  - pom.xml
+---
+
+You are a security engineer auditing the Skyflow Java SDK for vulnerabilities.
+
+## Audit Scope
+
+Use `$ARGUMENTS` to determine target files. If none provided, run:
+```bash
+git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+```
+
+**Skip:** `src/main/java/com/skyflow/generated/` — observations only, no edits.
+
+## Security Checks
+
+### 1. Credential and token exposure (Critical)
+- Bearer tokens, API keys, and private keys must never appear in logs, error messages, exception messages, or `toString()` output
+- `Credentials` fields (`path`, `token`, `apiKey`, `credentialsString`) must not be serialised to logs
+- JWT claims must not be logged
+
+### 2. Input validation (High)
+- All string inputs from callers must be null/empty checked before use
+- File paths passed to `new File(path)` must not allow path traversal (`../`)
+- JSON strings parsed with `JsonParser` must be wrapped in try/catch for `JsonSyntaxException`
+
+### 3. Credentials file handling (High)
+- Credentials files must only be read from paths provided by the caller — no environment variable path injection without sanitisation
+- `FileReader` must be in a try-with-resources or explicitly closed
+
+### 4. HTTP security (Medium)
+- All API calls must go over HTTPS — verify `Utils.getBaseURL` enforces this
+- Authorization headers must not be logged at any log level
+- HTTP timeouts must be configured
+
+### 5. Error information leakage (Medium)
+- `SkyflowException` messages must not include raw server response bodies that could contain PII
+- Stack traces must not be surfaced to callers — wrap in `SkyflowException`
+
+### 6. Dependency vulnerabilities (Low)
+- Note any dependencies that are known to have CVEs (check pom.xml versions)
+
+### 7. Authentication lifecycle (Medium)
+- Bearer token caching must check expiry before reuse
+- Token refresh must be thread-safe (`synchronized` or equivalent)
+
+## Output Format
+
+For each finding:
+
+```
+### path/to/File.java : line N
+
+**Severity:** Critical / High / Medium / Low / Info
+**Risk:** What an attacker could do
+**Trigger:** Input or code path that triggers the vulnerability
+**Fix:** Concrete remediation with code example
+**CWE:** CWE-NNN
+```
+
+End with a summary table and overall risk rating.
diff --git a/.claude/commands/code-smell.md b/.claude/commands/code-smell.md
new file mode 100644
index 00000000..f456a8d8
--- /dev/null
+++ b/.claude/commands/code-smell.md
@@ -0,0 +1,145 @@
+---
+name: code-smell
+description: Structural smell analysis + spell check — long methods, dead code, misplaced validation, deep nesting, magic numbers. Does not check patterns or security.
+paths:
+  - src/main/java/**/*.java
+---
+
+You are a senior engineer performing a code smell analysis on the Skyflow Java SDK.
+
+## Scope
+
+Use `$ARGUMENTS` to determine scope:
+- A file or directory path — analyse only that path
+- Empty / default — analyse files changed on current branch vs `main`:
+  ```bash
+  git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+  ```
+
+**Skip entirely:** `src/main/java/com/skyflow/generated/` — Fern-generated REST client, read-only.
+
+---
+
+## Spell check
+
+Before analysing smells, run cspell on the files in scope:
+
+```bash
+npx cspell --no-progress "src/**/*.java" ".claude/**/*.md" "CLAUDE.md" "docs/**/*.md" 2>&1 | grep "Unknown word"
+```
+
+Report any spelling violations at **Smell** severity in the per-file table. The word list is in `.cspell.json` — add legitimate project-specific terms there rather than fixing them as typos.
+
+---
+
+## What Are Code Smells
+
+Code smells are structural signals — they do not necessarily mean the code is broken, but they indicate areas of technical debt, reduced readability, or future maintenance risk. All findings are reported at **Smell** severity and do not block merge unless they indicate a design violation.
+
+---
+
+## Smell Catalogue
+
+### Method & Class Size
+
+**Long method** — any method over 40 lines.
+Signal: the method is doing too much. Candidate for decomposition into named private helpers.
+
+**Long class** — any class over 300 lines.
+Signal: the class may be taking on too many responsibilities. Check if it can be split by concern.
+
+**Large parameter list** — more than 4 parameters on a method.
+Signal: consider a config/options object or a builder to group related parameters.
+
+---
+
+### Responsibility Violations
+
+**Business logic in Request/Response classes**
+Request and Response classes are data holders — they carry data, nothing more. Flag any conditional logic, field transformation, or computation beyond null-safe getters.
+Example of a violation: a Response class that renames map keys in `toString()` instead of letting the controller do it.
+
+**toString() with business logic**
+`toString()` should only serialise state for debugging. Logic like field renaming, manual JSON construction, conditional field injection, or iteration belongs in the controller or formatter methods.
+
+**Validation outside `Validations.java`**
+Any `if (x == null) throw new SkyflowException(...)` outside `src/main/java/com/skyflow/utils/validations/` is misplaced validation. All request validation must live in `Validations.validateXxxRequest()`.
+
+---
+
+### Control Flow
+
+**Deep nesting** — more than 3 levels of `if` / `for` / `try` nesting.
+Signal: extract inner blocks to named private methods. Deep nesting hides the happy path.
+
+**Long if-else chains** — more than 4 branches on the same condition.
+Signal: consider a `Map`, `switch`, or polymorphism.
+
+**Null checks scattered**
+Multiple consecutive null guards that could be replaced with `Optional` or an early return guard clause.
+
+---
+
+### Data
+
+**Magic numbers**
+Literal integers or sizes (e.g. `25`, `3600`, `100`) without a named constant. Use `Constants`.
+
+**Raw HashMap chains**
+`HashMap<String, Object>` passed through more than 2 method boundaries without a typed wrapper or explanatory comment. Flag for awareness — do not require an immediate fix.
+
+**Temporary field**
+A class field that is only set in certain code paths and is `null` the rest of the time. Should be a local variable or method parameter instead.
+
+---
+
+### Dead Code
+
+**Unused private methods** — private methods with no callers.
+
+**Unused imports** — any `import` not referenced in the file.
+
+**Unreachable code** — code after `return` / `throw` in the same branch.
+
+**Commented-out code** — blocks of commented code without explanation. Remove entirely or add a `// TODO: [ticket]` with context.
+
+---
+
+### Comments
+
+**Explains what, not why**
+A comment that restates what the code does (`// get the vault ID`) adds no value. Only flag comments that explain the *what* without explaining *why*.
+
+**Stale comment**
+A comment that contradicts the current code — e.g. references a removed parameter, an old method name, or a behaviour that has changed.
+
+---
+
+## Output Format
+
+Group findings by file:
+
+```
+### path/to/File.java
+
+| Smell                     | Line | Detail                                                    |
+|---------------------------|------|-----------------------------------------------------------|
+| Long method               | 42   | processInsertResponse() is 67 lines — decompose          |
+| Business logic in Response| 88   | toString() renames skyflow_id — move to formatter         |
+| Magic number              | 103  | Literal 25 — extract to Constants.MAX_QUERY_RECORDS       |
+| Stale comment             | 210  | References removed tokenizedData field                    |
+| Dead code                 | 315  | Private method buildHeaders() has no callers              |
+```
+
+End with a **Smell Summary** table:
+
+```
+| Category              | Count | Files affected         |
+|-----------------------|-------|------------------------|
+| Long methods          | 2     | VaultController.java   |
+| Business logic in DTO | 1     | QueryResponse.java     |
+| Magic numbers         | 3     | Validations.java       |
+| Dead code             | 2     | Utils.java             |
+```
+
+Close with a recommendation: **CLEAN** / **MINOR DEBT** / **SIGNIFICANT DEBT** and a one-sentence summary.
diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md
new file mode 100644
index 00000000..6aae4614
--- /dev/null
+++ b/.claude/commands/commit.md
@@ -0,0 +1,55 @@
+---
+name: commit
+description: Stage check + Jira-aware commit — extracts ticket ID from branch name and validates against pr.yml commit-message check.
+---
+
+Create a git commit for staged changes on the current branch.
+
+Use `$ARGUMENTS` as the commit message description. If empty, ask the user for a description before proceeding.
+
+## Step 1 — Extract ticket ID from branch name
+
+```bash
+git rev-parse --abbrev-ref HEAD
+```
+
+Extract the Jira ticket ID using the pattern `[A-Z]{1,10}-[0-9]+`:
+- `devesh/SK-1234-fix-foo` → `SK-1234`
+- `karthik/GV-770-ext-auth-json-error` → `GV-770`
+- `username/SDK-2814-some-fix` → `SDK-2814`
+
+If no ticket ID is found, **stop** and ask the user to provide one before continuing.
+
+## Step 2 — Check what is staged
+
+```bash
+git status --short
+git diff --cached --stat
+```
+
+If nothing is staged, list the unstaged files and ask the user which files to stage. Do not run `git add .` — ask for explicit paths (`.env`, `credentials.json`, and `generated/` must never be staged).
+
+## Step 3 — Assemble and validate the commit message
+
+Build the message as:
+```
+<ticket-id> <description>
+```
+
+If the user provided a Conventional Commits prefix (`feat`, `fix`, `chore`, `docs`, `refactor`, `test`), prepend it:
+```
+feat: SK-1234 add bulk insert support
+fix: GV-770 handle null bearer token on refresh
+```
+
+Validate against the `pr.yml` enforced pattern: `(\[?[A-Z]{1,10}-[1-9][0-9]*)|(\[AUTOMATED\])|(Merge)|(Release)`
+- Must contain a Jira ID — a bare description without a ticket ID will fail CI.
+- If validation fails, report the exact requirement and stop.
+
+## Step 4 — Commit
+
+```bash
+git commit -m "<assembled message>"
+```
+
+Report the resulting commit SHA and the commit message first line.
diff --git a/.claude/commands/sdk-sample.md b/.claude/commands/sdk-sample.md
new file mode 100644
index 00000000..a7b84a65
--- /dev/null
+++ b/.claude/commands/sdk-sample.md
@@ -0,0 +1,70 @@
+---
+name: sdk-sample
+description: Generate a Skyflow Java SDK sample file for a vault feature or service account operation. Compile-verified after creation.
+paths:
+  - samples/**/*.java
+  - samples/pom.xml
+---
+
+Create a Skyflow Java SDK sample file demonstrating: $ARGUMENTS
+
+## File placement
+
+| Feature type | Package | Directory |
+|---|---|---|
+| Vault ops (insert/get/update/delete/query/tokenize) | `com.example.vault` | `samples/src/main/java/com/example/vault/` |
+| Service account auth | `com.example.serviceaccount` | `samples/src/main/java/com/example/serviceaccount/` |
+| Connection | `com.example.connection` | `samples/src/main/java/com/example/connection/` |
+| Detect | `com.example.detect` | `samples/src/main/java/com/example/detect/` |
+| Audit event operations | `com.example.audit` | `samples/src/main/java/com/example/audit/` |
+| BIN lookup | `com.example.bin` | `samples/src/main/java/com/example/bin/` |
+
+File name: `<FeatureName>Example.java`
+
+## Structure (follow this order)
+
+1. Package declaration
+2. Imports — only from `com.skyflow.*`, `java.*`; never from `com.skyflow.generated.*`
+3. Public class with `main(String[] args) throws SkyflowException`
+4. Credentials setup — choose based on feature:
+   - **Vault ops:** `credentials.setApiKey("<YOUR_API_KEY>")` or `credentials.setCredentialsString("<YOUR_CREDENTIALS_STRING>")`
+   - **Service account:** `credentials.setPath("credentials.json")` (path to the service account JSON file)
+5. `VaultConfig` with `setVaultId`, `setClusterId`, `setEnv(Env.PROD)`, `setCredentials(credentials)`
+6. Build the Skyflow client:
+   ```java
+   Skyflow skyflowClient = Skyflow.builder()
+       .setLogLevel(LogLevel.DEBUG)
+       .addVaultConfig(vaultConfig)
+       .build();
+   ```
+7. Request object via `*Request.builder()` — options go directly on the builder (no separate Options class):
+   ```java
+   // Example: InsertRequest with tokenMode
+   InsertRequest request = InsertRequest.builder()
+       .table("...")
+       .values(records)
+       .tokenMode(TokenMode.ENABLE)
+       .build();
+   ```
+8. Call the vault method inside a try/catch for `SkyflowException`:
+   ```java
+   InsertResponse response = skyflowClient.vault().insert(request);
+   System.out.println(response);
+   ```
+
+## Rules
+
+- Vault IDs / cluster IDs use placeholders: `"<YOUR_VAULT_ID>"`, `"<YOUR_CLUSTER_ID>"`
+- Credential values use placeholders: `"<YOUR_API_KEY>"`, `"<YOUR_CREDENTIALS_STRING>"`
+- Credentials file path: `"credentials.json"` (relative — no absolute paths)
+- Always catch `SkyflowException` and print `e.getMessage()`
+- No separate `*Options` classes — they don't exist in this SDK; use request builder methods
+- Keep under 80 lines
+
+## After creating the file
+
+```bash
+cd samples && mvn compile -q 2>&1 | tail -20
+```
+
+Report the file path and any compile errors.
diff --git a/.claude/commands/test.md b/.claude/commands/test.md
new file mode 100644
index 00000000..e690a355
--- /dev/null
+++ b/.claude/commands/test.md
@@ -0,0 +1,73 @@
+---
+name: test
+description: Quality pipeline — compile, checkstyle, build, tests, coverage analysis. Pass a class name to target a single test class.
+paths:
+  - src/**/*.java
+  - pom.xml
+---
+
+Run the Skyflow Java SDK quality pipeline.
+
+Use `$ARGUMENTS` to target a specific test class (e.g. `BearerTokenTests`). If empty, run the full suite.
+
+> Baseline failures are listed in CLAUDE.md under "Known Pre-existing Test Failures".
+> Do not investigate them unless specifically asked. Only report failures **beyond** that baseline.
+
+## Pipeline
+
+### Step 1 — Compile
+```bash
+mvn compile -q 2>&1 | tail -20
+```
+Expected: no output (clean compile). Report any errors.
+
+### Step 2 — Checkstyle
+```bash
+mvn checkstyle:check -q 2>&1 | tail -20
+```
+Note: `failsOnError=false` in pom.xml means the build will not fail even if violations exist — check the output for `[WARN]` checkstyle lines. Violations are excluded from `generated/` by pom config.
+
+### Step 3 — Build
+```bash
+mvn package -DskipTests -q 2>&1 | tail -20
+```
+Expected: BUILD SUCCESS.
+
+### Step 4 — Tests
+If `$ARGUMENTS` is set:
+```bash
+mvn test -Dtest=$ARGUMENTS -q 2>&1 | tail -40
+```
+Otherwise:
+```bash
+mvn test -q 2>&1 | tail -40
+```
+Report: tests run, failures, errors. Flag any pre-existing failures separately from new ones.
+
+### Step 5 — Coverage analysis
+Flag any public interface class (`src/main/java/com/skyflow/vault/`, `src/main/java/com/skyflow/config/`, `src/main/java/com/skyflow/serviceaccount/`) that has no corresponding test file under `src/test/`.
+
+For classes that do have tests, check whether each public method has at least one positive and one negative test case. List any gaps.
+
+### Step 6 — Edge case identification
+For any test class below complete coverage, identify missing scenarios:
+- Null / empty inputs
+- Invalid types / wrong enum values
+- Concurrent / reuse scenarios
+- Error paths (API rejection, network failure)
+
+Write concrete JUnit 4 test method stubs (not full implementations) for each gap.
+
+### Step 7 — Report
+
+```
+| Step | Status | Notes |
+|---|---|---|
+| Compile | ✅ / ❌ | ... |
+| Checkstyle | ✅ / ❌ | ... |
+| Build | ✅ / ❌ | ... |
+| Tests | ✅ / ❌ | N passed, M failed |
+| Coverage gaps | ... | list classes |
+```
+
+Conclude with **READY TO MERGE** or **NEEDS FIXES** and a prioritised fix list.
diff --git a/.claude/hooks/checkstyle-on-edit.py b/.claude/hooks/checkstyle-on-edit.py
new file mode 100644
index 00000000..4fd0787d
--- /dev/null
+++ b/.claude/hooks/checkstyle-on-edit.py
@@ -0,0 +1,19 @@
+import sys, json, subprocess, os
+
+d = json.load(sys.stdin)
+f = d.get('tool_input', {}).get('file_path', d.get('file_path', ''))
+if not f or not f.endswith('.java'):
+    sys.exit(0)
+
+root = '/home/devb/SDK/skyflow-java'
+marker = 'src/main/java/'
+if marker in f:
+    rel = f.split(marker, 1)[1]
+    args = ['mvn', 'checkstyle:check', '-q', '-Dcheckstyle.includes=' + rel]
+else:
+    args = ['mvn', 'checkstyle:check', '-q']
+
+r = subprocess.run(args, capture_output=True, text=True, cwd=root)
+out = (r.stdout + r.stderr).strip()
+if out:
+    print('\n'.join(out.splitlines()[-20:]))
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000..1d00baed
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,30 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/checkstyle-on-edit.py"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(mvn *)",
+      "Bash(java *)",
+      "Bash(python3 *)",
+      "Bash(git *)",
+      "Bash(find *)",
+      "Bash(grep *)",
+      "Bash(npx cspell *)"
+    ],
+    "deny": [
+      "Edit(src/main/java/com/skyflow/generated/**)",
+      "Write(src/main/java/com/skyflow/generated/**)"
+    ]
+  }
+}
diff --git a/.claude/skills/requesting-code-review/SKILL.md b/.claude/skills/requesting-code-review/SKILL.md
new file mode 100644
index 00000000..9f662842
--- /dev/null
+++ b/.claude/skills/requesting-code-review/SKILL.md
@@ -0,0 +1,76 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+paths:
+  - src/main/java/**/*.java
+  - src/test/java/**/*.java
+---
+
+# Requesting Code Review
+
+**Core principle:** Review early, review often. Review after each task — catch issues before they compound.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing a major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing a complex bug
+
+## How to Request
+
+**1. Pick the right command:**
+
+| Change type | Command |
+|---|---|
+| SDK logic, patterns, naming, tests | `/code-review` — SDK checks + smell + security |
+| Structural debt only | `/code-smell` — standalone smell analysis |
+| Auth, credentials, tokens, HTTP | `/code-security` — standalone security audit |
+
+For security-sensitive changes, run both:
+```bash
+/code-review src/main/java/com/skyflow/serviceaccount/
+/code-security src/main/java/com/skyflow/serviceaccount/
+```
+
+**2. Fork context — dispatch a subagent reviewer:**
+
+The commands above run in the current session and share your context. For an independent second opinion (no confirmation bias, preserved main context window), dispatch a fresh subagent:
+
+```
+Agent tool (general-purpose):
+  description: "SDK code review"
+  prompt: |
+    You are a senior engineer reviewing the Skyflow Java SDK.
+
+    Read CLAUDE.md for project conventions, then read and follow
+    .claude/commands/code-review.md for the full review process.
+
+    Git range to review:
+      Base: {BASE_SHA}
+      Head: {HEAD_SHA}
+
+    Run:
+      git diff --stat {BASE_SHA}..{HEAD_SHA}
+      git diff {BASE_SHA}..{HEAD_SHA}
+
+    Description of what was implemented:
+      {DESCRIPTION}
+```
+
+Get the SHAs:
+```bash
+BASE_SHA=$(git merge-base main HEAD)   # branch vs main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor/Smell issues for later
+- Push back with reasoning if you disagree
diff --git a/.cspell.json b/.cspell.json
index a0ec0be6..a982f837 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -73,9 +73,33 @@
     "pkcs",
     "prioritise",
     "Prioritise",
+    "prioritised",
     "Timeto",
     "Wdex",
-    "jacoco"
+    "jacoco",
+    "serialise",
+    "serialised",
+    "serialises",
+    "serialising",
+    "normalise",
+    "Normalise",
+    "normalised",
+    "normalises",
+    "Normalises",
+    "normalising",
+    "behaviour",
+    "Behaviour",
+    "behaviours",
+    "sanitisation",
+    "prioritise",
+    "recognised",
+    "unrecognised",
+    "nocreds",
+    "nodir",
+    "detok",
+    "qhdmceurtnlz",
+    "ngrok",
+    "obac"
   ],
   "languageSettings": [
     {
@@ -98,7 +122,9 @@
     "src/main/java/com/skyflow/generated/**",
     "**/*.ts",
     "**/processed-*",
-    "samples/src/main/java/com/example/credentials.json"
+    "samples/src/main/java/com/example/credentials.json",
+    "RUNNING_SAMPLES.md",
+    "docs/superpowers/**"
   ],
   "ignoreRegExpList": [
     "/\\b[A-Z][A-Z0-9_]{2,}\\b/g",
@@ -106,6 +132,7 @@
     "/(eyJ[A-Za-z0-9+/=_-]+\\.)+[A-Za-z0-9+/=_-]+/g",
     "/[A-Za-z0-9_.~-]*%[0-9A-Fa-f]{2}[A-Za-z0-9_.~%-]*/g",
     "/\\b[A-Za-z0-9_]{7,}\\b(?=])/g",
-    "/\"[A-Za-z0-9+/=]{15,}\"/g"
+    "/\"[A-Za-z0-9+/=]{15,}\"/g",
+    "/-D[A-Za-z][A-Za-z0-9.]*/g"
   ]
 }
diff --git a/.github/workflows/claude-changelog.yml b/.github/workflows/claude-changelog.yml
new file mode 100644
index 00000000..aae70fa2
--- /dev/null
+++ b/.github/workflows/claude-changelog.yml
@@ -0,0 +1,86 @@
+name: Claude Changelog
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+      - '*.*.*-beta.*'
+
+permissions:
+  contents: write
+
+jobs:
+  generate-changelog:
+    name: Generate Release Notes
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get previous tag
+        id: previoustag
+        uses: WyriHaximus/github-action-get-previous-tag@v1
+        with:
+          fallback: '0.0.0'
+
+      - name: Get commits since previous tag
+        id: commits
+        run: |
+          PREV="${{ steps.previoustag.outputs.tag }}"
+          CURR="${{ github.ref_name }}"
+          COMMITS=$(git log "${PREV}..${CURR}" --oneline \
+            | grep -v '^\S* \[AUTOMATED\]' \
+            | grep -v '^\S* Merge ' \
+            | grep -v '^\S* \[AUTOMATED\]')
+          echo "log<<EOF" >> $GITHUB_OUTPUT
+          echo "$COMMITS" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Install Claude CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Generate release notes
+        id: notes
+        continue-on-error: true
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          PREV="${{ steps.previoustag.outputs.tag }}"
+          CURR="${{ github.ref_name }}"
+          COMMITS="${{ steps.commits.outputs.log }}"
+          NOTES=$(claude --print --model claude-sonnet-4-5 -p "
+          Generate GitHub Release notes for the Skyflow Java SDK.
+
+          Release: $CURR (previous: $PREV)
+
+          Commits:
+          $COMMITS
+
+          Rules:
+          - Group into sections: ## Features, ## Bug Fixes, ## Security, ## Breaking Changes
+          - Omit any section with no entries
+          - Each entry: bullet point with a concise one-line description; include the Jira ticket ID if present (e.g. SK-1234)
+          - Strip PR merge numbers like (#323) — keep the substance
+          - Skip [AUTOMATED] commits, version bump commits, and bare merge commits
+          - Breaking Changes section must come first if present
+          - End with: _Full changelog: https://github.com/skyflowapi/skyflow-java/compare/${PREV}...${CURR}_
+
+          Output only the markdown. No preamble or explanation.
+          ")
+          echo "notes<<EOF" >> $GITHUB_OUTPUT
+          echo "$NOTES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create or update GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ github.ref_name }}"
+          NOTES="${{ steps.notes.outputs.notes }}"
+          if gh release view "$TAG" > /dev/null 2>&1; then
+            gh release edit "$TAG" --notes "$NOTES"
+          else
+            gh release create "$TAG" --notes "$NOTES" --title "Release $TAG"
+          fi
diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml
new file mode 100644
index 00000000..821b2d50
--- /dev/null
+++ b/.github/workflows/claude-pr-review.yml
@@ -0,0 +1,157 @@
+name: Claude PR Review
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'src/**/*.java'
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  sdk-patterns-review:
+    name: SDK Patterns & Naming Review
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Claude CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Get changed Java files
+        id: changed-files
+        run: |
+          FILES=$(git diff --name-only origin/${{ github.base_ref }}...${{ github.sha }} \
+            | grep '\.java$' \
+            | grep -v 'generated' \
+            | tr '\n' ' ')
+          echo "files=$FILES" >> $GITHUB_OUTPUT
+
+      - name: Run SDK patterns review
+        if: steps.changed-files.outputs.files != ''
+        id: review
+        continue-on-error: true
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          FILES="${{ steps.changed-files.outputs.files }}"
+          REVIEW=$(claude --print --model claude-sonnet-4-5 -p "
+          You are a senior engineer reviewing the Skyflow Java SDK.
+
+          Review the following changed Java files for SDK pattern violations:
+          1. Request/Response/Options patterns — builders are data holders, validation in Validations.java only
+          2. Error handling — all public methods throw SkyflowException, no swallowed exceptions, no bare println/printStackTrace
+          3. Naming — acronyms as words (skyflowId not skyflowID, tokenUri not tokenURI); UPPER_SNAKE constants; PascalCase classes
+          4. Response normalisation — skyflowId not skyflow_id in response maps; getErrors() present on every response class
+          5. Code quality — no magic strings (use Constants), no @SuppressWarnings without comment, deprecation via LogUtil.printWarningLog
+
+          Skip src/main/java/com/skyflow/generated/ entirely.
+
+          Files to review: $FILES
+
+          For each file with findings, produce a markdown table:
+          | Severity | Line | Finding |
+          Severities: Critical (data loss/security), Bug (wrong behaviour), Quality (naming/patterns).
+          Skip Info-level observations. If no findings for a file, omit it.
+          If no findings at all, write: 'No issues found.'
+
+          End with one of: APPROVE / APPROVE WITH FIXES / REQUEST CHANGES
+          ")
+          echo "result<<EOF" >> $GITHUB_OUTPUT
+          echo "$REVIEW" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Post review comment
+        if: steps.changed-files.outputs.files != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const review = `${{ steps.review.outputs.result }}`;
+            const files = `${{ steps.changed-files.outputs.files }}`;
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: context.payload.pull_request.number,
+              body: `## Claude SDK Patterns Review\n\n${review}\n\n---\n_Files reviewed: \`${files}\`_`
+            });
+
+  security-review:
+    name: Security Review (serviceaccount changes)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for serviceaccount changes
+        id: filter
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            serviceaccount:
+              - 'src/**/serviceaccount/**/*.java'
+
+      - name: Install Claude CLI
+        if: steps.filter.outputs.serviceaccount == 'true'
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Get changed serviceaccount files
+        if: steps.filter.outputs.serviceaccount == 'true'
+        id: sa-files
+        run: |
+          FILES=$(git diff --name-only origin/${{ github.base_ref }}...${{ github.sha }} \
+            | grep 'serviceaccount' \
+            | grep '\.java$' \
+            | tr '\n' ' ')
+          echo "files=$FILES" >> $GITHUB_OUTPUT
+
+      - name: Run security audit
+        if: steps.filter.outputs.serviceaccount == 'true' && steps.sa-files.outputs.files != ''
+        id: security
+        continue-on-error: true
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          FILES="${{ steps.sa-files.outputs.files }}"
+          AUDIT=$(claude --print --model claude-sonnet-4-5 -p "
+          You are a security engineer auditing the Skyflow Java SDK serviceaccount module.
+
+          Audit the following files for:
+          1. Credential and token exposure — bearer tokens, API keys, private keys must never appear in logs, error messages, or toString() output
+          2. Path traversal — file paths passed to new File(path) must not allow ../
+          3. JSON parsing — JsonParser calls must be wrapped in try/catch for JsonSyntaxException
+          4. HTTP security — all API calls must be HTTPS; Authorization headers must not be logged at any level
+          5. Token lifecycle — bearer token caching must check expiry before reuse; token refresh must be thread-safe
+
+          Files: $FILES
+
+          For each finding:
+          **Severity:** Critical / High / Medium / Low
+          **File:Line:** path:N
+          **Risk:** one sentence
+          **Fix:** one concrete sentence
+
+          If no findings, write: 'No security issues found.'
+          End with overall risk rating: LOW / MEDIUM / HIGH / CRITICAL
+          ")
+          echo "result<<EOF" >> $GITHUB_OUTPUT
+          echo "$AUDIT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Post security comment
+        if: steps.filter.outputs.serviceaccount == 'true' && steps.sa-files.outputs.files != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const audit = `${{ steps.security.outputs.result }}`;
+            const files = `${{ steps.sa-files.outputs.files }}`;
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: context.payload.pull_request.number,
+              body: `## Claude Security Audit (serviceaccount)\n\n${audit}\n\n---\n_Files audited: \`${files}\`_`
+            });
diff --git a/.github/workflows/release-v1.yml b/.github/workflows/release-v1.yml
new file mode 100644
index 00000000..e69de29b
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..00904528
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,148 @@
+---
+name: skyflow-java-sdk
+description: Skyflow Java SDK project context — naming conventions, build commands, known failures, and slash commands. Loaded for all Java source, test, and sample files.
+paths:
+  - src/**/*.java
+  - samples/**/*.java
+  - pom.xml
+  - checkstyle.xml
+---
+
+# Skyflow Java SDK — Claude Code Instructions
+
+## Project Overview
+
+This is the Skyflow Java SDK (`skyflow-java`). It provides a Java interface to the Skyflow Data Privacy Vault API — vault operations (insert, get, update, delete, query, tokenize, detokenize), service account authentication (bearer tokens, signed data tokens), connections, detect, and audit.
+
+**v1 (maintenance mode, `v1` branch):** Security and bug fixes only — no new features. EOL announced: **October 31, 2026**. 
+
+**Current stable version: v2.1** — supports PDB vaults. This is what customers use.
+
+**v3 (pre-release, Flow DB only):** v3 is *not* a full replacement for v2. It adds Flow DB-specific operations used by the [Spark wrapper](https://github.com/skyflowapi/vault-workflows):
+- `bulkInsert`
+- `batchProcessing` (`batchSize` + `concurrencyLimit`)
+
+v3 does not yet have full parity with v2. Do not treat v3 as the general SDK — scope v3 work strictly to Flow DB features unless explicitly told otherwise.
+
+## Critical Boundary — Generated Code
+
+**Never edit files under `src/main/java/com/skyflow/generated/`.**
+
+These are auto-generated by [Fern](https://buildwithfern.com) from the Skyflow API definition. Manual edits are overwritten on the next generation run. If you find a bug in generated code, report it — do not patch it directly.
+
+The `pom.xml` checkstyle and test configs already exclude `generated/` from all checks.
+
+## Project Structure
+
+```
+src/
+  main/java/com/skyflow/
+    config/          # VaultConfig, Credentials, ConnectionConfig
+    vault/           # controller/, data/, tokens/, connection/, audit/, bin/, detect/
+    serviceaccount/  # BearerToken, SignedDataTokens (JWT + credential parsing)
+    enums/           # LogLevel, RedactionType, TokenMode, Env
+    errors/          # SkyflowException, ErrorCode, ErrorMessage
+    utils/           # Utils, Constants, HttpUtility, LogUtil, Validations
+    generated/       # ← FERN-GENERATED, DO NOT EDIT
+  test/java/com/skyflow/
+    ...              # JUnit 4 tests mirroring main structure
+samples/             # Standalone Maven project — vault / serviceaccount / detect / connection
+docs/
+  superpowers/specs/ # Design specs
+  superpowers/plans/ # Implementation plans
+```
+
+## Naming Conventions
+
+- **Acronyms as words:** `skyflowId` (not `skyflowID`), `clientId` (not `clientID`), `tokenUri` (not `tokenURI`), `keyId` (not `keyID`)
+- **Builder setters:** `setVaultId()`, `setClusterId()`, `setSkyflowId()` — never `setVaultID()`
+- **Response maps:** always use `skyflowId` (camelCase) — the raw API returns `skyflow_id` (snake_case) which VaultController normalises before returning to callers
+- **Constants class:** use `com.skyflow.utils.Constants` for string literals; `ErrorMessage` enum for error message strings
+
+## Build and Test
+
+```bash
+mvn compile -q              # compile
+mvn checkstyle:check -q     # lint (config: checkstyle.xml)
+mvn test -q                 # full test suite (JUnit 4)
+mvn test -Dtest=ClassName   # single test class
+mvn package -DskipTests -q  # build jar
+```
+
+Samples (separate Maven project):
+```bash
+cd samples && mvn compile -q
+```
+
+## Credentials JSON Format
+
+The SDK reads a `credentials.json` file for service account authentication. The canonical field names (v3+) are:
+
+```json
+{
+  "clientId": "...",
+  "keyId": "...",
+  "tokenUri": "...",
+  "privateKey": "..."
+}
+```
+
+The legacy all-caps forms (`clientID`, `keyID`, `tokenURI`) are accepted as fallbacks for migration.
+
+## Known Pre-existing Test Failures
+
+These failures exist on `main` and are **not regressions** — do not investigate them unless specifically asked:
+
+| Test class | Failure | Cause |
+|---|---|---|
+| `HttpUtilityTests` | `InaccessibleObject` (all tests) | JDK 21 + PowerMock incompatibility — PowerMock cannot reflect into `java.net` |
+| `TokenTests#testExpiredTokenForIsExpiredToken` | Environment error | Requires live credentials |
+| `VaultClientTests#testSetBearerTokenWithEnvCredentials` | Environment error | Requires `SKYFLOW_CREDENTIALS` env var |
+| `ConnectionClientTests#testSetBearerTokenWithEnvCredentials` | Environment error | Requires `SKYFLOW_CREDENTIALS` env var |
+
+Run `mvn test -q 2>&1 | grep -E "Tests run|FAIL|ERROR"` to see the current baseline.
+
+## Active Work
+
+See `docs/superpowers/specs/` for in-progress design specs and `docs/superpowers/plans/` for implementation plans.
+
+## Slash Commands
+
+- `/code-review` — full review: SDK patterns + code smells + security (Steps 2 and 3 read `.claude/commands/code-smell.md` and `.claude/commands/code-security.md` at runtime)
+- `/code-smell` — standalone structural smell analysis only (long methods, dead code, misplaced logic)
+- `/code-security` — standalone security audit only (credentials, input validation, HTTP security)
+- `/sdk-sample <feature>` — generate a sample file for a feature
+- `/test [ClassName]` — run quality pipeline (compile → checkstyle → build → test → coverage)
+- `/commit <description>` — stage check + Jira-aware commit (extracts ticket ID from branch name)
+
+## Commit & PR Guidelines
+
+### Commit messages
+Every commit on a PR branch **must** include a Jira ticket ID — enforced by the `check-commit-message` step in `.github/workflows/pr.yml`.
+
+Accepted formats:
+```
+SK-1234 short description
+SK-1234: short description
+feat: SK-1234 short description
+fix(SK-1234): short description
+```
+
+Exempt patterns (no ticket needed):
+- `[AUTOMATED]` — release version bumps only
+- `Merge ...` — merge commits
+- `Release ...` — release commits
+
+Conventional Commits prefixes (`feat:`, `fix:`, `chore:`, `docs:`) are encouraged but only valid alongside a Jira ID.
+
+### Branch naming
+Branch name must include your GitHub username:
+
+```
+<github-username>/<ticket-id>-<short-description>
+```
+
+Example: `karthik/GV-770-ext-auth-json-error`
+
+### PR template
+The `.github/pull_request_template.md` requires: **Why**, **Goal**, **Testing** sections. Tech debt section is optional.

From 08df1abe892d1ef94747c1166cda598e778e273b Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 18:50:36 +0530
Subject: [PATCH 02/30] =?UTF-8?q?SK-2832=20remove=20release-v1.yml=20?=
 =?UTF-8?q?=E2=80=94=20not=20part=20of=20Claude=20setup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/release-v1.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 .github/workflows/release-v1.yml

diff --git a/.github/workflows/release-v1.yml b/.github/workflows/release-v1.yml
deleted file mode 100644
index e69de29b..00000000

From 1819b057693a8695222d69e7f4994de63a89febb Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:03:02 +0530
Subject: [PATCH 03/30] SK-2832 split samples context into samples/CLAUDE.md

- Move file placement, deprecated folder note, and sample rules
  into samples/CLAUDE.md (loads only when working on samples)
- Remove samples paths and content from root CLAUDE.md to reduce
  token load on every non-samples session

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md         |  9 +--------
 samples/CLAUDE.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 8 deletions(-)
 create mode 100644 samples/CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 00904528..ad46df3f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,9 +1,8 @@
 ---
 name: skyflow-java-sdk
-description: Skyflow Java SDK project context — naming conventions, build commands, known failures, and slash commands. Loaded for all Java source, test, and sample files.
+description: Skyflow Java SDK project context — naming conventions, build commands, known failures, and slash commands. Loaded for all Java source files.
 paths:
   - src/**/*.java
-  - samples/**/*.java
   - pom.xml
   - checkstyle.xml
 ---
@@ -46,7 +45,6 @@ src/
     generated/       # ← FERN-GENERATED, DO NOT EDIT
   test/java/com/skyflow/
     ...              # JUnit 4 tests mirroring main structure
-samples/             # Standalone Maven project — vault / serviceaccount / detect / connection
 docs/
   superpowers/specs/ # Design specs
   superpowers/plans/ # Implementation plans
@@ -69,11 +67,6 @@ mvn test -Dtest=ClassName   # single test class
 mvn package -DskipTests -q  # build jar
 ```
 
-Samples (separate Maven project):
-```bash
-cd samples && mvn compile -q
-```
-
 ## Credentials JSON Format
 
 The SDK reads a `credentials.json` file for service account authentication. The canonical field names (v3+) are:
diff --git a/samples/CLAUDE.md b/samples/CLAUDE.md
new file mode 100644
index 00000000..9ec2ea9a
--- /dev/null
+++ b/samples/CLAUDE.md
@@ -0,0 +1,45 @@
+---
+name: skyflow-java-samples
+description: Samples project context — file placement, structure, and rules for Skyflow Java SDK sample files.
+paths:
+  - "**/*.java"
+  - pom.xml
+---
+
+# Skyflow Java SDK — Samples
+
+Standalone Maven project demonstrating SDK features. Compile with:
+```bash
+cd samples && mvn compile -q
+```
+
+## File Placement
+
+| Feature | Package | Directory |
+|---|---|---|
+| Vault ops (insert/get/update/delete/query/tokenize/detokenize) | `com.example.vault` | `samples/src/main/java/com/example/vault/` |
+| Service account auth | `com.example.serviceaccount` | `samples/src/main/java/com/example/serviceaccount/` |
+| Connection | `com.example.connection` | `samples/src/main/java/com/example/connection/` |
+| Detect | `com.example.detect` | `samples/src/main/java/com/example/detect/` |
+| Audit event operations | `com.example.audit` | `samples/src/main/java/com/example/audit/` |
+| BIN lookup | `com.example.bin` | `samples/src/main/java/com/example/bin/` |
+
+File name: `<FeatureName>Example.java`
+
+## Deprecated Samples
+
+Deprecated examples (v1-era or superseded APIs) live in:
+```
+samples/src/main/java/com/example/vault/deprecated/
+```
+Do not update deprecated samples — they are kept for reference only. New samples go in the parent package, not in `deprecated/`.
+
+## Rules
+
+- Vault IDs / cluster IDs: `"<YOUR_VAULT_ID>"`, `"<YOUR_CLUSTER_ID>"`
+- Credential values: `"<YOUR_API_KEY>"`, `"<YOUR_CREDENTIALS_STRING>"`
+- Credentials file path: `"credentials.json"` (relative, never absolute)
+- Always catch `SkyflowException` and print `e.getMessage()`
+- No separate `*Options` classes — use request builder methods directly
+- Keep under 80 lines
+- Imports from `com.skyflow.*` only — never from `com.skyflow.generated.*`

From c8b52b0a060c74309fcb9346e48612236ccce536 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:03:48 +0530
Subject: [PATCH 04/30] SK-2832 add basic samples reference to root CLAUDE.md

---
 CLAUDE.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index ad46df3f..e847ac8b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -45,6 +45,7 @@ src/
     generated/       # ← FERN-GENERATED, DO NOT EDIT
   test/java/com/skyflow/
     ...              # JUnit 4 tests mirroring main structure
+samples/             # Standalone Maven project — see samples/CLAUDE.md for placement rules
 docs/
   superpowers/specs/ # Design specs
   superpowers/plans/ # Implementation plans

From 50fe8bffa2ea9350468cad6d9ad2560345f01552 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:08:53 +0530
Subject: [PATCH 05/30] SK-2832 make commit guidelines directive for Claude

---
 CLAUDE.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index e847ac8b..3e175bca 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -112,6 +112,8 @@ See `docs/superpowers/specs/` for in-progress design specs and `docs/superpowers
 ## Commit & PR Guidelines
 
 ### Commit messages
+**When making any `git commit`, always extract the Jira ticket ID from the current branch name and include it in the message.** Use `/commit <description>` to do this automatically.
+
 Every commit on a PR branch **must** include a Jira ticket ID — enforced by the `check-commit-message` step in `.github/workflows/pr.yml`.
 
 Accepted formats:

From c3ec30ffc9250c42c28b9dd1daee2e68038374fa Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:09:50 +0530
Subject: [PATCH 06/30] SK-2832 replace redundant commit rules with /commit
 reference

---
 CLAUDE.md | 19 +------------------
 1 file changed, 1 insertion(+), 18 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3e175bca..6ab538dc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -112,24 +112,7 @@ See `docs/superpowers/specs/` for in-progress design specs and `docs/superpowers
 ## Commit & PR Guidelines
 
 ### Commit messages
-**When making any `git commit`, always extract the Jira ticket ID from the current branch name and include it in the message.** Use `/commit <description>` to do this automatically.
-
-Every commit on a PR branch **must** include a Jira ticket ID — enforced by the `check-commit-message` step in `.github/workflows/pr.yml`.
-
-Accepted formats:
-```
-SK-1234 short description
-SK-1234: short description
-feat: SK-1234 short description
-fix(SK-1234): short description
-```
-
-Exempt patterns (no ticket needed):
-- `[AUTOMATED]` — release version bumps only
-- `Merge ...` — merge commits
-- `Release ...` — release commits
-
-Conventional Commits prefixes (`feat:`, `fix:`, `chore:`, `docs:`) are encouraged but only valid alongside a Jira ID.
+Always use `/commit <description>` when committing — it extracts the Jira ticket ID from the branch name and validates the format against the CI check in `.github/workflows/pr.yml`.
 
 ### Branch naming
 Branch name must include your GitHub username:

From 9de9e92517991c3b5de80bceb04905452826ed93 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:10:38 +0530
Subject: [PATCH 07/30] fix: example

---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6ab538dc..6edbafd1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -121,7 +121,7 @@ Branch name must include your GitHub username:
 <github-username>/<ticket-id>-<short-description>
 ```
 
-Example: `karthik/GV-770-ext-auth-json-error`
+Example: `devesh/SK-770-ext-auth-json-error`
 
 ### PR template
 The `.github/pull_request_template.md` requires: **Why**, **Goal**, **Testing** sections. Tech debt section is optional.

From a9647cee1f2e41044865af2c12aa06f9fe3b79a8 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:16:36 +0530
Subject: [PATCH 08/30] SK-2832 rename /test to /quality, add 100% coverage
 requirement

---
 .claude/commands/{test.md => quality.md} | 40 +++++++++++++++++-------
 CLAUDE.md                                |  2 +-
 2 files changed, 29 insertions(+), 13 deletions(-)
 rename .claude/commands/{test.md => quality.md} (50%)

diff --git a/.claude/commands/test.md b/.claude/commands/quality.md
similarity index 50%
rename from .claude/commands/test.md
rename to .claude/commands/quality.md
index e690a355..77e363ed 100644
--- a/.claude/commands/test.md
+++ b/.claude/commands/quality.md
@@ -1,6 +1,6 @@
 ---
-name: test
-description: Quality pipeline — compile, checkstyle, build, tests, coverage analysis. Pass a class name to target a single test class.
+name: quality
+description: Quality pipeline — compile, checkstyle, build, tests, coverage check. Pass a class name to target a single test class.
 paths:
   - src/**/*.java
   - pom.xml
@@ -13,6 +13,19 @@ Use `$ARGUMENTS` to target a specific test class (e.g. `BearerTokenTests`). If e
 > Baseline failures are listed in CLAUDE.md under "Known Pre-existing Test Failures".
 > Do not investigate them unless specifically asked. Only report failures **beyond** that baseline.
 
+## Coverage Requirements
+
+**All code written or modified by Claude must have 100% coverage — both instruction and branch.**
+
+**All public interfaces must have 100% coverage — both instruction and branch.** This applies to:
+- All classes under `src/main/java/com/skyflow/vault/` (controllers, data, tokens, connection, audit, bin, detect)
+- All classes under `src/main/java/com/skyflow/config/`
+- All classes under `src/main/java/com/skyflow/serviceaccount/`
+
+Flag any gap as a blocker — **NEEDS FIXES** if coverage is below 100% on Claude-written or public interface code.
+
+---
+
 ## Pipeline
 
 ### Step 1 — Compile
@@ -45,12 +58,15 @@ mvn test -q 2>&1 | tail -40
 Report: tests run, failures, errors. Flag any pre-existing failures separately from new ones.
 
 ### Step 5 — Coverage analysis
-Flag any public interface class (`src/main/java/com/skyflow/vault/`, `src/main/java/com/skyflow/config/`, `src/main/java/com/skyflow/serviceaccount/`) that has no corresponding test file under `src/test/`.
+For every public interface class and every class touched by Claude in this session:
+- Check for a corresponding test file under `src/test/`
+- Check that every public method has at least one positive and one negative test case
+- Check that every branch (if/else, switch, try/catch) is covered
 
-For classes that do have tests, check whether each public method has at least one positive and one negative test case. List any gaps.
+List all gaps. Any gap on Claude-written or public interface code is a **blocker**.
 
 ### Step 6 — Edge case identification
-For any test class below complete coverage, identify missing scenarios:
+For any class below 100% coverage, identify missing scenarios:
 - Null / empty inputs
 - Invalid types / wrong enum values
 - Concurrent / reuse scenarios
@@ -61,13 +77,13 @@ Write concrete JUnit 4 test method stubs (not full implementations) for each gap
 ### Step 7 — Report
 
 ```
-| Step | Status | Notes |
-|---|---|---|
-| Compile | ✅ / ❌ | ... |
-| Checkstyle | ✅ / ❌ | ... |
-| Build | ✅ / ❌ | ... |
-| Tests | ✅ / ❌ | N passed, M failed |
-| Coverage gaps | ... | list classes |
+| Step             | Status    | Notes                        |
+|------------------|-----------|------------------------------|
+| Compile          | ✅ / ❌   | ...                          |
+| Checkstyle       | ✅ / ❌   | ...                          |
+| Build            | ✅ / ❌   | ...                          |
+| Tests            | ✅ / ❌   | N passed, M failed           |
+| Coverage (100%)  | ✅ / ❌   | list classes with gaps       |
 ```
 
 Conclude with **READY TO MERGE** or **NEEDS FIXES** and a prioritised fix list.
diff --git a/CLAUDE.md b/CLAUDE.md
index 6edbafd1..5e4747cd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -106,7 +106,7 @@ See `docs/superpowers/specs/` for in-progress design specs and `docs/superpowers
 - `/code-smell` — standalone structural smell analysis only (long methods, dead code, misplaced logic)
 - `/code-security` — standalone security audit only (credentials, input validation, HTTP security)
 - `/sdk-sample <feature>` — generate a sample file for a feature
-- `/test [ClassName]` — run quality pipeline (compile → checkstyle → build → test → coverage)
+- `/quality [ClassName]` — run quality pipeline (compile → checkstyle → build → test → 100% coverage check)
 - `/commit <description>` — stage check + Jira-aware commit (extracts ticket ID from branch name)
 
 ## Commit & PR Guidelines

From 1b54cee9f64682cca6f36f0ead1e011485fda9ea Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:17:29 +0530
Subject: [PATCH 09/30] SK-2832 reference /quality in code-review final verdict

---
 .claude/commands/code-review.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md
index 498fcfac..616c590c 100644
--- a/.claude/commands/code-review.md
+++ b/.claude/commands/code-review.md
@@ -105,3 +105,4 @@ Read the file `.claude/commands/code-security.md` and follow all of its instruct
 After all three steps, close with:
 1. A tech-debt summary table grouped by category (SDK Patterns / Error Handling / Naming / Tests / Smells / Security)
 2. A verdict: `APPROVE` / `APPROVE WITH FIXES` / `REQUEST CHANGES`
+3. If verdict is not `APPROVE`, remind: run `/quality` to verify compile, tests, and 100% coverage before merging.

From d3dc74b5f840fcc779758b519c8c5a3b81266d06 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:18:08 +0530
Subject: [PATCH 10/30] SK-2832 add /quality check step to /commit before
 committing

---
 .claude/commands/commit.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md
index 6aae4614..2a28b220 100644
--- a/.claude/commands/commit.md
+++ b/.claude/commands/commit.md
@@ -46,7 +46,11 @@ Validate against the `pr.yml` enforced pattern: `(\[?[A-Z]{1,10}-[1-9][0-9]*)|(\
 - Must contain a Jira ID — a bare description without a ticket ID will fail CI.
 - If validation fails, report the exact requirement and stop.
 
-## Step 4 — Commit
+## Step 4 — Quality check
+
+Before committing, confirm `/quality` has been run and passed (compile, tests, 100% coverage on changed code). If it has not been run, ask the user whether to run it now before proceeding.
+
+## Step 5 — Commit
 
 ```bash
 git commit -m "<assembled message>"

From 390b5133d56824085b334480f5589002a221846d Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:21:47 +0530
Subject: [PATCH 11/30] SK-2832 enforce /commit rule in CLAUDE.md, add /quality
 to review skill

---
 .claude/skills/requesting-code-review/SKILL.md | 2 ++
 CLAUDE.md                                      | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/.claude/skills/requesting-code-review/SKILL.md b/.claude/skills/requesting-code-review/SKILL.md
index 9f662842..46967910 100644
--- a/.claude/skills/requesting-code-review/SKILL.md
+++ b/.claude/skills/requesting-code-review/SKILL.md
@@ -31,6 +31,7 @@ paths:
 | SDK logic, patterns, naming, tests | `/code-review` — SDK checks + smell + security |
 | Structural debt only | `/code-smell` — standalone smell analysis |
 | Auth, credentials, tokens, HTTP | `/code-security` — standalone security audit |
+| Compile + tests + 100% coverage | `/quality` — run after fixing review findings, before `/commit` |
 
 For security-sensitive changes, run both:
 ```bash
@@ -74,3 +75,4 @@ HEAD_SHA=$(git rev-parse HEAD)
 - Fix Important issues before proceeding
 - Note Minor/Smell issues for later
 - Push back with reasoning if you disagree
+- After fixing: run `/quality` to verify compile + tests + 100% coverage, then `/commit`
diff --git a/CLAUDE.md b/CLAUDE.md
index 5e4747cd..c6487c09 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -112,7 +112,7 @@ See `docs/superpowers/specs/` for in-progress design specs and `docs/superpowers
 ## Commit & PR Guidelines
 
 ### Commit messages
-Always use `/commit <description>` when committing — it extracts the Jira ticket ID from the branch name and validates the format against the CI check in `.github/workflows/pr.yml`.
+**Never run `git commit` directly. Always use `/commit <description>`** — it extracts the Jira ticket ID from the branch name, confirms `/quality` has passed, and validates the format against the CI check in `.github/workflows/pr.yml`.
 
 ### Branch naming
 Branch name must include your GitHub username:

From 2f1eac1f68bdc1400d7380dcd234797b18176b30 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:24:09 +0530
Subject: [PATCH 12/30] SK-2832 require /quality before code-review, not just
 after

---
 .claude/commands/code-review.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md
index 616c590c..fae1ff9a 100644
--- a/.claude/commands/code-review.md
+++ b/.claude/commands/code-review.md
@@ -8,6 +8,10 @@ paths:
 
 You are a senior engineer performing a thorough code review on the Skyflow Java SDK.
 
+## Pre-requisite
+
+Before starting the review, confirm `/quality` has been run and passed (compile, tests, 100% coverage). If it has not been run, run it now before proceeding with the review.
+
 ## Scope
 
 Use `$ARGUMENTS` to determine scope:
@@ -105,4 +109,4 @@ Read the file `.claude/commands/code-security.md` and follow all of its instruct
 After all three steps, close with:
 1. A tech-debt summary table grouped by category (SDK Patterns / Error Handling / Naming / Tests / Smells / Security)
 2. A verdict: `APPROVE` / `APPROVE WITH FIXES` / `REQUEST CHANGES`
-3. If verdict is not `APPROVE`, remind: run `/quality` to verify compile, tests, and 100% coverage before merging.
+3. Remind: run `/quality` again after any fixes before merging.

From 80a5ebfc9e7c7c453673918d12eefb497887f21c Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:26:40 +0530
Subject: [PATCH 13/30] SK-2832 add descriptive header to checkstyle-on-edit.py

---
 .claude/hooks/checkstyle-on-edit.py | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/.claude/hooks/checkstyle-on-edit.py b/.claude/hooks/checkstyle-on-edit.py
index 4fd0787d..689b2b74 100644
--- a/.claude/hooks/checkstyle-on-edit.py
+++ b/.claude/hooks/checkstyle-on-edit.py
@@ -1,3 +1,18 @@
+# checkstyle-on-edit.py — PostToolUse hook for the Skyflow Java SDK.
+#
+# Registered in .claude/settings.json under hooks.PostToolUse with matcher "Edit|Write".
+# Fires automatically after every Edit or Write tool call on any file.
+#
+# What it does:
+#   - Ignores non-.java files immediately (no Maven overhead).
+#   - For files under src/main/java/, runs checkstyle scoped to that single file
+#     via -Dcheckstyle.includes=<relative-path> to keep it fast.
+#   - For files outside src/main/java/ (e.g. tests, samples), runs full-module checkstyle.
+#   - Prints the last 20 lines of any violations so Claude sees them in-turn
+#     without needing a separate /quality run.
+#
+# Config: checkstyle.xml — generated/ is excluded by pom.xml config so Fern
+# auto-generated code is never flagged.
 import sys, json, subprocess, os
 
 d = json.load(sys.stdin)

From fedad62c0373ff8e60b58e5a1c70e4677d039e26 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:52:41 +0530
Subject: [PATCH 14/30] SK-2832 remove paths from review skill, delegate all
 rules to code-review.md

---
 .claude/skills/requesting-code-review/SKILL.md | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/.claude/skills/requesting-code-review/SKILL.md b/.claude/skills/requesting-code-review/SKILL.md
index 46967910..e4290c7c 100644
--- a/.claude/skills/requesting-code-review/SKILL.md
+++ b/.claude/skills/requesting-code-review/SKILL.md
@@ -1,9 +1,6 @@
 ---
 name: requesting-code-review
 description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
-paths:
-  - src/main/java/**/*.java
-  - src/test/java/**/*.java
 ---
 
 # Requesting Code Review
@@ -50,7 +47,8 @@ Agent tool (general-purpose):
     You are a senior engineer reviewing the Skyflow Java SDK.
 
     Read CLAUDE.md for project conventions, then read and follow
-    .claude/commands/code-review.md for the full review process.
+    .claude/commands/code-review.md for the full review process
+    including all rules, output format, and act-on-feedback guidance.
 
     Git range to review:
       Base: {BASE_SHA}
@@ -70,9 +68,4 @@ BASE_SHA=$(git merge-base main HEAD)   # branch vs main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**3. Act on feedback:**
-- Fix Critical issues immediately
-- Fix Important issues before proceeding
-- Note Minor/Smell issues for later
-- Push back with reasoning if you disagree
-- After fixing: run `/quality` to verify compile + tests + 100% coverage, then `/commit`
+All review rules, severity definitions, output format, and post-review steps are defined in `.claude/commands/code-review.md` — that file is the single source of truth.

From cadbca9d196248cd74d8c5d8acdc2d08705f5d9d Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:55:20 +0530
Subject: [PATCH 15/30] SK-2832 restore paths to review skill for proactive
 review triggers

---
 .claude/skills/requesting-code-review/SKILL.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.claude/skills/requesting-code-review/SKILL.md b/.claude/skills/requesting-code-review/SKILL.md
index e4290c7c..cdb1ddf2 100644
--- a/.claude/skills/requesting-code-review/SKILL.md
+++ b/.claude/skills/requesting-code-review/SKILL.md
@@ -1,6 +1,9 @@
 ---
 name: requesting-code-review
 description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+paths:
+  - src/main/java/**/*.java
+  - src/test/java/**/*.java
 ---
 
 # Requesting Code Review

From 967c3c99bab092277a2b40b1d901c72cfae3c87b Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 19:58:38 +0530
Subject: [PATCH 16/30] SK-2832 add devesh to cspell wordlist

---
 .cspell.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.cspell.json b/.cspell.json
index a982f837..6f06b9ef 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -99,7 +99,8 @@
     "detok",
     "qhdmceurtnlz",
     "ngrok",
-    "obac"
+    "obac",
+    "devesh"
   ],
   "languageSettings": [
     {

From ed287b107f8ef75277e31cf30fedb669ed2e85e7 Mon Sep 17 00:00:00 2001
From: Devesh-Skyflow <devesh.bhardwaj@skyflow.com>
Date: Fri, 29 May 2026 20:00:08 +0530
Subject: [PATCH 17/30] SK-2832 suppress cspell on branch name example, revert
 devesh from wordlist

---
 .cspell.json | 3 +--
 CLAUDE.md    | 1 +
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.cspell.json b/.cspell.json
index 6f06b9ef..a982f837 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -99,8 +99,7 @@
     "detok",
     "qhdmceurtnlz",
     "ngrok",
-    "obac",
-    "devesh"
+    "obac"
   ],
   "languageSettings": [
     {
diff --git a/CLAUDE.md b/CLAUDE.md
index c6487c09..a5d3e94c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -121,6 +121,7 @@ Branch name must include your GitHub username:
 <github-username>/<ticket-id>-<short-description>
 ```
 
+<!-- cspell:disable-next-line -->
 Example: `devesh/SK-770-ext-auth-json-error`
 
 ### PR template

From e437f4485d5a1c22f1d3e50a3c8394b471f0f28b Mon Sep 17 00:00:00 2001
From: skyflow-bharti <bharti.sagar@skyflow.com>
Date: Mon, 1 Jun 2026 12:29:05 +0530
Subject: [PATCH 18/30] SK-2832 update the claude setup and remove duplicate
 things

---
 .claude/commands/code-patterns.md             | 59 +++++++++++++
 .../commands/{quality.md => code-quality.md}  |  2 +-
 .claude/commands/code-review.md               | 68 ++-------------
 .claude/commands/code-security.md             |  2 +
 .claude/commands/code-smell.md                |  2 +
 .claude/commands/commit.md                    |  2 +-
 .../skills/requesting-code-review/SKILL.md    |  2 +-
 CLAUDE.md                                     | 24 +++++-
 .../java/com/skyflow/ConnectionClient.java    |  4 +-
 src/main/java/com/skyflow/VaultClient.java    | 86 ++++++++++++++++---
 .../java/com/skyflow/utils/HttpUtility.java   |  5 +-
 11 files changed, 172 insertions(+), 84 deletions(-)
 create mode 100644 .claude/commands/code-patterns.md
 rename .claude/commands/{quality.md => code-quality.md} (99%)

diff --git a/.claude/commands/code-patterns.md b/.claude/commands/code-patterns.md
new file mode 100644
index 00000000..dfacb1d8
--- /dev/null
+++ b/.claude/commands/code-patterns.md
@@ -0,0 +1,59 @@
+---
+name: code-patterns
+description: SDK pattern review — request/response/options shape, error handling, naming, test coverage, code quality.
+paths:
+  - src/main/java/**/*.java
+  - src/test/java/**/*.java
+exclude:
+  - src/main/java/com/skyflow/generated/**
+---
+
+You are a senior engineer reviewing the Skyflow Java SDK against its established patterns.
+
+Coding rules (error handling, request/response shape, naming, no magic strings) are defined in CLAUDE.md — apply those during this review.
+
+## Scope
+
+Files are passed in by the caller (usually `/code-review`). Review only those files.
+
+---
+
+## 1. Test coverage
+
+- Every public method must have at least one positive and one negative test
+- Tests must use `Assert.assertEquals` / `Assert.assertNull` — not just `Assert.fail` guards
+- No mocking of the production class under test
+- Reflection-based tests on private methods are acceptable only when no public API exercises the method
+
+---
+
+## 2. Code quality
+
+- No magic strings for API field names — use `Constants` or `ErrorMessage` enums
+- No duplicate validation logic across request classes — belongs in `Validations`
+- No `@SuppressWarnings` without a comment explaining why
+- `LogUtil.printWarningLog` must be used for deprecation warnings, not `System.err`
+
+---
+
+## Output format
+
+Group findings by file:
+
+```
+### path/to/File.java
+
+| Severity   | Line | Finding                                                    |
+|------------|------|------------------------------------------------------------|
+| Critical   | 42   | SkyflowException swallowed in catch block                  |
+| Bug        | 87   | skyflow_id not normalised to skyflowId                     |
+| Quality    | 103  | Magic string "records" — use Constants                     |
+```
+
+**Severities:**
+| Level | Meaning |
+|---|---|
+| **Critical** | Data loss, silent failure, security risk — must fix before merge |
+| **Bug** | Wrong behaviour, incorrect output — must fix before merge |
+| **Edge Case** | Unhandled input that will cause runtime failure — fix before merge |
+| **Quality** | Maintainability issue, naming violation, missing pattern — fix before merge |
diff --git a/.claude/commands/quality.md b/.claude/commands/code-quality.md
similarity index 99%
rename from .claude/commands/quality.md
rename to .claude/commands/code-quality.md
index 77e363ed..21ce6aa9 100644
--- a/.claude/commands/quality.md
+++ b/.claude/commands/code-quality.md
@@ -1,5 +1,5 @@
 ---
-name: quality
+name: code-quality
 description: Quality pipeline — compile, checkstyle, build, tests, coverage check. Pass a class name to target a single test class.
 paths:
   - src/**/*.java
diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md
index fae1ff9a..6fa74777 100644
--- a/.claude/commands/code-review.md
+++ b/.claude/commands/code-review.md
@@ -4,13 +4,15 @@ description: Full code review — SDK patterns, naming, test coverage, then runs
 paths:
   - src/main/java/**/*.java
   - src/test/java/**/*.java
+exclude:
+  - src/main/java/com/skyflow/generated/**
 ---
 
 You are a senior engineer performing a thorough code review on the Skyflow Java SDK.
 
 ## Pre-requisite
 
-Before starting the review, confirm `/quality` has been run and passed (compile, tests, 100% coverage). If it has not been run, run it now before proceeding with the review.
+Before starting the review, confirm `/code-quality` has been run and passed (compile, tests, 100% coverage). If it has not been run, run it now before proceeding with the review.
 
 ## Scope
 
@@ -28,67 +30,7 @@ Use `$ARGUMENTS` to determine scope:
 
 ## Step 1 — SDK Pattern Review
 
-Check the files in scope against the rules below.
-
-### 1. Request / Response / Options patterns
-
-- Request builders are plain data holders — validation happens in `Validations.validateXxxRequest()` inside the controller, not in `build()`. Flag if validation logic is duplicated outside `Validations`.
-- Response getters returning `ArrayList<HashMap<String, Object>>` is the established SDK pattern — do not flag these as violations.
-- All response classes must have `getErrors()` returning `null` (not absent) when no errors.
-- No separate `*Options` classes exist — options are fields on the request builder itself.
-- SDK must not add field-level null/empty validation on top of what the backend enforces. Only structural checks (`table == null`, `values == null`) are permitted.
-
-### 2. Error handling
-
-- All public methods must declare `throws SkyflowException`
-- `SkyflowException` must be thrown (not swallowed) on invalid input
-- No `System.out.println` or bare `e.printStackTrace()` — use `LogUtil`
-- Catch blocks must not silently drop exceptions
-- `catch (Exception e)` without re-throw or explicit handling is a critical issue
-
-### 3. Naming conventions and response field normalisation
-
-Follow the conventions in CLAUDE.md under "Naming Conventions". Key enforcement points:
-- Acronyms as words: `skyflowId`, `tokenUri`, `clientId` — never uppercase abbreviations
-- Builder setters: `setFooId()` not `setFooID()`; constants: `UPPER_SNAKE_CASE`; classes: `PascalCase`
-- Response maps: `skyflowId` (camelCase) only — never `skyflow_id`; `getErrors()` must be present on every response class
-- Deprecated methods: `@Deprecated(since = "x.x", forRemoval = true)` + `@deprecated` Javadoc with `{@link}` to replacement
-
-### 5. Test coverage
-
-- Every public method must have at least one positive and one negative test
-- Tests must use `Assert.assertEquals` / `Assert.assertNull` — not just `Assert.fail` guards
-- No mocking of the production class under test
-- Reflection-based tests on private methods are acceptable only when no public API exercises the method
-
-### 6. Code quality
-
-- No magic strings for API field names — use `Constants` or `ErrorMessage` enums
-- No duplicate validation logic across request classes — belongs in `Validations`
-- No `@SuppressWarnings` without a comment explaining why
-- `LogUtil.printWarningLog` must be used for deprecation warnings, not `System.err`
-
-### Output for Step 1
-
-Group findings by file:
-
-```
-### path/to/File.java
-
-| Severity   | Line | Finding                                                    |
-|------------|------|------------------------------------------------------------|
-| Critical   | 42   | SkyflowException swallowed in catch block                  |
-| Bug        | 87   | skyflow_id not normalised to skyflowId                     |
-| Quality    | 103  | Magic string "records" — use Constants                     |
-```
-
-**Severities:**
-| Level | Meaning |
-|---|---|
-| **Critical** | Data loss, silent failure, security risk — must fix before merge |
-| **Bug** | Wrong behaviour, incorrect output — must fix before merge |
-| **Edge Case** | Unhandled input that will cause runtime failure — fix before merge |
-| **Quality** | Maintainability issue, naming violation, missing pattern — fix before merge |
+Read the file `.claude/commands/code-patterns.md` and follow all of its instructions for the same files in scope. Produce its full output (per-file findings table + severity key).
 
 ---
 
@@ -109,4 +51,4 @@ Read the file `.claude/commands/code-security.md` and follow all of its instruct
 After all three steps, close with:
 1. A tech-debt summary table grouped by category (SDK Patterns / Error Handling / Naming / Tests / Smells / Security)
 2. A verdict: `APPROVE` / `APPROVE WITH FIXES` / `REQUEST CHANGES`
-3. Remind: run `/quality` again after any fixes before merging.
+3. Remind: run `/code-quality` again after any fixes before merging.
diff --git a/.claude/commands/code-security.md b/.claude/commands/code-security.md
index 0fa69923..7de061f6 100644
--- a/.claude/commands/code-security.md
+++ b/.claude/commands/code-security.md
@@ -7,6 +7,8 @@ paths:
   - src/main/java/com/skyflow/utils/**/*.java
   - src/main/java/com/skyflow/vault/controller/**/*.java
   - pom.xml
+exclude:
+  - src/main/java/com/skyflow/generated/**
 ---
 
 You are a security engineer auditing the Skyflow Java SDK for vulnerabilities.
diff --git a/.claude/commands/code-smell.md b/.claude/commands/code-smell.md
index f456a8d8..4cc5953c 100644
--- a/.claude/commands/code-smell.md
+++ b/.claude/commands/code-smell.md
@@ -3,6 +3,8 @@ name: code-smell
 description: Structural smell analysis + spell check — long methods, dead code, misplaced validation, deep nesting, magic numbers. Does not check patterns or security.
 paths:
   - src/main/java/**/*.java
+exclude:
+  - src/main/java/com/skyflow/generated/**
 ---
 
 You are a senior engineer performing a code smell analysis on the Skyflow Java SDK.
diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md
index 2a28b220..651cc507 100644
--- a/.claude/commands/commit.md
+++ b/.claude/commands/commit.md
@@ -48,7 +48,7 @@ Validate against the `pr.yml` enforced pattern: `(\[?[A-Z]{1,10}-[1-9][0-9]*)|(\
 
 ## Step 4 — Quality check
 
-Before committing, confirm `/quality` has been run and passed (compile, tests, 100% coverage on changed code). If it has not been run, ask the user whether to run it now before proceeding.
+Before committing, confirm `/code-quality` has been run and passed (compile, tests, 100% coverage on changed code). If it has not been run, ask the user whether to run it now before proceeding.
 
 ## Step 5 — Commit
 
diff --git a/.claude/skills/requesting-code-review/SKILL.md b/.claude/skills/requesting-code-review/SKILL.md
index cdb1ddf2..5d89b793 100644
--- a/.claude/skills/requesting-code-review/SKILL.md
+++ b/.claude/skills/requesting-code-review/SKILL.md
@@ -31,7 +31,7 @@ paths:
 | SDK logic, patterns, naming, tests | `/code-review` — SDK checks + smell + security |
 | Structural debt only | `/code-smell` — standalone smell analysis |
 | Auth, credentials, tokens, HTTP | `/code-security` — standalone security audit |
-| Compile + tests + 100% coverage | `/quality` — run after fixing review findings, before `/commit` |
+| Compile + tests + 100% coverage | `/code-quality` — run after fixing review findings, before `/commit` |
 
 For security-sensitive changes, run both:
 ```bash
diff --git a/CLAUDE.md b/CLAUDE.md
index a5d3e94c..6e83fcb2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,6 +5,8 @@ paths:
   - src/**/*.java
   - pom.xml
   - checkstyle.xml
+exclude:
+  - src/main/java/com/skyflow/generated/**
 ---
 
 # Skyflow Java SDK — Claude Code Instructions
@@ -58,6 +60,26 @@ docs/
 - **Response maps:** always use `skyflowId` (camelCase) — the raw API returns `skyflow_id` (snake_case) which VaultController normalises before returning to callers
 - **Constants class:** use `com.skyflow.utils.Constants` for string literals; `ErrorMessage` enum for error message strings
 
+## SDK Coding Rules
+
+These apply whenever writing or modifying code — not just during review.
+
+### Error handling
+- All public methods must declare `throws SkyflowException`
+- Never swallow exceptions — always re-throw as `SkyflowException`
+- No `System.out.println` or `e.printStackTrace()` — use `LogUtil`
+- `catch (Exception e)` without re-throw is always a bug
+
+### Request / Response patterns
+- Request builders are data holders — validation belongs in `Validations.validateXxxRequest()`, not in `build()`
+- No separate `*Options` classes — options are fields on the request builder itself
+- All response classes must have `getErrors()` returning `null` when no errors
+
+### String literals
+- Use `Constants` for string literals and `ErrorMessage` enum for error messages — no magic strings
+
+---
+
 ## Build and Test
 
 ```bash
@@ -112,7 +134,7 @@ See `docs/superpowers/specs/` for in-progress design specs and `docs/superpowers
 ## Commit & PR Guidelines
 
 ### Commit messages
-**Never run `git commit` directly. Always use `/commit <description>`** — it extracts the Jira ticket ID from the branch name, confirms `/quality` has passed, and validates the format against the CI check in `.github/workflows/pr.yml`.
+**Never run `git commit` directly. Always use `/commit <description>`** — it extracts the Jira ticket ID from the branch name, confirms `/code-quality` has passed, and validates the format against the CI check in `.github/workflows/pr.yml`.
 
 ### Branch naming
 Branch name must include your GitHub username:
diff --git a/src/main/java/com/skyflow/ConnectionClient.java b/src/main/java/com/skyflow/ConnectionClient.java
index d67122ad..3715b509 100644
--- a/src/main/java/com/skyflow/ConnectionClient.java
+++ b/src/main/java/com/skyflow/ConnectionClient.java
@@ -40,7 +40,7 @@ protected void updateConnectionConfig(ConnectionConfig connectionConfig) throws
         prioritiseCredentials();
     }
 
-    protected void setBearerToken() throws SkyflowException {
+    protected synchronized void setBearerToken() throws SkyflowException {
         prioritiseCredentials();
         Validations.validateCredentials(this.finalCredentials);
         if (this.finalCredentials.getApiKey() != null) {
@@ -89,7 +89,7 @@ private void prioritiseCredentials() throws SkyflowException {
         } catch (SkyflowException e) {
             throw e;
         } catch (Exception e) {
-            throw new RuntimeException(e);
+            throw new SkyflowException(ErrorCode.SERVER_ERROR.getCode(), ErrorMessage.EmptyCredentials.getMessage());
         }
     }
 
diff --git a/src/main/java/com/skyflow/VaultClient.java b/src/main/java/com/skyflow/VaultClient.java
index 1d5e5d74..5060c48f 100644
--- a/src/main/java/com/skyflow/VaultClient.java
+++ b/src/main/java/com/skyflow/VaultClient.java
@@ -1,5 +1,18 @@
 package com.skyflow;
 
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.util.ArrayList;
+import java.util.Base64;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
+
 import com.skyflow.config.Credentials;
 import com.skyflow.config.VaultConfig;
 import com.skyflow.enums.DetectEntities;
@@ -10,8 +23,24 @@
 import com.skyflow.generated.rest.ApiClient;
 import com.skyflow.generated.rest.ApiClientBuilder;
 import com.skyflow.generated.rest.resources.files.FilesClient;
-import com.skyflow.generated.rest.resources.files.requests.*;
-import com.skyflow.generated.rest.resources.files.types.*;
+import com.skyflow.generated.rest.resources.files.requests.DeidentifyFileAudioRequestDeidentifyAudio;
+import com.skyflow.generated.rest.resources.files.requests.DeidentifyFileDocumentPdfRequestDeidentifyPdf;
+import com.skyflow.generated.rest.resources.files.requests.DeidentifyFileImageRequestDeidentifyImage;
+import com.skyflow.generated.rest.resources.files.requests.DeidentifyFileRequestDeidentifyDocument;
+import com.skyflow.generated.rest.resources.files.requests.DeidentifyFileRequestDeidentifyPresentation;
+import com.skyflow.generated.rest.resources.files.requests.DeidentifyFileRequestDeidentifySpreadsheet;
+import com.skyflow.generated.rest.resources.files.requests.DeidentifyFileRequestDeidentifyStructuredText;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileAudioRequestDeidentifyAudioEntityTypesItem;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileAudioRequestDeidentifyAudioOutputTranscription;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileDocumentPdfRequestDeidentifyPdfEntityTypesItem;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileImageRequestDeidentifyImageEntityTypesItem;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileImageRequestDeidentifyImageMaskingMethod;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileRequestDeidentifyDocumentEntityTypesItem;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileRequestDeidentifyPresentationEntityTypesItem;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileRequestDeidentifySpreadsheetEntityTypesItem;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileRequestDeidentifyStructuredTextEntityTypesItem;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileRequestDeidentifyTextEntityTypesItem;
+import com.skyflow.generated.rest.resources.files.types.DeidentifyFileRequestEntityTypesItem;
 import com.skyflow.generated.rest.resources.query.QueryClient;
 import com.skyflow.generated.rest.resources.records.RecordsClient;
 import com.skyflow.generated.rest.resources.records.requests.RecordServiceBatchOperationBody;
@@ -24,8 +53,40 @@
 import com.skyflow.generated.rest.resources.tokens.TokensClient;
 import com.skyflow.generated.rest.resources.tokens.requests.V1DetokenizePayload;
 import com.skyflow.generated.rest.resources.tokens.requests.V1TokenizePayload;
+import com.skyflow.generated.rest.types.BatchRecordMethod;
+import com.skyflow.generated.rest.types.DeidentifyStringResponse;
+import com.skyflow.generated.rest.types.FileData;
+import com.skyflow.generated.rest.types.FileDataDataFormat;
+import com.skyflow.generated.rest.types.FileDataDeidentifyAudio;
+import com.skyflow.generated.rest.types.FileDataDeidentifyAudioDataFormat;
+import com.skyflow.generated.rest.types.FileDataDeidentifyDocument;
+import com.skyflow.generated.rest.types.FileDataDeidentifyDocumentDataFormat;
+import com.skyflow.generated.rest.types.FileDataDeidentifyImage;
+import com.skyflow.generated.rest.types.FileDataDeidentifyImageDataFormat;
+import com.skyflow.generated.rest.types.FileDataDeidentifyPdf;
+import com.skyflow.generated.rest.types.FileDataDeidentifyPresentation;
+import com.skyflow.generated.rest.types.FileDataDeidentifyPresentationDataFormat;
+import com.skyflow.generated.rest.types.FileDataDeidentifySpreadsheet;
+import com.skyflow.generated.rest.types.FileDataDeidentifySpreadsheetDataFormat;
+import com.skyflow.generated.rest.types.FileDataDeidentifyStructuredText;
+import com.skyflow.generated.rest.types.FileDataDeidentifyStructuredTextDataFormat;
+import com.skyflow.generated.rest.types.FileDataDeidentifyText;
+import com.skyflow.generated.rest.types.Format;
+import com.skyflow.generated.rest.types.FormatMaskedItem;
+import com.skyflow.generated.rest.types.FormatPlaintextItem;
+import com.skyflow.generated.rest.types.FormatRedactedItem;
+import com.skyflow.generated.rest.types.ShiftDates;
+import com.skyflow.generated.rest.types.ShiftDatesEntityTypesItem;
+import com.skyflow.generated.rest.types.StringResponseEntities;
+import com.skyflow.generated.rest.types.TokenTypeMapping;
+import com.skyflow.generated.rest.types.TokenTypeMappingEntityOnlyItem;
+import com.skyflow.generated.rest.types.TokenTypeMappingEntityUnqCounterItem;
+import com.skyflow.generated.rest.types.TokenTypeMappingVaultTokenItem;
 import com.skyflow.generated.rest.types.Transformations;
-import com.skyflow.generated.rest.types.*;
+import com.skyflow.generated.rest.types.V1BatchRecord;
+import com.skyflow.generated.rest.types.V1DetokenizeRecordRequest;
+import com.skyflow.generated.rest.types.V1FieldRecords;
+import com.skyflow.generated.rest.types.V1TokenizeRecordRequest;
 import com.skyflow.logs.InfoLogs;
 import com.skyflow.serviceaccount.util.Token;
 import com.skyflow.utils.Constants;
@@ -36,24 +97,23 @@
 import com.skyflow.vault.data.InsertRequest;
 import com.skyflow.vault.data.UpdateRequest;
 import com.skyflow.vault.detect.DeidentifyFileRequest;
-import com.skyflow.vault.detect.*;
+import com.skyflow.vault.detect.DeidentifyTextRequest;
+import com.skyflow.vault.detect.DeidentifyTextResponse;
+import com.skyflow.vault.detect.EntityInfo;
+import com.skyflow.vault.detect.ReidentifyTextRequest;
+import com.skyflow.vault.detect.TextIndex;
+import com.skyflow.vault.detect.TokenFormat;
 import com.skyflow.vault.tokens.ColumnValue;
 import com.skyflow.vault.tokens.DetokenizeData;
 import com.skyflow.vault.tokens.DetokenizeRequest;
 import com.skyflow.vault.tokens.TokenizeRequest;
+
 import io.github.cdimascio.dotenv.Dotenv;
 import io.github.cdimascio.dotenv.DotenvException;
 import okhttp3.ConnectionPool;
 import okhttp3.OkHttpClient;
 import okhttp3.Request;
 
-import java.io.File;
-import java.io.IOException;
-import java.nio.file.Files;
-import java.util.*;
-import java.util.concurrent.TimeUnit;
-import java.util.stream.Collectors;
-
 
 public class VaultClient {
     private final VaultConfig vaultConfig;
@@ -232,7 +292,7 @@ protected File getFileForFileUpload(FileUploadRequest fileUploadRequest) throws
         return null;
     }
 
-    protected void setBearerToken() throws SkyflowException {
+    protected synchronized void setBearerToken() throws SkyflowException {
         prioritiseCredentials();
         Validations.validateCredentials(this.finalCredentials);
         if (this.finalCredentials.getApiKey() != null) {
@@ -879,7 +939,7 @@ private void prioritiseCredentials() throws SkyflowException {
         } catch (SkyflowException e) {
             throw e;
         } catch (Exception e) {
-            throw new RuntimeException(e);
+            throw new SkyflowException(ErrorCode.SERVER_ERROR.getCode(), ErrorMessage.EmptyCredentials.getMessage());
         }
     }
 }
diff --git a/src/main/java/com/skyflow/utils/HttpUtility.java b/src/main/java/com/skyflow/utils/HttpUtility.java
index 671e2415..811bd553 100644
--- a/src/main/java/com/skyflow/utils/HttpUtility.java
+++ b/src/main/java/com/skyflow/utils/HttpUtility.java
@@ -2,6 +2,7 @@
 
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
+import com.skyflow.errors.ErrorMessage;
 import com.skyflow.errors.SkyflowException;
 
 import java.io.*;
@@ -83,8 +84,8 @@ public static String sendRequest(String method, URL url, JsonObject params, Map<
                 if (connection.getErrorStream() != null)
                     streamReader = new InputStreamReader(connection.getErrorStream());
                 else {
-                    String description = appendRequestId("replace with description", requestID);
-                    throw new SkyflowException(description);
+                    String description = appendRequestId(ErrorMessage.ErrorOccurred.getMessage(), requestID);
+                    throw new SkyflowException(httpCode, new Throwable(description), responseHeaders, "{}");
                 }
             } else {
                 streamReader = new InputStreamReader(connection.getInputStream());

From d571befedd8cff100b2a6fa793c0eaa3e7f77ddf Mon Sep 17 00:00:00 2001
From: skyflow-bharti <bharti.sagar@skyflow.com>
Date: Mon, 1 Jun 2026 12:49:07 +0530
Subject: [PATCH 19/30] SK-2832 Rename the commit md file to git-commit

---
 .claude/commands/{commit.md => git-commit.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename .claude/commands/{commit.md => git-commit.md} (100%)

diff --git a/.claude/commands/commit.md b/.claude/commands/git-commit.md
similarity index 100%
rename from .claude/commands/commit.md
rename to .claude/commands/git-commit.md

From 5ad91d6eae5dfee4c91113b344a1cadc247713e3 Mon Sep 17 00:00:00 2001
From: skyflow-bharti <bharti.sagar@skyflow.com>
Date: Mon, 1 Jun 2026 15:30:10 +0530
Subject: [PATCH 20/30] SK-2832 Removed the duplicate section from commands

---
 .claude/commands/code-patterns.md             | 12 +++--------
 .claude/commands/code-quality.md              | 15 +++++++-------
 .claude/commands/code-review.md               |  3 +--
 .claude/commands/code-security.md             |  8 ++------
 .claude/commands/code-smell.md                |  6 ++++--
 .claude/commands/git-commit.md                |  7 ++++---
 .claude/commands/sdk-sample.md                |  4 ++++
 .../skills/requesting-code-review/SKILL.md    |  3 +++
 CLAUDE.md                                     | 20 ++++++++++++++-----
 9 files changed, 44 insertions(+), 34 deletions(-)

diff --git a/.claude/commands/code-patterns.md b/.claude/commands/code-patterns.md
index dfacb1d8..731eccd5 100644
--- a/.claude/commands/code-patterns.md
+++ b/.claude/commands/code-patterns.md
@@ -6,12 +6,11 @@ paths:
   - src/test/java/**/*.java
 exclude:
   - src/main/java/com/skyflow/generated/**
+context: fork
 ---
 
 You are a senior engineer reviewing the Skyflow Java SDK against its established patterns.
 
-Coding rules (error handling, request/response shape, naming, no magic strings) are defined in CLAUDE.md — apply those during this review.
-
 ## Scope
 
 Files are passed in by the caller (usually `/code-review`). Review only those files.
@@ -21,18 +20,13 @@ Files are passed in by the caller (usually `/code-review`). Review only those fi
 ## 1. Test coverage
 
 - Every public method must have at least one positive and one negative test
-- Tests must use `Assert.assertEquals` / `Assert.assertNull` — not just `Assert.fail` guards
-- No mocking of the production class under test
-- Reflection-based tests on private methods are acceptable only when no public API exercises the method
+- Follow the Tests coding rules (Assert conventions, no production class mocking, 100% coverage)
 
 ---
 
 ## 2. Code quality
 
-- No magic strings for API field names — use `Constants` or `ErrorMessage` enums
-- No duplicate validation logic across request classes — belongs in `Validations`
-- No `@SuppressWarnings` without a comment explaining why
-- `LogUtil.printWarningLog` must be used for deprecation warnings, not `System.err`
+- Follow the Code quality coding rules (@SuppressWarnings, LogUtil for deprecation)
 
 ---
 
diff --git a/.claude/commands/code-quality.md b/.claude/commands/code-quality.md
index 21ce6aa9..423113bd 100644
--- a/.claude/commands/code-quality.md
+++ b/.claude/commands/code-quality.md
@@ -4,23 +4,24 @@ description: Quality pipeline — compile, checkstyle, build, tests, coverage ch
 paths:
   - src/**/*.java
   - pom.xml
+exclude:
+  - src/main/java/com/skyflow/generated/**
+context: fork
 ---
 
 Run the Skyflow Java SDK quality pipeline.
 
 Use `$ARGUMENTS` to target a specific test class (e.g. `BearerTokenTests`). If empty, run the full suite.
 
-> Baseline failures are listed in CLAUDE.md under "Known Pre-existing Test Failures".
+> Baseline failures are documented in the Known Pre-existing Test Failures table.
 > Do not investigate them unless specifically asked. Only report failures **beyond** that baseline.
 
 ## Coverage Requirements
 
-**All code written or modified by Claude must have 100% coverage — both instruction and branch.**
-
-**All public interfaces must have 100% coverage — both instruction and branch.** This applies to:
-- All classes under `src/main/java/com/skyflow/vault/` (controllers, data, tokens, connection, audit, bin, detect)
-- All classes under `src/main/java/com/skyflow/config/`
-- All classes under `src/main/java/com/skyflow/serviceaccount/`
+Follow the Tests coding rules (100% instruction + branch coverage). Public interface packages:
+- `src/main/java/com/skyflow/vault/` (controllers, data, tokens, connection, audit, bin, detect)
+- `src/main/java/com/skyflow/config/`
+- `src/main/java/com/skyflow/serviceaccount/`
 
 Flag any gap as a blocker — **NEEDS FIXES** if coverage is below 100% on Claude-written or public interface code.
 
diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md
index 6fa74777..1124549d 100644
--- a/.claude/commands/code-review.md
+++ b/.claude/commands/code-review.md
@@ -6,6 +6,7 @@ paths:
   - src/test/java/**/*.java
 exclude:
   - src/main/java/com/skyflow/generated/**
+context: fork
 ---
 
 You are a senior engineer performing a thorough code review on the Skyflow Java SDK.
@@ -24,8 +25,6 @@ Use `$ARGUMENTS` to determine scope:
   git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
   ```
 
-**Skip entirely:** `src/main/java/com/skyflow/generated/` — Fern-generated REST client, read-only.
-
 ---
 
 ## Step 1 — SDK Pattern Review
diff --git a/.claude/commands/code-security.md b/.claude/commands/code-security.md
index 7de061f6..f03660ff 100644
--- a/.claude/commands/code-security.md
+++ b/.claude/commands/code-security.md
@@ -2,13 +2,11 @@
 name: code-security
 description: Security audit — credential exposure, input validation, path traversal, HTTP security, token lifecycle, dependency CVEs.
 paths:
-  - src/main/java/com/skyflow/serviceaccount/**/*.java
-  - src/main/java/com/skyflow/config/**/*.java
-  - src/main/java/com/skyflow/utils/**/*.java
-  - src/main/java/com/skyflow/vault/controller/**/*.java
+  - src/main/java/com/skyflow/**/*.java
   - pom.xml
 exclude:
   - src/main/java/com/skyflow/generated/**
+context: fork
 ---
 
 You are a security engineer auditing the Skyflow Java SDK for vulnerabilities.
@@ -20,8 +18,6 @@ Use `$ARGUMENTS` to determine target files. If none provided, run:
 git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
 ```
 
-**Skip:** `src/main/java/com/skyflow/generated/` — observations only, no edits.
-
 ## Security Checks
 
 ### 1. Credential and token exposure (Critical)
diff --git a/.claude/commands/code-smell.md b/.claude/commands/code-smell.md
index 4cc5953c..ee7ecdda 100644
--- a/.claude/commands/code-smell.md
+++ b/.claude/commands/code-smell.md
@@ -3,8 +3,12 @@ name: code-smell
 description: Structural smell analysis + spell check — long methods, dead code, misplaced validation, deep nesting, magic numbers. Does not check patterns or security.
 paths:
   - src/main/java/**/*.java
+  - src/test/java/**/*.java
+  - .claude/**/*.md
+  - docs/**/*.md
 exclude:
   - src/main/java/com/skyflow/generated/**
+context: fork
 ---
 
 You are a senior engineer performing a code smell analysis on the Skyflow Java SDK.
@@ -18,8 +22,6 @@ Use `$ARGUMENTS` to determine scope:
   git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
   ```
 
-**Skip entirely:** `src/main/java/com/skyflow/generated/` — Fern-generated REST client, read-only.
-
 ---
 
 ## Spell check
diff --git a/.claude/commands/git-commit.md b/.claude/commands/git-commit.md
index 651cc507..429ca746 100644
--- a/.claude/commands/git-commit.md
+++ b/.claude/commands/git-commit.md
@@ -1,6 +1,7 @@
 ---
-name: commit
+name: git-commit
 description: Stage check + Jira-aware commit — extracts ticket ID from branch name and validates against pr.yml commit-message check.
+context: fork
 ---
 
 Create a git commit for staged changes on the current branch.
@@ -13,7 +14,7 @@ Use `$ARGUMENTS` as the commit message description. If empty, ask the user for a
 git rev-parse --abbrev-ref HEAD
 ```
 
-Extract the Jira ticket ID using the pattern `[A-Z]{1,10}-[0-9]+`:
+Extract the Jira ticket ID using the pattern `[A-Z]{1,5}-[0-9]+`:
 - `devesh/SK-1234-fix-foo` → `SK-1234`
 - `karthik/GV-770-ext-auth-json-error` → `GV-770`
 - `username/SDK-2814-some-fix` → `SDK-2814`
@@ -42,7 +43,7 @@ feat: SK-1234 add bulk insert support
 fix: GV-770 handle null bearer token on refresh
 ```
 
-Validate against the `pr.yml` enforced pattern: `(\[?[A-Z]{1,10}-[1-9][0-9]*)|(\[AUTOMATED\])|(Merge)|(Release)`
+Validate against the `pr.yml` enforced pattern: `(\[?[A-Z]{1,5}-[1-9][0-9]*)|(\[AUTOMATED\])|(Merge)|(Release).+$`
 - Must contain a Jira ID — a bare description without a ticket ID will fail CI.
 - If validation fails, report the exact requirement and stop.
 
diff --git a/.claude/commands/sdk-sample.md b/.claude/commands/sdk-sample.md
index a7b84a65..97740142 100644
--- a/.claude/commands/sdk-sample.md
+++ b/.claude/commands/sdk-sample.md
@@ -1,9 +1,13 @@
 ---
 name: sdk-sample
 description: Generate a Skyflow Java SDK sample file for a vault feature or service account operation. Compile-verified after creation.
+context: fork
 paths:
   - samples/**/*.java
   - samples/pom.xml
+  - src/main/java/com/skyflow/**/*.java
+exclude:
+  - src/main/java/com/skyflow/generated/**
 ---
 
 Create a Skyflow Java SDK sample file demonstrating: $ARGUMENTS
diff --git a/.claude/skills/requesting-code-review/SKILL.md b/.claude/skills/requesting-code-review/SKILL.md
index 5d89b793..7f5e9d55 100644
--- a/.claude/skills/requesting-code-review/SKILL.md
+++ b/.claude/skills/requesting-code-review/SKILL.md
@@ -4,6 +4,9 @@ description: Use when completing tasks, implementing major features, or before m
 paths:
   - src/main/java/**/*.java
   - src/test/java/**/*.java
+exclude:
+  - src/main/java/com/skyflow/generated/**
+context: fork
 ---
 
 # Requesting Code Review
diff --git a/CLAUDE.md b/CLAUDE.md
index 6e83fcb2..263165ca 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -55,8 +55,8 @@ docs/
 
 ## Naming Conventions
 
-- **Acronyms as words:** `skyflowId` (not `skyflowID`), `clientId` (not `clientID`), `tokenUri` (not `tokenURI`), `keyId` (not `keyID`)
-- **Builder setters:** `setVaultId()`, `setClusterId()`, `setSkyflowId()` — never `setVaultID()`
+- **Acronyms as words:** Examples: `skyflowId` (not `skyflowID`), `clientId` (not `clientID`), `tokenUri` (not `tokenURI`), `keyId` (not `keyID`)
+- **Builder setters:** Examples: `setVaultId()`, `setClusterId()`, `setSkyflowId()` — never `setVaultID()`
 - **Response maps:** always use `skyflowId` (camelCase) — the raw API returns `skyflow_id` (snake_case) which VaultController normalises before returning to callers
 - **Constants class:** use `com.skyflow.utils.Constants` for string literals; `ErrorMessage` enum for error message strings
 
@@ -78,6 +78,16 @@ These apply whenever writing or modifying code — not just during review.
 ### String literals
 - Use `Constants` for string literals and `ErrorMessage` enum for error messages — no magic strings
 
+### Tests
+- Use `Assert.assertEquals` / `Assert.assertNull` — not just `Assert.fail` guards
+- No mocking of the production class under test
+- Reflection-based tests on private methods are acceptable only when no public API exercises the method
+- All code written or modified by Claude must have 100% coverage — both instruction and branch
+
+### Code quality
+- No `@SuppressWarnings` without a comment explaining why
+- Use `LogUtil.printWarningLog` for deprecation warnings — not `System.err`
+
 ---
 
 ## Build and Test
@@ -128,13 +138,13 @@ See `docs/superpowers/specs/` for in-progress design specs and `docs/superpowers
 - `/code-smell` — standalone structural smell analysis only (long methods, dead code, misplaced logic)
 - `/code-security` — standalone security audit only (credentials, input validation, HTTP security)
 - `/sdk-sample <feature>` — generate a sample file for a feature
-- `/quality [ClassName]` — run quality pipeline (compile → checkstyle → build → test → 100% coverage check)
-- `/commit <description>` — stage check + Jira-aware commit (extracts ticket ID from branch name)
+- `/code-quality [ClassName]` — run quality pipeline (compile → checkstyle → build → test → 100% coverage check)
+- `/git-commit <description>` — stage check + Jira-aware commit (extracts ticket ID from branch name)
 
 ## Commit & PR Guidelines
 
 ### Commit messages
-**Never run `git commit` directly. Always use `/commit <description>`** — it extracts the Jira ticket ID from the branch name, confirms `/code-quality` has passed, and validates the format against the CI check in `.github/workflows/pr.yml`.
+**Never run `git commit` directly. Always use `/git-commit <description>`** — it extracts the Jira ticket ID from the branch name, confirms `/code-quality` has passed, and validates the format against the CI check in `.github/workflows/pr.yml`.
 
 ### Branch naming
 Branch name must include your GitHub username:

From 10b523e06c74c6cb4e99c385233a676d7070d678 Mon Sep 17 00:00:00 2001
From: skyflow-bharti <bharti.sagar@skyflow.com>
Date: Mon, 1 Jun 2026 16:52:17 +0530
Subject: [PATCH 21/30] SK-2832 Removed the duplicate section from skill

---
 .../skills/requesting-code-review/SKILL.md    | 36 ++-----------------
 1 file changed, 2 insertions(+), 34 deletions(-)

diff --git a/.claude/skills/requesting-code-review/SKILL.md b/.claude/skills/requesting-code-review/SKILL.md
index 7f5e9d55..61e0e05d 100644
--- a/.claude/skills/requesting-code-review/SKILL.md
+++ b/.claude/skills/requesting-code-review/SKILL.md
@@ -38,40 +38,8 @@ context: fork
 
 For security-sensitive changes, run both:
 ```bash
-/code-review src/main/java/com/skyflow/serviceaccount/
-/code-security src/main/java/com/skyflow/serviceaccount/
-```
-
-**2. Fork context — dispatch a subagent reviewer:**
-
-The commands above run in the current session and share your context. For an independent second opinion (no confirmation bias, preserved main context window), dispatch a fresh subagent:
-
-```
-Agent tool (general-purpose):
-  description: "SDK code review"
-  prompt: |
-    You are a senior engineer reviewing the Skyflow Java SDK.
-
-    Read CLAUDE.md for project conventions, then read and follow
-    .claude/commands/code-review.md for the full review process
-    including all rules, output format, and act-on-feedback guidance.
-
-    Git range to review:
-      Base: {BASE_SHA}
-      Head: {HEAD_SHA}
-
-    Run:
-      git diff --stat {BASE_SHA}..{HEAD_SHA}
-      git diff {BASE_SHA}..{HEAD_SHA}
-
-    Description of what was implemented:
-      {DESCRIPTION}
-```
-
-Get the SHAs:
-```bash
-BASE_SHA=$(git merge-base main HEAD)   # branch vs main
-HEAD_SHA=$(git rev-parse HEAD)
+/code-review src/main/java/com/skyflow/
+/code-security src/main/java/com/skyflow/
 ```
 
 All review rules, severity definitions, output format, and post-review steps are defined in `.claude/commands/code-review.md` — that file is the single source of truth.

From 72e0853ca55a2eb7d0dd9113ae266b60b06f4d75 Mon Sep 17 00:00:00 2001
From: skyflow-bharti <bharti.sagar@skyflow.com>
Date: Mon, 1 Jun 2026 16:55:10 +0530
Subject: [PATCH 22/30] SK-2832 Removed the duplicate claude setup file from
 samples

---
 samples/CLAUDE.md | 45 ---------------------------------------------
 1 file changed, 45 deletions(-)
 delete mode 100644 samples/CLAUDE.md

diff --git a/samples/CLAUDE.md b/samples/CLAUDE.md
deleted file mode 100644
index 9ec2ea9a..00000000
--- a/samples/CLAUDE.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-name: skyflow-java-samples
-description: Samples project context — file placement, structure, and rules for Skyflow Java SDK sample files.
-paths:
-  - "**/*.java"
-  - pom.xml
----
-
-# Skyflow Java SDK — Samples
-
-Standalone Maven project demonstrating SDK features. Compile with:
-```bash
-cd samples && mvn compile -q
-```
-
-## File Placement
-
-| Feature | Package | Directory |
-|---|---|---|
-| Vault ops (insert/get/update/delete/query/tokenize/detokenize) | `com.example.vault` | `samples/src/main/java/com/example/vault/` |
-| Service account auth | `com.example.serviceaccount` | `samples/src/main/java/com/example/serviceaccount/` |
-| Connection | `com.example.connection` | `samples/src/main/java/com/example/connection/` |
-| Detect | `com.example.detect` | `samples/src/main/java/com/example/detect/` |
-| Audit event operations | `com.example.audit` | `samples/src/main/java/com/example/audit/` |
-| BIN lookup | `com.example.bin` | `samples/src/main/java/com/example/bin/` |
-
-File name: `<FeatureName>Example.java`
-
-## Deprecated Samples
-
-Deprecated examples (v1-era or superseded APIs) live in:
-```
-samples/src/main/java/com/example/vault/deprecated/
-```
-Do not update deprecated samples — they are kept for reference only. New samples go in the parent package, not in `deprecated/`.
-
-## Rules
-
-- Vault IDs / cluster IDs: `"<YOUR_VAULT_ID>"`, `"<YOUR_CLUSTER_ID>"`
-- Credential values: `"<YOUR_API_KEY>"`, `"<YOUR_CREDENTIALS_STRING>"`
-- Credentials file path: `"credentials.json"` (relative, never absolute)
-- Always catch `SkyflowException` and print `e.getMessage()`
-- No separate `*Options` classes — use request builder methods directly
-- Keep under 80 lines
-- Imports from `com.skyflow.*` only — never from `com.skyflow.generated.*`

From b8fb38b69b55c89f16c622ea7e8627db8125f12d Mon Sep 17 00:00:00 2001
From: skyflow-bharti <bharti.sagar@skyflow.com>
Date: Mon, 1 Jun 2026 19:48:35 +0530
Subject: [PATCH 23/30] SK-2832 Removed the unused code patterns

---
 .claude/commands/code-patterns.md | 53 -------------------------------
 .claude/commands/code-review.md   | 23 +++++++++++++-
 2 files changed, 22 insertions(+), 54 deletions(-)
 delete mode 100644 .claude/commands/code-patterns.md

diff --git a/.claude/commands/code-patterns.md b/.claude/commands/code-patterns.md
deleted file mode 100644
index 731eccd5..00000000
--- a/.claude/commands/code-patterns.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-name: code-patterns
-description: SDK pattern review — request/response/options shape, error handling, naming, test coverage, code quality.
-paths:
-  - src/main/java/**/*.java
-  - src/test/java/**/*.java
-exclude:
-  - src/main/java/com/skyflow/generated/**
-context: fork
----
-
-You are a senior engineer reviewing the Skyflow Java SDK against its established patterns.
-
-## Scope
-
-Files are passed in by the caller (usually `/code-review`). Review only those files.
-
----
-
-## 1. Test coverage
-
-- Every public method must have at least one positive and one negative test
-- Follow the Tests coding rules (Assert conventions, no production class mocking, 100% coverage)
-
----
-
-## 2. Code quality
-
-- Follow the Code quality coding rules (@SuppressWarnings, LogUtil for deprecation)
-
----
-
-## Output format
-
-Group findings by file:
-
-```
-### path/to/File.java
-
-| Severity   | Line | Finding                                                    |
-|------------|------|------------------------------------------------------------|
-| Critical   | 42   | SkyflowException swallowed in catch block                  |
-| Bug        | 87   | skyflow_id not normalised to skyflowId                     |
-| Quality    | 103  | Magic string "records" — use Constants                     |
-```
-
-**Severities:**
-| Level | Meaning |
-|---|---|
-| **Critical** | Data loss, silent failure, security risk — must fix before merge |
-| **Bug** | Wrong behaviour, incorrect output — must fix before merge |
-| **Edge Case** | Unhandled input that will cause runtime failure — fix before merge |
-| **Quality** | Maintainability issue, naming violation, missing pattern — fix before merge |
diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md
index 1124549d..399e260e 100644
--- a/.claude/commands/code-review.md
+++ b/.claude/commands/code-review.md
@@ -29,7 +29,28 @@ Use `$ARGUMENTS` to determine scope:
 
 ## Step 1 — SDK Pattern Review
 
-Read the file `.claude/commands/code-patterns.md` and follow all of its instructions for the same files in scope. Produce its full output (per-file findings table + severity key).
+Review all files in scope against the rules defined in `CLAUDE.md` (loaded automatically from the project root). Check every rule category: naming conventions, error handling, request/response patterns, string literals, tests, and code quality.
+
+Group findings by file and produce a table:
+
+```
+### path/to/File.java
+
+| Severity | Line | Finding |
+|----------|------|---------|
+| Critical | 42   | SkyflowException swallowed in catch block |
+| Bug      | 87   | skyflow_id not normalised to skyflowId |
+| Quality  | 103  | Magic string "records" — use Constants |
+```
+
+**Severities:**
+
+| Level | Meaning |
+|---|---|
+| **Critical** | Data loss, silent failure, security risk — must fix before merge |
+| **Bug** | Wrong behaviour, incorrect output — must fix before merge |
+| **Edge Case** | Unhandled input that will cause runtime failure — fix before merge |
+| **Quality** | Maintainability issue, naming violation, missing pattern — fix before merge |
 
 ---
 

From 976079b2f0c6daf316373636e72ac58fe12dcb53 Mon Sep 17 00:00:00 2001
From: Aadarsh <aadarsh.thakur@skyflow.com>
Date: Tue, 2 Jun 2026 18:35:31 +0530
Subject: [PATCH 24/30] SK-2832: Updated pr review workflow

---
 .claude/commands/code-review.md        |  12 +-
 .claude/commands/code-security.md      |   6 +-
 .github/workflows/claude-pr-review.yml | 151 ++++++++++++++-----------
 3 files changed, 96 insertions(+), 73 deletions(-)

diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md
index 399e260e..9662ad0d 100644
--- a/.claude/commands/code-review.md
+++ b/.claude/commands/code-review.md
@@ -13,16 +13,22 @@ You are a senior engineer performing a thorough code review on the Skyflow Java
 
 ## Pre-requisite
 
-Before starting the review, confirm `/code-quality` has been run and passed (compile, tests, 100% coverage). If it has not been run, run it now before proceeding with the review.
+If `GITHUB_ACTIONS` environment variable is set, skip this step (CI runs compile/test in a separate job).
+
+Otherwise, confirm `/code-quality` has been run and passed (compile, tests, 100% coverage). If it has not been run, run it now before proceeding with the review.
 
 ## Scope
 
 Use `$ARGUMENTS` to determine scope:
 - `full review` — scan all files under `src/main/java/com/skyflow/` recursively (exclude `generated/`)
 - A file or directory path — review only that path
-- Empty / default — review files changed on current branch vs `main`:
+- Empty / default — review files changed on current PR/branch vs base:
   ```bash
-  git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+  # CI: GITHUB_BASE_REF is set (e.g. "main") — use origin/ prefix
+  # Local: unset — use main directly
+  BASE="${GITHUB_BASE_REF:+origin/$GITHUB_BASE_REF}"
+  BASE="${BASE:-main}"
+  git diff "$BASE"...HEAD --name-only | grep '\.java$' | grep -v 'generated'
   ```
 
 ---
diff --git a/.claude/commands/code-security.md b/.claude/commands/code-security.md
index f03660ff..d2fd2983 100644
--- a/.claude/commands/code-security.md
+++ b/.claude/commands/code-security.md
@@ -15,7 +15,11 @@ You are a security engineer auditing the Skyflow Java SDK for vulnerabilities.
 
 Use `$ARGUMENTS` to determine target files. If none provided, run:
 ```bash
-git diff main...HEAD --name-only | grep '\.java$' | grep -v 'generated'
+# CI: GITHUB_BASE_REF is set (e.g. "main") — use origin/ prefix
+# Local: unset — use main directly
+BASE="${GITHUB_BASE_REF:+origin/$GITHUB_BASE_REF}"
+BASE="${BASE:-main}"
+git diff "$BASE"...HEAD --name-only | grep '\.java$' | grep -v 'generated'
 ```
 
 ## Security Checks
diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml
index 821b2d50..f1bf772f 100644
--- a/.github/workflows/claude-pr-review.yml
+++ b/.github/workflows/claude-pr-review.yml
@@ -5,16 +5,21 @@ on:
     branches: [main]
     paths:
       - 'src/**/*.java'
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'PR number to re-run review on'
+        required: false
 
 permissions:
   pull-requests: write
   contents: read
 
 jobs:
-  sdk-patterns-review:
-    name: SDK Patterns & Naming Review
+  sdk-review:
+    name: SDK Review (patterns + smell + security)
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v4
         with:
@@ -23,66 +28,72 @@ jobs:
       - name: Install Claude CLI
         run: npm install -g @anthropic-ai/claude-code
 
-      - name: Get changed Java files
-        id: changed-files
+      - name: Check for non-generated Java changes
+        id: check
         run: |
-          FILES=$(git diff --name-only origin/${{ github.base_ref }}...${{ github.sha }} \
-            | grep '\.java$' \
-            | grep -v 'generated' \
-            | tr '\n' ' ')
-          echo "files=$FILES" >> $GITHUB_OUTPUT
-
-      - name: Run SDK patterns review
-        if: steps.changed-files.outputs.files != ''
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
+            | grep '\.java$' | grep -v 'generated')
+          if [ -z "$CHANGED" ]; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            LINES=$(git diff origin/${{ github.base_ref }}...HEAD -- '*.java' \
+              | grep -c '^[+-][^+-]' 2>/dev/null || echo 1)
+            echo "changed_lines=$LINES" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run code review
+        if: steps.check.outputs.has_changes == 'true'
         id: review
         continue-on-error: true
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
+          GITHUB_BASE_REF: ${{ github.base_ref }}
+          GITHUB_ACTIONS: "true"
         run: |
-          FILES="${{ steps.changed-files.outputs.files }}"
-          REVIEW=$(claude --print --model claude-sonnet-4-5 -p "
-          You are a senior engineer reviewing the Skyflow Java SDK.
-
-          Review the following changed Java files for SDK pattern violations:
-          1. Request/Response/Options patterns — builders are data holders, validation in Validations.java only
-          2. Error handling — all public methods throw SkyflowException, no swallowed exceptions, no bare println/printStackTrace
-          3. Naming — acronyms as words (skyflowId not skyflowID, tokenUri not tokenURI); UPPER_SNAKE constants; PascalCase classes
-          4. Response normalisation — skyflowId not skyflow_id in response maps; getErrors() present on every response class
-          5. Code quality — no magic strings (use Constants), no @SuppressWarnings without comment, deprecation via LogUtil.printWarningLog
+          RAW=$(claude --output-format json --model claude-sonnet-4-6 -p "/code-review" 2>/dev/null)
 
-          Skip src/main/java/com/skyflow/generated/ entirely.
+          RESULT=$(echo "$RAW" | jq -r '.result // "_Review failed to produce output._"')
+          INPUT_TOK=$(echo "$RAW" | jq -r '.usage.input_tokens // 0')
+          OUTPUT_TOK=$(echo "$RAW" | jq -r '.usage.output_tokens // 0')
+          CACHED_TOK=$(echo "$RAW" | jq -r '.usage.cache_read_input_tokens // 0')
+          COST=$(echo "$RAW" | jq -r '.total_cost_usd // 0')
+          LINES="${{ steps.check.outputs.changed_lines }}"
 
-          Files to review: $FILES
-
-          For each file with findings, produce a markdown table:
-          | Severity | Line | Finding |
-          Severities: Critical (data loss/security), Bug (wrong behaviour), Quality (naming/patterns).
-          Skip Info-level observations. If no findings for a file, omit it.
-          If no findings at all, write: 'No issues found.'
-
-          End with one of: APPROVE / APPROVE WITH FIXES / REQUEST CHANGES
-          ")
           echo "result<<EOF" >> $GITHUB_OUTPUT
-          echo "$REVIEW" >> $GITHUB_OUTPUT
+          echo "$RESULT" >> $GITHUB_OUTPUT
           echo "EOF" >> $GITHUB_OUTPUT
 
+          {
+            echo "## Token Usage — SDK Review"
+            echo "| Metric | Value |"
+            echo "|--------|-------|"
+            echo "| Input tokens | $INPUT_TOK |"
+            echo "| Output tokens | $OUTPUT_TOK |"
+            echo "| Cache hits | $CACHED_TOK |"
+            echo "| Total cost | \$$COST |"
+            echo "| Changed lines | $LINES |"
+          } >> $GITHUB_STEP_SUMMARY
+
       - name: Post review comment
-        if: steps.changed-files.outputs.files != ''
+        if: steps.check.outputs.has_changes == 'true'
         uses: actions/github-script@v7
+        env:
+          REVIEW_BODY: ${{ steps.review.outputs.result }}
         with:
           script: |
-            const review = `${{ steps.review.outputs.result }}`;
-            const files = `${{ steps.changed-files.outputs.files }}`;
+            const review = process.env.REVIEW_BODY || '_Review output unavailable._';
             await github.rest.issues.createComment({
               ...context.repo,
               issue_number: context.payload.pull_request.number,
-              body: `## Claude SDK Patterns Review\n\n${review}\n\n---\n_Files reviewed: \`${files}\`_`
+              body: `## Claude SDK Review\n\n${review}`
             });
 
   security-review:
     name: Security Review (serviceaccount changes)
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
         with:
@@ -104,10 +115,8 @@ jobs:
         if: steps.filter.outputs.serviceaccount == 'true'
         id: sa-files
         run: |
-          FILES=$(git diff --name-only origin/${{ github.base_ref }}...${{ github.sha }} \
-            | grep 'serviceaccount' \
-            | grep '\.java$' \
-            | tr '\n' ' ')
+          FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
+            | grep 'serviceaccount' | grep '\.java$' | tr '\n' ' ')
           echo "files=$FILES" >> $GITHUB_OUTPUT
 
       - name: Run security audit
@@ -116,40 +125,44 @@ jobs:
         continue-on-error: true
         env:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
+          GITHUB_BASE_REF: ${{ github.base_ref }}
+          GITHUB_ACTIONS: "true"
+          SA_FILES: ${{ steps.sa-files.outputs.files }}
         run: |
-          FILES="${{ steps.sa-files.outputs.files }}"
-          AUDIT=$(claude --print --model claude-sonnet-4-5 -p "
-          You are a security engineer auditing the Skyflow Java SDK serviceaccount module.
-
-          Audit the following files for:
-          1. Credential and token exposure — bearer tokens, API keys, private keys must never appear in logs, error messages, or toString() output
-          2. Path traversal — file paths passed to new File(path) must not allow ../
-          3. JSON parsing — JsonParser calls must be wrapped in try/catch for JsonSyntaxException
-          4. HTTP security — all API calls must be HTTPS; Authorization headers must not be logged at any level
-          5. Token lifecycle — bearer token caching must check expiry before reuse; token refresh must be thread-safe
-
-          Files: $FILES
-
-          For each finding:
-          **Severity:** Critical / High / Medium / Low
-          **File:Line:** path:N
-          **Risk:** one sentence
-          **Fix:** one concrete sentence
-
-          If no findings, write: 'No security issues found.'
-          End with overall risk rating: LOW / MEDIUM / HIGH / CRITICAL
-          ")
+          RAW=$(claude --output-format json --model claude-sonnet-4-6 \
+            -p "/code-security $SA_FILES" 2>/dev/null)
+
+          RESULT=$(echo "$RAW" | jq -r '.result // "_Audit failed to produce output._"')
+          INPUT_TOK=$(echo "$RAW" | jq -r '.usage.input_tokens // 0')
+          OUTPUT_TOK=$(echo "$RAW" | jq -r '.usage.output_tokens // 0')
+          CACHED_TOK=$(echo "$RAW" | jq -r '.usage.cache_read_input_tokens // 0')
+          COST=$(echo "$RAW" | jq -r '.total_cost_usd // 0')
+
           echo "result<<EOF" >> $GITHUB_OUTPUT
-          echo "$AUDIT" >> $GITHUB_OUTPUT
+          echo "$RESULT" >> $GITHUB_OUTPUT
           echo "EOF" >> $GITHUB_OUTPUT
 
+          {
+            echo "## Token Usage — Security Audit"
+            echo "| Metric | Value |"
+            echo "|--------|-------|"
+            echo "| Input tokens | $INPUT_TOK |"
+            echo "| Output tokens | $OUTPUT_TOK |"
+            echo "| Cache hits | $CACHED_TOK |"
+            echo "| Total cost | \$$COST |"
+          } >> $GITHUB_STEP_SUMMARY
+
       - name: Post security comment
         if: steps.filter.outputs.serviceaccount == 'true' && steps.sa-files.outputs.files != ''
         uses: actions/github-script@v7
+        env:
+          AUDIT_BODY: ${{ steps.security.outputs.result }}
+          SA_FILES: ${{ steps.sa-files.outputs.files }}
         with:
           script: |
-            const audit = `${{ steps.security.outputs.result }}`;
-            const files = `${{ steps.sa-files.outputs.files }}`;
+            const audit = process.env.AUDIT_BODY || '_Audit output unavailable._';
+            const files = process.env.SA_FILES;
             await github.rest.issues.createComment({
               ...context.repo,
               issue_number: context.payload.pull_request.number,

From 10e1c092e60b6a19096aeb8810cc1302bef5c17e Mon Sep 17 00:00:00 2001
From: Aadarsh <aadarsh.thakur@skyflow.com>
Date: Tue, 2 Jun 2026 18:41:36 +0530
Subject: [PATCH 25/30] SK-2832: Fix claude issue

---
 .github/workflows/claude-pr-review.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml
index f1bf772f..b62584da 100644
--- a/.github/workflows/claude-pr-review.yml
+++ b/.github/workflows/claude-pr-review.yml
@@ -52,7 +52,7 @@ jobs:
           GITHUB_BASE_REF: ${{ github.base_ref }}
           GITHUB_ACTIONS: "true"
         run: |
-          RAW=$(claude --output-format json --model claude-sonnet-4-6 -p "/code-review" 2>/dev/null)
+          RAW=$(claude --output-format json --model claude-sonnet-4-6 -p "/code-review")
 
           RESULT=$(echo "$RAW" | jq -r '.result // "_Review failed to produce output._"')
           INPUT_TOK=$(echo "$RAW" | jq -r '.usage.input_tokens // 0')

From 7953daa21797720f8587253b7ed4ab49e39c3f1d Mon Sep 17 00:00:00 2001
From: Aadarsh <aadarsh.thakur@skyflow.com>
Date: Tue, 2 Jun 2026 18:46:28 +0530
Subject: [PATCH 26/30] SK-2832: fix

---
 .github/workflows/claude-pr-review.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml
index b62584da..987be2d6 100644
--- a/.github/workflows/claude-pr-review.yml
+++ b/.github/workflows/claude-pr-review.yml
@@ -52,7 +52,7 @@ jobs:
           GITHUB_BASE_REF: ${{ github.base_ref }}
           GITHUB_ACTIONS: "true"
         run: |
-          RAW=$(claude --output-format json --model claude-sonnet-4-6 -p "/code-review")
+          RAW=$(claude --dangerously-skip-permissions --output-format json --model claude-sonnet-4-6 -p "/code-review")
 
           RESULT=$(echo "$RAW" | jq -r '.result // "_Review failed to produce output._"')
           INPUT_TOK=$(echo "$RAW" | jq -r '.usage.input_tokens // 0')
@@ -130,8 +130,8 @@ jobs:
           GITHUB_ACTIONS: "true"
           SA_FILES: ${{ steps.sa-files.outputs.files }}
         run: |
-          RAW=$(claude --output-format json --model claude-sonnet-4-6 \
-            -p "/code-security $SA_FILES" 2>/dev/null)
+          RAW=$(claude --dangerously-skip-permissions --output-format json --model claude-sonnet-4-6 \
+            -p "/code-security $SA_FILES")
 
           RESULT=$(echo "$RAW" | jq -r '.result // "_Audit failed to produce output._"')
           INPUT_TOK=$(echo "$RAW" | jq -r '.usage.input_tokens // 0')

From ec3e4124a335c243123dc4ae8172412e541a137d Mon Sep 17 00:00:00 2001
From: Aadarsh <aadarsh.thakur@skyflow.com>
Date: Tue, 2 Jun 2026 18:50:15 +0530
Subject: [PATCH 27/30] SK-2832: check api key valid or not

---
 .github/workflows/claude-pr-review.yml | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml
index 987be2d6..141b06ab 100644
--- a/.github/workflows/claude-pr-review.yml
+++ b/.github/workflows/claude-pr-review.yml
@@ -42,6 +42,14 @@ jobs:
             echo "changed_lines=$LINES" >> $GITHUB_OUTPUT
           fi
 
+      - name: Verify Claude CLI
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          echo "Claude version: $(claude --version)"
+          TEST=$(claude --dangerously-skip-permissions --output-format json -p "Reply with only the word: WORKING" 2>&1)
+          echo "Auth test: $TEST"
+
       - name: Run code review
         if: steps.check.outputs.has_changes == 'true'
         id: review
@@ -52,7 +60,7 @@ jobs:
           GITHUB_BASE_REF: ${{ github.base_ref }}
           GITHUB_ACTIONS: "true"
         run: |
-          RAW=$(claude --dangerously-skip-permissions --output-format json --model claude-sonnet-4-6 -p "/code-review")
+          RAW=$(claude --dangerously-skip-permissions --output-format json --model claude-sonnet-4-6 -p "/code-review" 2>&1)
 
           RESULT=$(echo "$RAW" | jq -r '.result // "_Review failed to produce output._"')
           INPUT_TOK=$(echo "$RAW" | jq -r '.usage.input_tokens // 0')

From 93f8bd5dad9241c582a6dbd42edaa8c5c8f16790 Mon Sep 17 00:00:00 2001
From: Aadarsh <aadarsh.thakur@skyflow.com>
Date: Tue, 2 Jun 2026 18:53:25 +0530
Subject: [PATCH 28/30] SK-2832: Debug

---
 .github/workflows/claude-pr-review.yml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml
index 141b06ab..33a584aa 100644
--- a/.github/workflows/claude-pr-review.yml
+++ b/.github/workflows/claude-pr-review.yml
@@ -47,8 +47,12 @@ jobs:
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
         run: |
           echo "Claude version: $(claude --version)"
+          set +e
           TEST=$(claude --dangerously-skip-permissions --output-format json -p "Reply with only the word: WORKING" 2>&1)
-          echo "Auth test: $TEST"
+          EXIT=$?
+          set -e
+          echo "Exit code: $EXIT"
+          echo "Output: $TEST"
 
       - name: Run code review
         if: steps.check.outputs.has_changes == 'true'

From e409f0a6162a0b6e2082155f6803721c45774f90 Mon Sep 17 00:00:00 2001
From: Aadarsh <aadarsh.thakur@skyflow.com>
Date: Tue, 2 Jun 2026 19:06:39 +0530
Subject: [PATCH 29/30] SK-2832: Updated the token count

---
 .github/workflows/claude-pr-review.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml
index 33a584aa..d6a4cf93 100644
--- a/.github/workflows/claude-pr-review.yml
+++ b/.github/workflows/claude-pr-review.yml
@@ -67,9 +67,9 @@ jobs:
           RAW=$(claude --dangerously-skip-permissions --output-format json --model claude-sonnet-4-6 -p "/code-review" 2>&1)
 
           RESULT=$(echo "$RAW" | jq -r '.result // "_Review failed to produce output._"')
-          INPUT_TOK=$(echo "$RAW" | jq -r '.usage.input_tokens // 0')
-          OUTPUT_TOK=$(echo "$RAW" | jq -r '.usage.output_tokens // 0')
-          CACHED_TOK=$(echo "$RAW" | jq -r '.usage.cache_read_input_tokens // 0')
+          INPUT_TOK=$(echo "$RAW" | jq '[.modelUsage[].inputTokens // 0] | add // 0')
+          OUTPUT_TOK=$(echo "$RAW" | jq '[.modelUsage[].outputTokens // 0] | add // 0')
+          CACHED_TOK=$(echo "$RAW" | jq '[.modelUsage[].cacheReadInputTokens // 0] | add // 0')
           COST=$(echo "$RAW" | jq -r '.total_cost_usd // 0')
           LINES="${{ steps.check.outputs.changed_lines }}"
 
@@ -146,9 +146,9 @@ jobs:
             -p "/code-security $SA_FILES")
 
           RESULT=$(echo "$RAW" | jq -r '.result // "_Audit failed to produce output._"')
-          INPUT_TOK=$(echo "$RAW" | jq -r '.usage.input_tokens // 0')
-          OUTPUT_TOK=$(echo "$RAW" | jq -r '.usage.output_tokens // 0')
-          CACHED_TOK=$(echo "$RAW" | jq -r '.usage.cache_read_input_tokens // 0')
+          INPUT_TOK=$(echo "$RAW" | jq '[.modelUsage[].inputTokens // 0] | add // 0')
+          OUTPUT_TOK=$(echo "$RAW" | jq '[.modelUsage[].outputTokens // 0] | add // 0')
+          CACHED_TOK=$(echo "$RAW" | jq '[.modelUsage[].cacheReadInputTokens // 0] | add // 0')
           COST=$(echo "$RAW" | jq -r '.total_cost_usd // 0')
 
           echo "result<<EOF" >> $GITHUB_OUTPUT

From 376bdef3e5e8a5a285c8440f9690a57b35e71da1 Mon Sep 17 00:00:00 2001
From: Aadarsh <aadarsh.thakur@skyflow.com>
Date: Tue, 2 Jun 2026 19:18:16 +0530
Subject: [PATCH 30/30] SK-2832: Updated condition for code-review

---
 .claude/commands/code-review.md        | 7 +++++--
 .github/workflows/claude-pr-review.yml | 2 +-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md
index 9662ad0d..c3a203b6 100644
--- a/.claude/commands/code-review.md
+++ b/.claude/commands/code-review.md
@@ -24,12 +24,15 @@ Use `$ARGUMENTS` to determine scope:
 - A file or directory path — review only that path
 - Empty / default — review files changed on current PR/branch vs base:
   ```bash
-  # CI: GITHUB_BASE_REF is set (e.g. "main") — use origin/ prefix
-  # Local: unset — use main directly
   BASE="${GITHUB_BASE_REF:+origin/$GITHUB_BASE_REF}"
   BASE="${BASE:-main}"
   git diff "$BASE"...HEAD --name-only | grep '\.java$' | grep -v 'generated'
   ```
+  **If `GITHUB_ACTIONS` is set:** work from the diff output directly (changed lines only) instead of reading full files:
+  ```bash
+  git diff "$BASE"...HEAD -- '*.java' | grep -v 'src/main/java/com/skyflow/generated/'
+  ```
+  Review only added lines (`+` prefix) from the diff. Do not comment on unchanged context lines or pre-existing code.
 
 ---
 
diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml
index d6a4cf93..c3d71832 100644
--- a/.github/workflows/claude-pr-review.yml
+++ b/.github/workflows/claude-pr-review.yml
@@ -17,7 +17,7 @@ permissions:
 
 jobs:
   sdk-review:
-    name: SDK Review (patterns + smell + security)
+    name: SDK PR Review (changed lines only)
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps: