cquery docs updates:

- Add a "Troubleshooting" section with initial entry describing "/..." challenges.
- Remove "Updates" section. This is redundant. The hotlist link isn't particularly useful. Better to funnel users through standardized help links.

PiperOrigin-RevId: 372633052

site/docs/cquery.html

@@ -735,11 +735,44 @@ <h2 id='known-issues'>Known issues</h2>
   </li>
 </ul>
 
-<h2 id='updates'>Updates</h2>
+<h2 id='troubleshooting'>Troubleshooting</h2>
+
+<h3>Recursive target patterns (<code>/...</code>)</h3>
+
+<p>
+  If you encounter:
+</p>
+
+<pre>
+$ bazel cquery --universe_scope=//foo:app "somepath(//foo:app, //foo/...)"
+ERROR: Error doing post analysis query: Evaluation failed: Unable to load package '[foo]'
+because package is not in scope. Check that all target patterns in query expression are within the
+--universe_scope of this query.
+</pre>
 
 <p>
-  The Bazel configurability team is continuously improving <code>cquery</code>. If you want to
-  ask questions, stay updated, or get involved, contact
+  this incorrectly suggests package <code>//foo</code> isn't in scope even though
+  <code>--universe_scope=//foo:app</code> includes it. This is due to design limitations in
+  <code>cquery</code>. As a workaround, explicitly include <code>//foo/...</code> in the universe
+  scope:
+</p>
 
-  the Bazel team at one of <a href="https://bazel.build/support.html">these channels</a>.
+<pre>
+$ bazel cquery --universe_scope=//foo:app,//foo/... "somepath(//foo:app, //foo/...)"
+</pre>
+
+<p>
+  If that doesn't work (for example, because some target in <code>//foo/...</code> can't build
+  with the chosen build flags), manually unwrap the pattern into its constituent packages with a
+  pre-processing query:
 </p>
+
+<pre>
+# Replace "//foo/..." with a subshell query call (not cquery!) outputting each package, piped into
+# a sed call converting "&lt;pkg&gt;" to "//&lt;pkg&gt;:*", piped into a "+"-delimited line merge.
+# Output looks like "//foo:*+//foo/bar:*+//foo/baz".
+#
+$  bazel cquery --universe_scope=//foo:app "somepath(//foo:app, $(bazel query //foo/...
+--output=package | sed -e 's/^/\/\//' -e 's/$/:*/' | paste -sd "+" -))"
+</pre>
+