[jwrosewell]

Merge order

Merge this after #37, which moves the examples, tests and CI to the data
repository in cxx/data. The run steps here describe only that layout, so
they are wrong on rc until #37 is in.

Why

AGENTS.md held notes for changing the code, and nothing on running an
example. Someone new to the repository, asked only to get an example running
and show it, had to piece the steps together from the root README, the two
example READMEs, the poms and the example sources, and would still meet the
problems listed under "Pitfalls" by trial and error.

What changes

AGENTS.md opens with a new section, "Run the examples", which gives the
steps in order for the Device Detection and IP Intelligence
GettingStartedOnPrem console examples.

1. Running needs no native build. The examples use
   device-detection.version and ip-intelligence.version, 4.5.128 on rc
   and on Use the data repository for the examples, tests and CI #37's head, from Maven Central unless -Pdev is given
   (examples/*/pom.xml). The published device-detection.hash.engine.on-premise
   and ip-intelligence.engine.on-premise 4.5.128 jars were downloaded and
   their entries listed, and they hold the native libraries named under
   "Pitfalls". The device-detection.shared and ip-intelligence.shared test
   jars the examples also take are on Maven Central at 4.5.128.
2. Prerequisites, from the README's "Building" (JDK 8 or later, Maven 3.8
   or mvnw), ci/options.json (Java 8, 11, 17 and 21) and the tools the
   data repository's download scripts need. On Linux and macOS that is
   curl, gzip and md5sum (md5 on macOS), and on Windows it is Windows
   PowerShell 5.1 or PowerShell 7.
3. Data files. The free files are links in cxx/data, and
   cxx/data/get-data-files.sh or get-data-files.ps1 downloads them. On
   Windows the step runs the script with
   powershell -NoProfile -ExecutionPolicy Bypass -File, as runDownload in
   both DataFileHelper.java files does, because the policy Windows sets by
   default can refuse a script file.
4. Build. mvn -pl console -am package -DskipTests, run in an examples
   folder, is the form ci/run-integration-tests.ps1 uses for the cloud web
   example. The fat jar comes from the jar-with-dependencies assembly that
   each console/pom.xml binds to package.
5. Run. java -cp <jar> <class> from the root. FileFinder.getFilePath
   searches only below user.dir when project.root is not set, and the
   examples find logback.xml, the data file, a missing file's .link and
   their options XML that way. findDataFile in DataFileHelper.java runs
   the download script for a free file that is missing. The IP Intelligence
   example defaults to ip-intelligence/51Degrees-EnterpriseIpiV41.ipi
   (DataFileHelper.ENTERPRISE_DATA_FILE_REL_PATH), so it is given
   cxx/data/ip-intelligence/51Degrees-LiteV41.ipi as its first argument,
   which it downloads when the file is missing.
6. Correct output, read from both GettingStartedOnPrem.java files, both
   EvidenceHelper.java files, both DataFileHelper.java files and the IP
   Intelligence PropertyHelper.tryGet, which turns a property the data file
   lacks into an "Unknown" line rather than an exception.
7. Cloud examples. The Device Detection configurator link is the one
   examples/device-detection/README.md gives, and KeyHelper and
   GettingStartedCloud.main say where the key is read from.
8. Pitfalls, each checked in the repository or, for the platforms the jars
   cover, in the published jars.

The second commit removes what the first said about the layout rc had
before #37, being the steps for the old data submodules and Git LFS, the
choice between two layouts, the Git LFS pointer pitfall and the line endings
pitfall. The data repository's
.gitattributes
keeps its shell script and its links LF, so the line endings pitfall no longer
applies.

Every other section is unchanged. The "Releases" section from #39 is added
with the same text in the same place. #37 rewrites the "Data files and
project.root" notes further down, which this pull request leaves alone.

How it was checked

• Every path, command and message in the new section was checked against
  Use the data repository for the examples, tests and CI #37's head (8e50767), being both DataFileHelper.java files, both
  GettingStartedOnPrem.java files, the IP Intelligence
  gettingStartedOnPrem.xml, FileFinder.java, the example poms and
  ci/fetch-assets.ps1, and against the data repository at the commit cxx
  4.5.103 pins (e448dcf) for the scripts, their options and the shell
  script's executable bit.
• git merge-tree merges this branch with Use the data repository for the examples, tests and CI #37's head, with Describe the rc approach to releases in AGENTS.md #39's head
  (6ca4f17) and with rc, each with no conflict.
• The "UTM link lint" and "Only rc into main" checks run on this pull request.
• Nothing was built or run, because the change is to AGENTS.md alone.

Commands that neither CI nor the README gives

• mvn -pl console -am package -DskipTests in an examples folder adapts CI's
  command for the cloud web example to the console module.
• The java -cp commands use the README form with today's jar names and
  GettingStartedOnPrem in place of OfflineProcessing, and are run from the
  root with paths from there.

Found on the way, not changed here

• examples/device-detection/README.md and examples/ip-intelligence/README.md
  run java from the examples folder, where FileFinder cannot reach the data
  file in cxx, and name jars at 4.4.20 and 4.4.19.

Still to check

• The commands have not been run. A run from a fresh clone, following only
  AGENTS.md, is the check.