docs: document query owner context

Author: buger

docs/probe-agent/sdk/tools-reference.md

@@ -163,6 +163,7 @@ AST-based structural queries using tree-sitter patterns.
 | `path` | string | No | Directory to search |
 | `language` | string | No | Programming language |
 | `limit` | number | No | Maximum results |
+| `with_context` | boolean | No | Include owning source-block context in JSON output |
 
 **Example AI Usage:**
 ```xml
@@ -173,6 +174,17 @@ AST-based structural queries using tree-sitter patterns.
 </query>
 ```
 
+Use `with_context` when the exact AST match needs its enclosing function, method, class, attached comments, or call context for downstream analysis:
+
+```xml
+<query>
+  <pattern>fetch($$$ARGS)</pattern>
+  <language>typescript</language>
+  <path>./src</path>
+  <with_context>true</with_context>
+</query>
+```
+
 **Common Patterns:**
 - Functions: `fn $NAME() { $$$BODY }`
 - Classes: `class $NAME { $$$BODY }`

docs/probe-cli/query.md

@@ -119,6 +119,7 @@ probe query "go $FUNC($$$ARGS)" ./src -l go
 | `--allow-tests` | Boolean | false | Include test files |
 | `-i`, `--ignore` | String[] | - | Patterns to ignore |
 | `--no-gitignore` | Boolean | false | Don't respect .gitignore |
+| `--with-context`, `--owner-context` | Boolean | false | Include owning source-block context in JSON output |
 
 ### Language Options
 
@@ -156,10 +157,68 @@ probe query "fn $NAME()" ./src --format markdown
 # JSON for tooling
 probe query "fn $NAME()" ./src --format json
 
+# JSON with owning source-block context
+probe query "fetch($$$ARGS)" ./src --language typescript --format json --with-context
+
 # Plain text
 probe query "fn $NAME()" ./src --format plain
 ```
 
+### Owner Context JSON
+
+Use `--with-context` when a structural match is not enough by itself and the caller also needs the source block a human would inspect. This keeps `query` precise while adding neutral source facts such as the owning function, method, class, attached comments, and enclosing calls.
+
+```bash
+probe query "fetch($$$ARGS)" ./src --language typescript --format json --with-context
+```
+
+The default JSON fields remain available. With context enabled, each result can also include:
+
+```json
+{
+  "schema_version": "probe.query.context.v1",
+  "results": [
+    {
+      "file": "src/api.ts",
+      "lines": [4, 4],
+      "node_type": "match",
+      "content": "fetch(url)",
+      "column_start": 10,
+      "column_end": 20,
+      "language": "typescript",
+      "pattern": {
+        "source": "fetch($$$ARGS)",
+        "id": null
+      },
+      "match": {
+        "node_type": "call_expression",
+        "content": "fetch(url)",
+        "lines": [4, 4],
+        "columns": [10, 20]
+      },
+      "owner": {
+        "symbol": "loadProfile",
+        "qualified_symbol": "loadProfile",
+        "node_type": "function_declaration",
+        "scope": "function",
+        "lines": [2, 5],
+        "columns": [1, 2],
+        "comments": [
+          {
+            "kind": "leading",
+            "start_line": 1,
+            "end_line": 1,
+            "text": "// Network boundary: user profile API client."
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+Probe does not interpret comment contents or apply domain policy. Downstream tools decide whether a comment is a requirement, security annotation, checklist marker, or ordinary text.
+
 ---
 
 ## Common Patterns

docs/reference/output-formats.md

@@ -125,6 +125,61 @@ The `query` command's JSON output is similar to the search command but includes
 }
 ```
 
+When `--with-context` or `--owner-context` is used with `--format json`, Probe keeps the compatible result fields and adds source-block context for each structural match:
+
+```json
+{
+  "schema_version": "probe.query.context.v1",
+  "results": [
+    {
+      "file": "/path/to/api.ts",
+      "lines": [4, 4],
+      "node_type": "match",
+      "content": "fetch(url)",
+      "column_start": 10,
+      "column_end": 20,
+      "language": "typescript",
+      "pattern": {
+        "source": "fetch($$$ARGS)",
+        "id": null
+      },
+      "match": {
+        "node_type": "call_expression",
+        "content": "fetch(url)",
+        "lines": [4, 4],
+        "columns": [10, 20]
+      },
+      "owner": {
+        "symbol": "requestJSON",
+        "qualified_symbol": "requestJSON",
+        "node_type": "function_declaration",
+        "scope": "function",
+        "lines": [1, 5],
+        "columns": [1, 2],
+        "comments": [
+          {
+            "kind": "leading",
+            "start_line": 1,
+            "end_line": 1,
+            "text": "// Handles outbound API calls."
+          }
+        ],
+        "enclosing_symbols": [],
+        "enclosing_calls": []
+      }
+    }
+  ],
+  "summary": {
+    "count": 1,
+    "total_bytes": 10,
+    "total_tokens": 3
+  },
+  "version": "0.0.0"
+}
+```
+
+The context fields are intentionally source facts only. Probe reports owner, match, comment, symbol, and enclosing-call metadata; it does not interpret requirements, policies, test frameworks, or annotation formats.
+
 #### Example: Query JSON Output
 
 ```bash
@@ -622,4 +677,4 @@ Both JSON and XML formats handle special characters appropriately:
 - **JSON**: Special characters in code are properly escaped according to JSON rules
 - **XML**: Code blocks are wrapped in CDATA sections to preserve formatting and special characters
 
-This ensures that the output can be reliably parsed regardless of the content of the code.
+This ensures that the output can be reliably parsed regardless of the content of the code.