diff --git a/.claude/commands/ppl-bugfix.md b/.claude/commands/ppl-bugfix.md
new file mode 100644
index 0000000000..e12cefce9c
--- /dev/null
+++ b/.claude/commands/ppl-bugfix.md
@@ -0,0 +1,125 @@
+---
+allowed-tools: Agent, Read, Bash(gh:*), Bash(git:*)
+description: Run the PPL bugfix harness for a GitHub issue or follow up on an existing PR
+---
+
+Fix a PPL bug or follow up on an existing PR using the harness in `.claude/harness/ppl-bugfix-harness.md`.
+
+## Input
+
+Accepts one or more issue/PR references. Multiple references are processed in parallel (each gets its own subagent + worktree).
+
+- `/ppl-bugfix #1234` — single issue
+- `/ppl-bugfix PR#5678` — single PR
+- `/ppl-bugfix #1234 #5678 PR#9012` — multiple in parallel
+- `/ppl-bugfix https://github.com/opensearch-project/sql/issues/1234` — URL
+
+Optional mode flag (append to any of the above):
+- `--safe` — `acceptEdits` mode. Auto-approve file edits only, Bash commands require manual approval. (Most conservative)
+- `--yolo` — `bypassPermissions` mode. Fully trusted, no prompts. Subagent runs in an isolated worktree so this is safe. (Default)
+
+> **Note**: `bypassPermissions` skips the interactive prompt but still respects the allow-list in `~/.claude/settings.json`. Ensure git/gh write commands are in the global allow-list.
+
+Examples:
+- `/ppl-bugfix #1234` — single issue, defaults to yolo
+- `/ppl-bugfix #1234 #5678 --yolo` — two issues in parallel
+- `/ppl-bugfix PR#5293 PR#5300` — two PRs in parallel
+- `/ppl-bugfix #1234 PR#5678 --safe` — mix of issue and PR
+
+If no argument given, ask for an issue or PR number.
+
+## Step 0: Resolve Permission Mode
+
+Parse the mode flag from the input arguments:
+
+| Flag | Mode |
+|------|------|
+| `--safe` | `acceptEdits` |
+| `--yolo` | `bypassPermissions` |
+| _(no flag)_ | `bypassPermissions` (default) |
+
+Use the resolved mode as the `mode` parameter when dispatching the subagent in Step 2A/2B.
+
+## Step 1: Resolve Each Reference
+
+For each issue/PR reference in the input, resolve its state. Run these lookups in parallel when there are multiple references.
+
+```bash
+# Issue → PR (check multiple closing keyword variants)
+gh pr list --search "Resolves #<issue_number>" --json number,url,state --limit 5
+gh pr list --search "Fixes #<issue_number>" --json number,url,state --limit 5
+gh pr list --search "Closes #<issue_number>" --json number,url,state --limit 5
+
+# PR → Issue
+gh pr view <pr_number> --json body | jq -r '.body' | grep -oiE '(resolves|fixes|closes) #[0-9]+' | grep -oE '[0-9]+'
+```
+
+| State | Action |
+|-------|--------|
+| Issue exists, no PR | **Initial Fix** (Step 2A) |
+| Issue exists, open PR found | **Follow-up** (Step 2B) |
+| PR provided directly | **Follow-up** (Step 2B) |
+
+## Step 2: Dispatch Subagents
+
+Dispatch one subagent per reference. When there are multiple references, dispatch all subagents in a single message (parallel execution).
+
+### 2A: Initial Fix
+
+```
+Agent(
+  mode: "<resolved_mode>",
+  isolation: "worktree",
+  name: "bugfix-<issue_number>",
+  description: "PPL bugfix #<issue_number>",
+  prompt: "Read .claude/harness/ppl-bugfix-harness.md and follow it to fix GitHub issue #<issue_number>.
+           Follow Phase 0 through Phase 3 in order.
+           Phase 0.3 defines TDD execution flow. Do NOT skip any phase.
+           CRITICAL: If Phase 0.1 determines the bug is already fixed on main, HARD STOP.
+           Do NOT write tests, do NOT create a PR — just comment/close the issue and report back.
+           If the bug IS reproducible, post the Decision Log (Phase 3.4) before completing."
+)
+```
+
+### 2B: Follow-up
+
+```
+Agent(
+  mode: "<resolved_mode>",
+  isolation: "worktree",
+  name: "bugfix-<issue_number>",
+  description: "PPL bugfix #<issue_number> followup",
+  prompt: "Read .claude/harness/ppl-bugfix-followup.md and follow it.
+           PR: <pr_number> (<pr_url>), Issue: #<issue_number>"
+)
+```
+
+## Step 3: Report Back
+
+After all subagents complete, report a summary for each:
+- Classification, fix summary, PR URL, worktree path and branch, items needing human attention (2A)
+- What was addressed, current PR state, whether another round is needed (2B)
+
+## Subagent Lifecycle
+
+Subagents are task-scoped. They complete and release context — they cannot poll for events.
+
+```
+Agent A (Phase 0-3) → creates PR → completes
+  (CI runs, reviewers comment, conflicts arise)
+Agent B (Phase 3.5) → handles feedback → completes
+  (repeat as needed)
+Agent N (Phase 3.5) → gh pr ready → done
+```
+
+Context is preserved across agents via:
+- **Decision Log** (PR comment) — single source of truth for rejected alternatives, pitfalls, design rationale
+- **GitHub state** (PR diff, review comments, CI logs) — reconstructed by each follow-up agent
+
+## Rules
+
+- Subagent reads `.claude/harness/ppl-bugfix-harness.md` and fetches issue/PR details itself — do NOT inline content into the prompt
+- If bug is not reproducible (Phase 0.1), stop and report — do not proceed
+- Issue ↔ PR auto-resolution means the user never needs to track PR numbers manually
+- **Do NOT use `mode: "auto"` for subagents** — `auto` mode does not work for subagents; Bash commands still require manual approval. Only `bypassPermissions` reliably skips permission checks.
+- **Always dispatch subagent** — even for trivial follow-ups (remove co-author, force push). Do NOT run commands directly in the main session; subagents with `bypassPermissions` skip permission prompts, the main session does not.
diff --git a/.claude/harness/ppl-bugfix-followup.md b/.claude/harness/ppl-bugfix-followup.md
new file mode 100644
index 0000000000..b9eb18d629
--- /dev/null
+++ b/.claude/harness/ppl-bugfix-followup.md
@@ -0,0 +1,103 @@
+# PPL Bugfix Follow-up
+
+## Rules
+
+- Do NOT add `Co-Authored-By` lines in commits — only DCO `Signed-off-by`
+
+---
+
+## Reconstruct Context
+
+The follow-up agent runs in a fresh worktree. First checkout the PR branch, then load state:
+
+```bash
+# Checkout the PR branch in this worktree
+gh pr checkout <pr_number>
+
+# Resolve fork remote — the worktree may only have origin (upstream)
+git remote -v
+# If no fork remote exists, add it:
+git remote add fork https://github.com/<fork_owner>/sql.git
+
+# Load PR state — reviews, CI, mergeability
+gh pr view <pr_number> --json title,body,state,reviews,statusCheckRollup,mergeable
+gh pr checks <pr_number>
+
+# Load ALL comments — includes bot comments (Code-Diff-Analyzer, PR Reviewer Guide, Code Suggestions) and human comments
+gh pr view <pr_number> --json comments --jq '.comments[] | {author: .author.login, body: .body}'
+```
+
+Categorize ALL signals — not just CI and human reviews:
+
+| Signal | Type |
+|--------|------|
+| `statusCheckRollup` has failures | CI failure |
+| `reviews` has CHANGES_REQUESTED | Review feedback |
+| `mergeable` is CONFLICTING | Merge conflict |
+| Bot comments with actionable suggestions | Review feedback (treat like human review) |
+| All pass + approved | Ready — run `gh pr ready` |
+
+## Handle Review Feedback
+
+For each comment (human OR bot), **cross-check against the Decision Log first**:
+
+| Type | Action |
+|------|--------|
+| Code change | If already rejected in Decision Log, reply with reasoning. Otherwise make the change, new commit, push |
+| Question | Reply with explanation — Decision Log often has the answer |
+| Nit | Fix if trivial |
+| Disagreement | Reply with Decision Log reasoning; if reviewer insists, escalate to user |
+
+```bash
+git add <files> && git commit -s -m "Address review feedback: <description>"
+git push -u fork <branch_name>
+```
+
+## Clean Up Commit History
+
+When you need to amend a commit (e.g. remove Co-Authored-By, reword message) and the branch has a merge commit on top, don't try `git reset --soft origin/main` — it will include unrelated changes if main has moved. Instead cherry-pick the fix onto latest main:
+
+```bash
+git checkout -B clean-branch origin/main
+git cherry-pick <fix_commit_sha>
+git commit --amend -s -m "<updated message>"
+git push fork clean-branch:<pr_branch> --force-with-lease
+```
+
+## Handle CI Failures
+
+```bash
+gh pr checks <pr_number>                  # Identify failures
+gh run view <run_id> --log-failed         # Read logs
+# Test failure → fix locally, push new commit
+# Spotless → ./gradlew spotlessApply, push
+# Flaky → gh run rerun <run_id> --failed
+```
+
+## Handle Merge Conflicts
+
+```bash
+git fetch origin && git merge origin/main  # Resolve conflicts
+./gradlew spotlessApply && ./gradlew test && ./gradlew :integ-test:integTest  # Re-verify
+git commit -s -m "Resolve merge conflicts with main"
+git push -u fork <branch_name>
+```
+
+## Mark Ready
+
+```bash
+gh pr ready <pr_number>
+```
+
+## Retrospective
+
+After handling follow-up, reflect on the feedback received and check if it reveals gaps in the harness or command:
+
+For each comment addressed (bot or human):
+- **Does the feedback point to a pattern the harness should have prevented?** → Add guidance to the relevant Phase in `ppl-bugfix-harness.md`
+- **Was this a repeated mistake across PRs?** → Add to Quick Reference or Case Index
+- **Did the harness template produce the problematic code?** → Fix the template directly
+- **Was a permission or tool missing?** → Add to `.claude/settings.json`
+- **Did the follow-up workflow itself miss this signal?** → Update this file
+
+If any improvement is needed, make the edit and include it in the same commit.
diff --git a/.claude/harness/ppl-bugfix-harness.md b/.claude/harness/ppl-bugfix-harness.md
new file mode 100644
index 0000000000..5845385b55
--- /dev/null
+++ b/.claude/harness/ppl-bugfix-harness.md
@@ -0,0 +1,151 @@
+# PPL Bugfix Harness
+
+## Phase 0: Triage
+
+### 0.1 Load & Reproduce
+
+```bash
+gh issue view <issue_number> --repo opensearch-project/sql
+```
+
+Write a failing test or run an existing one to reproduce the bug on `main`.
+
+If the bug **does not reproduce** (correct results, not infra failure):
+
+| Finding | Action |
+|---------|--------|
+| Already fixed | `gh issue comment` + `gh issue close` |
+| Older version only | `gh issue comment` + `gh issue close` |
+| Intermittent | Label `flaky` or `needs-info`, do NOT close |
+| Can't reproduce | Comment asking for repro steps, label `needs-info` |
+
+**HARD STOP** — do not proceed. Report back.
+
+### 0.2 Classify
+
+Identify the bug layer (Grammar, AST/Functions, Type System, Optimizer, Execution, DI/Resource) and record it. Consult `.claude/harness/ppl-bugfix-reference.md` for fix-path-specific guidance if needed.
+
+### 0.3 Guardrails
+
+Stop and report back if:
+- Root cause unclear after reading 15+ source files
+- Fix breaks 5+ unrelated tests
+- Same build error 3 times in a row
+
+### 0.4 Execution Flow
+
+```
+Triage → Write FAILING test → Fix → Remaining tests → Verify → Commit → PR → Decision Log → Completion Gate
+```
+
+---
+
+## Phase 1: Fix
+
+Find and fix the root cause. Consult `.claude/harness/ppl-bugfix-reference.md` for path-specific patterns and examples.
+
+---
+
+## Phase 2: Tests
+
+Consult `.claude/harness/ppl-bugfix-reference.md` for test templates.
+
+Required deliverables:
+- Failing test reproducing the bug (written BEFORE the fix)
+- Unit tests covering happy path and edge cases
+- Integration test (`*IT.java` extending `CalcitePPLIT`)
+- YAML REST test at `integ-test/src/yamlRestTest/resources/rest-api-spec/test/issues/<ISSUE>.yml`
+
+---
+
+## Phase 3: Verify & Submit
+
+### 3.1 Verify
+
+```bash
+./gradlew spotlessApply
+./gradlew :<module>:test --tests "<TestClass>"
+./gradlew test
+./gradlew :integ-test:integTest -Dtests.class="*<YourIT>"
+```
+
+Run `./gradlew :integ-test:yamlRestTest` if YAML tests were added. Run `./gradlew generateGrammarSource && ./gradlew :ppl:test` if grammar was modified.
+
+### 3.2 Commit & PR
+
+```bash
+git add <changed_files>
+git commit -s -m "[BugFix] Fix <description> (#<issue_number>)"
+git fetch origin && git merge origin/main
+./gradlew test && ./gradlew :integ-test:integTest -Dtests.class="*<YourIT>"
+
+# Resolve fork remote (check git remote -v; add if missing)
+git remote add fork https://github.com/<fork_owner>/sql.git
+git push -u fork <branch_name>
+```
+
+Do NOT add Co-Authored-By lines. Use the git user name to infer the fork owner, or fall back to "qianheng-aws".
+
+```bash
+gh pr create --draft --repo opensearch-project/sql \
+  --title "[BugFix] Fix <description> (#<issue_number>)" \
+  --body "$(cat <<'EOF'
+### Description
+<Brief description of fix and root cause>
+
+### Related Issues
+Resolves #<issue_number>
+
+### Check List
+- [x] New functionality includes testing
+- [x] Commits signed per DCO (`-s`)
+- [x] `spotlessCheck` passed
+- [x] Unit tests passed
+- [x] Integration tests passed
+EOF
+)"
+```
+
+### 3.3 Decision Log
+
+Post as a PR comment:
+
+```bash
+gh pr comment <pr_number> --body "$(cat <<'EOF'
+## Decision Log
+**Root Cause**: <what actually caused the bug>
+**Approach**: <what was implemented and why>
+**Alternatives Rejected**: <what was considered and why it didn't work>
+**Pitfalls**: <dead ends, subtle edge cases discovered>
+**Things to Watch**: <known limitations, areas needing follow-up>
+EOF
+)"
+```
+
+---
+
+## Completion Gate
+
+Do NOT report "done" until every item below is checked. List each in your final report:
+
+- [ ] **Unit tests**: New test class or methods
+- [ ] **Integration test**: New `*IT.java` test
+- [ ] **YAML REST test**: `issues/<ISSUE>.yml`
+- [ ] **spotlessApply**: Ran successfully
+- [ ] **Tests pass**: Affected modules
+- [ ] **Commit**: DCO sign-off, `[BugFix]` prefix, no Co-Authored-By
+- [ ] **Draft PR**: `--draft`, body contains `Resolves #<issue>`
+- [ ] **Decision Log**: PR comment posted
+
+If any item is blocked, report which and why.
+
+---
+
+## Phase 4: Retrospective
+
+- [ ] Symptom in Quick Reference? Add if missing.
+- [ ] Classification correct? Fix routing if misleading.
+- [ ] Test template worked as-is? Fix if broken.
+- [ ] New pattern? Add to Case Index.
+
+Include harness improvements in the same PR.
diff --git a/.claude/harness/ppl-bugfix-reference.md b/.claude/harness/ppl-bugfix-reference.md
new file mode 100644
index 0000000000..615f91fb75
--- /dev/null
+++ b/.claude/harness/ppl-bugfix-reference.md
@@ -0,0 +1,148 @@
+# PPL Bugfix Reference
+
+Consult this file when you need fix-path-specific guidance or test templates.
+
+---
+
+## Fix Path Reference
+
+### Path A — Grammar / Parser
+
+1. Update grammar files (must stay in sync):
+   - `language-grammar/src/main/antlr4/OpenSearchPPLParser.g4` (primary)
+   - `ppl/src/main/antlr/OpenSearchPPLParser.g4`
+   - `async-query-core/src/main/antlr/OpenSearchPPLParser.g4` (if applicable)
+2. Regenerate: `./gradlew generateGrammarSource`
+3. Update AstBuilder: `ppl/.../parser/AstBuilder.java`
+4. Test: `AstBuilderTest`
+
+### Path B — AST / Function Implementation
+
+1. AST nodes in `core/.../ast/tree/`, functions in `core/.../expression/function/` or `PPLBuiltinOperators`
+2. Watch Visitor pattern — sync `AbstractNodeVisitor`, `Analyzer`, `CalciteRelNodeVisitor`, `PPLQueryDataAnonymizer`
+3. Test: `verifyLogical()`, `verifyPPLToSparkSQL()`, `verifyResult()`
+
+### Path C — Type System / Semantic Analysis
+
+1. `OpenSearchTypeFactory.java`, `Analyzer.java`, `ExpressionAnalyzer.java`
+2. Preserve nullable semantics; protect UDT from `leastRestrictive()` downgrade
+3. Test: type preservation, nullable propagation, mixed types
+
+### Path D — Optimizer / Predicate Pushdown
+
+1. `PredicateAnalyzer.java`, `LogicalPlanOptimizer`, `QueryService.java`
+2. Watch `nullAs` semantics; for plan bloat consider `FilterMergeRule`
+3. Verify: `EXPLAIN` output + integration test correctness
+
+### Path E — Execution / Resource Management
+
+1. `OpenSearchExecutionEngine.java`, `SQLPlugin.java`, `OpenSearchPluginModule.java`
+2. Common patterns: cache key collision, memory leak, unbounded growth, non-singleton, DI not injected
+
+---
+
+## Test Templates
+
+**Unit test** (extend `CalcitePPLAbstractTest`):
+```java
+public class CalcitePPLYourFixTest extends CalcitePPLAbstractTest {
+    public CalcitePPLYourFixTest() {
+        super(CalciteAssert.SchemaSpec.SCOTT_WITH_TEMPORAL);
+    }
+
+    @Before
+    public void init() {
+        doReturn(true).when(settings)
+            .getSettingValue(Settings.Key.CALCITE_ENGINE_ENABLED);
+    }
+
+    @Test
+    public void testBugScenario() {
+        verifyLogical("source=EMP | where SAL > 1000",
+            "LogicalFilter(condition=[>($5, 1000)])\n"
+            + "  LogicalTableScan(table=[[scott, EMP]])\n");
+    }
+}
+```
+
+**Integration test** (extend `CalcitePPLIT`):
+```java
+public class CalcitePPLYourFixIT extends CalcitePPLIT {
+    @Override
+    public void init() throws IOException {
+        super.init();
+        enableCalcite();
+    }
+
+    @Test
+    public void testBugFixEndToEnd() throws IOException {
+        JSONObject result = executeQuery("source=<index> | <your PPL>");
+        verifySchema(result, schema("field", "alias", "type"));
+        verifyDataRows(result, rows("expected_value_1"), rows("expected_value_2"));
+    }
+}
+```
+
+**YAML REST test** — place at `integ-test/src/yamlRestTest/resources/rest-api-spec/test/issues/<ISSUE>.yml`:
+```yaml
+setup:
+  - do:
+      indices.create:
+        index: test_issue_<ISSUE>
+        body:
+          settings: { number_of_shards: 1, number_of_replicas: 0 }
+          mappings: { properties: { <field>: { type: <type> } } }
+  - do:
+      query.settings:
+        body: { transient: { plugins.calcite.enabled: true } }
+---
+teardown:
+  - do:
+      query.settings:
+        body: { transient: { plugins.calcite.enabled: false } }
+---
+"<Bug description for issue #ISSUE>":
+  - skip: { features: [headers, allowed_warnings] }
+  - do:
+      bulk: { index: test_issue_<ISSUE>, refresh: true, body: ['{"index": {}}', '{"<field>": "<value>"}'] }
+  - do:
+      headers: { Content-Type: 'application/json' }
+      ppl: { body: { query: "source=test_issue_<ISSUE> | <your PPL>" } }
+  - match: { total: <expected> }
+  - length: { datarows: <expected> }
+```
+
+---
+
+## Symptom → Fix Path
+
+```
+SyntaxCheckException / unrecognized syntax       → Path A
+SemanticCheckException / type mismatch            → Path C
+Field type wrong (timestamp→string)               → Path C
+EXPLAIN shows predicate not pushed down           → Path D
+Multi-condition query: missing/extra rows         → Path D
+OOM / memory growth over time                     → Path E
+NPE in Transport layer                            → Path E
+"node must be boolean/number, found XXX"          → Path B
+Regex/function extraction offset                  → Path B
+```
+
+---
+
+## Case Index
+
+| Commit | Bug | Layer | Tests |
+|--------|-----|-------|-------|
+| `ada2e34` | UNION loses UDT type | Type System | 8 UT + 4 IT |
+| `26674f9` | rex capture group index shift | AST/Functions | Multiple UTs |
+| `b4df010` | isnotnull not pushed down with != | Optimizer | 2 UT + IT |
+| `e045d15` | Multiple filters OOM | Optimizer | 26 output updates |
+| `f024b4f` | High-cardinality GROUP BY OOM | Execution | Benchmark |
+| `97d5d26` | OrdinalMap cache collision + leak | Execution | — |
+| `90393bf` | Non-singleton ExecutionEngine leak | Resource | — |
+| `f6be830` | Transport extensions not injected | DI | — |
+| `734394d` | Grammar rule typo | Grammar | — |
+| `246ed0d` | Float precision flaky test | Test Infra | — |
+| `d56b8fa` | Wildcard index type conflict | Value Parsing | 3 UT + 1 IT + 1 YAML |
+| `5a78b78` | Boolean coercion from numeric in wildcard queries | Value Parsing | 3 UT + 1 IT + 1 YAML |
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000000..eae8ab7e33
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(./gradlew *)",
+      "Bash(gh issue:*)",
+      "Bash(gh pr:*)",
+      "Bash(gh api:*)",
+      "Bash(gh search:*)",
+      "Bash(gh run:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git stash:*)",
+      "Bash(git show:*)",
+      "Bash(git diff:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(git remote:*)",
+      "Bash(git fetch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git push -u:*)",
+      "Bash(git push --force-with-lease:*)",
+      "Bash(git merge:*)",
+      "Bash(git cherry-pick:*)",
+      "Bash(git reset --soft:*)"
+    ]
+  }
+}
diff --git a/.gitignore b/.gitignore
index 329348a7c1..bf9002f999 100644
--- a/.gitignore
+++ b/.gitignore
@@ -53,6 +53,10 @@ http-client.env.json
 .factorypath
 
 # Coding agent files (could be symlinks)
-.claude
+.claude/*
+!.claude/settings.json
+!.claude/commands/
+!.claude/harness/
+.claude/settings.local.json
 .clinerules
 memory-bank
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 4629dcf5fe..03f88a6004 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,46 +9,16 @@ OpenSearch SQL plugin — enables SQL and PPL (Piped Processing Language) querie
 ## Build Commands
 
 ```bash
-# Full build (compiles, tests, checks)
-./gradlew build
-
-# Fast build (skip integration tests)
-./gradlew build -x integTest
-
-# Build specific module
-./gradlew :core:build
-./gradlew :sql:build
-./gradlew :ppl:build
-
-# Run unit tests only
-./gradlew test
-
-# Run a single unit test class
-./gradlew :core:test --tests "org.opensearch.sql.analysis.AnalyzerTest"
-
-# Run integration tests
-./gradlew :integ-test:integTest
-
-# Run a single integration test
-./gradlew :integ-test:integTest -Dtests.class="*QueryIT"
-
-# Skip Prometheus if unavailable
-./gradlew :integ-test:integTest -DignorePrometheus
-
-# Code formatting
-./gradlew spotlessCheck    # Check
-./gradlew spotlessApply    # Auto-fix
-
-# Regenerate ANTLR parsers from grammar files
-./gradlew generateGrammarSource
-
-# Run plugin locally with OpenSearch
-./gradlew :opensearch-sql-plugin:run
-./gradlew :opensearch-sql-plugin:run -DdebugJVM   # With remote debug on port 5005
-
-# Run doctests
-./gradlew :doctest:doctest
-./gradlew :doctest:doctest -Pdocs=search    # Single file
+./gradlew build                          # Full build (compiles, tests, checks)
+./gradlew build -x integTest            # Fast build (skip integration tests)
+./gradlew :core:build                    # Build specific module
+./gradlew test                           # Unit tests only
+./gradlew :core:test --tests "*.AnalyzerTest"  # Single test class
+./gradlew :integ-test:integTest          # Integration tests
+./gradlew :integ-test:integTest -Dtests.class="*QueryIT"  # Single IT
+./gradlew spotlessCheck                  # Check formatting
+./gradlew spotlessApply                  # Auto-fix formatting
+./gradlew generateGrammarSource          # Regenerate ANTLR parsers
 ```
 
 ## Code Style
@@ -123,6 +93,10 @@ plugin (OpenSearch plugin entry point, Guice DI wiring)
 - **PhysicalPlan** implements `Iterator<ExprValue>` for streaming execution
 - **Guice** dependency injection in `OpenSearchPluginModule`
 
+## Fixing PPL Bugs
+
+Use `/ppl-bugfix #<issue_number>` to fix PPL bugs. It dispatches a subagent in an isolated worktree with a structured harness covering triage, fix, tests, and PR creation.
+
 ## Adding New PPL Commands
 
 Follow the checklist in `docs/dev/ppl-commands.md`:
@@ -142,11 +116,11 @@ Follow `docs/dev/ppl-functions.md`. Three approaches:
 
 ## Calcite Engine
 
-The project has two execution engines: the legacy **v2 engine** and the newer **Calcite engine** (Apache Calcite-based). Calcite is toggled via `plugins.calcite.enabled` setting (default: off in production, toggled per-test in integration tests).
+The execution engine is Apache Calcite-based, toggled via `plugins.calcite.enabled` (default: off in production, toggled per-test in integration tests).
 
 - In integration tests, call `enableCalcite()` in `init()` to activate the Calcite path
-- Some features (e.g., graphLookup) require pushdown optimization — use `enabledOnlyWhenPushdownIsEnabled()` to skip tests in the `CalciteNoPushdownIT` suite
-- `CalciteNoPushdownIT` is a JUnit `@Suite` that re-runs Calcite test classes with pushdown disabled; add new test classes to its `@Suite.SuiteClasses` list
+- Some features require pushdown optimization — use `enabledOnlyWhenPushdownIsEnabled()` to skip tests in `CalciteNoPushdownIT`
+- `CalciteNoPushdownIT` re-runs Calcite test classes with pushdown disabled; add new test classes to its `@Suite.SuiteClasses` list
 
 ## Integration Tests
 
diff --git a/CLAUDE_GUIDE.md b/CLAUDE_GUIDE.md
new file mode 100644
index 0000000000..f5eff489d6
--- /dev/null
+++ b/CLAUDE_GUIDE.md
@@ -0,0 +1,54 @@
+# Claude Commands
+
+Slash commands for Claude Code in this repository. Use them in any Claude Code session.
+
+## `/ppl-bugfix`
+
+Fix a PPL bug end-to-end or follow up on an existing PR.
+
+**Usage:**
+
+```
+/ppl-bugfix #1234                    # Single issue
+/ppl-bugfix PR#5678                  # Single PR follow-up
+/ppl-bugfix #1234 #5678 PR#9012     # Multiple in parallel
+/ppl-bugfix <github-url>            # By URL
+```
+
+**Permission mode flags** (optional, append to any input):
+
+| Flag | Mode | Description |
+|------|------|-------------|
+| `--safe` | `acceptEdits` | File edits auto-approved, Bash commands need manual approval |
+| `--yolo` | `bypassPermissions` | No prompts at all — subagent runs in isolated worktree (default) |
+
+**What it does:**
+
+1. Resolves issue/PR linkage automatically
+2. For new issues: dispatches a subagent in an isolated git worktree that follows the full bugfix harness (triage → fix → test → PR)
+3. For existing PRs: handles CI failures, review feedback, merge conflicts, or marks as ready
+
+**Related files:** [`.claude/harness/ppl-bugfix-harness.md`](.claude/harness/ppl-bugfix-harness.md)
+
+---
+
+## `/dedupe`
+
+Find duplicate GitHub issues for a given issue.
+
+**Usage:**
+
+```
+/dedupe 1234
+```
+
+**What it does:**
+
+1. Reads the target issue
+2. Runs 3+ parallel search strategies to find potential duplicates (only older issues)
+3. Verifies candidates by reading each one
+4. Posts a structured comment on the issue listing 1-3 confirmed duplicates (if any)
+
+**Skips:** closed issues, broad feedback issues, issues already checked
+
+**Related files:** [`scripts/comment-on-duplicates.sh`](scripts/comment-on-duplicates.sh)