[rahlk]

The quick-install block said "no system Java needed" and then demonstrated -a 2 — the first level that cannot work without one. That is the worst possible pairing: it tells a reader the exact opposite of the truth and hands them a command that proves it.

What is actually true

pip install codeanalyzer-java pulls jdk4py, whose runtime is a JRE. Verified:

bin/: java jcmd jfr jinfo jmap jps jrunscript jstack jstat jwebserver keytool rmiregistry

No javac. From -a 2 the analyzer shells out to the target project's Maven/Gradle wrapper to resolve dependencies and compile it — WALA reads compiled classes, not source — and that subprocess does its own JAVA_HOME discovery. So level 1 genuinely needs no system Java; level 2 onwards genuinely does.

Why the wrong claim was expensive

The failure is quiet. The run exits 0, warns on stderr, and returns a thinner graph:

[WARN]  RTA call graph unavailable (RuntimeException: No application classes found.); emitting declared edges only
[WARN]  L4 semantic ddg unavailable (WALA build failed); emitting the derived SDG vertices and param edges only

You keep declared call edges and the syntactic DDG; you lose the RTA overlay and the alias-aware prov: ["points-to"] edges. A caller checking only the exit status sees success.

Changes

• Quick-install example moves to -a 1, with an admonition stating the JRE/JDK split, the export JAVA_HOME=... you actually need, exactly what drops silently without it, and that --emit neo4j needs a JDK too since it always projects at full depth regardless of -a.
• The same correction in packaging/python/src/codeanalyzer_java/__init__.py — it made the "needs no system Java" claim inside the package users install, so fixing only the README would leave the false promise shipping on PyPI.
• Two FAQ entries for the adjacent surprise, both of which cost real debugging time today:
  • --no-build does not suppress dependency resolution. CodeAnalyzer.java:459 calls downloadLibraryDependencies unconditionally, so mvnw ... dependency:copy-dependencies still runs, prints BUILD SUCCESS, and writes into <project>/target/_library_dependencies/. It compiles nothing.
  • No application classes found under --no-build is the flag being taken at its word ("I have already built this"), not a bug.

Docs only; no behaviour change. Applies to 3.1.0 and every 3.0.x wheel.

Not fixed here

The two underlying defects, which want their own issues rather than a docs patch:

1. --no-build's contract. It reads as "do not run a build tool against my project" and it does. The obvious fix — skip dependency resolution too — would regress type resolution to bare spellings at every level, so this is a naming/contract decision, not a one-line guard.
2. The silent degradation. Losing the RTA overlay and the semantic DDG is a material change to what the graph contains, and it currently costs a WARN and exit 0. Worth considering a non-zero exit or an explicit marker in the payload so a programmatic caller can tell a full graph from a degraded one.