[jwrosewell]

Merge order

Merge this after #28, which moves the examples and tests to the data
repository in cxx/data and removes ip-intelligence/ip-intelligence-data.
The run steps here describe only that layout, so they are wrong on rc until
#28 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, two product
READMEs, the package READMEs, the CI scripts and the example sources, and
would meet the problems listed under "Pitfalls" by trial and error.

What changes

AGENTS.md opens with a new section, "Run the examples", in the same shape as
the one in 51degrees-cxx#98,
for the on-premise gettingstarted_console of Device Detection and of IP
Intelligence.

1. Prerequisites. Python 3.10 or later is the README's, and CI tests 3.10
   to 3.14 (ci/options.json). The compiler requirements are the Device
   Detection README's, with C11 and C++17 from the -std=gnu11 and
   -std=gnu++17 flags in the on-premise setup.py files. A compiler is
   needed even from PyPI, because PyPI has only source distributions of
   fiftyone-devicedetection-onpremise (4.5.100) and
   fiftyone-ipintelligence-onpremise (4.5.1), as its JSON API lists. The
   data file tools are the ones the data repository's scripts need, curl,
   gzip and md5sum (md5 on macOS) on Linux and macOS, and Windows
   PowerShell 5.1 or PowerShell 7 on Windows.
2. Data files. The free files, the Asn file included, are links in
   cxx/data, and cxx/data/get-data-files.sh or get-data-files.ps1
   downloads them, as Read the data files from the data repository in cxx/data #28's README says. On Windows the step runs the script
   with powershell -NoProfile -ExecutionPolicy Bypass -File, as __download
   in both example_utils.py files does, because the policy Windows sets by
   default can refuse a script file.
3. Build. The install commands are the ones the Device Detection README
   ("Build from Source") and the IP Intelligence README ("From source") give,
   run in a virtual environment as CI runs the examples
   (device-detection/ci/run-integration-tests.ps1). requirements.txt is
   installed first, as device-detection/setup.ps1 does, with setuptools,
   which ip-intelligence/ci/setup-environment.ps1 installs because Python
   3.12 and later no longer do.
4. Run. With no argument, find_file in the Device Detection
   example_utils.py looks for cxx/data/device-detection in the working
   folder and each folder above it, and downloads the Lite file there when it
   is missing, so the example runs from the root with no argument. With no
   argument, the IP Intelligence example looks for the Asn file in .,
   assets and cxx/data/ip-intelligence of the working folder and the seven
   above it, and downloads it the same way. A path given as the first argument
   is used as it is (main in each gettingstarted_console.py), so the Lite
   IP Intelligence file is downloaded with the script before it is given.
5. Correct output, read from both gettingstarted_console.py files, both
   example_utils.py files, both example_constants.py files and
   pipeline/fiftyone_pipeline_core/src/fiftyone_pipeline_core/logger.py,
   which logs through Python's logging.
6. Cloud examples. The variables each cloud example reads come from its
   main and example_utils.py. The Device Detection key link is the
   configuration 1QWJwHxl that the example's own error message names.
7. Pitfalls, each checked in the repository, including the C:\tmp
   workaround in device-detection/ci/run-integration-tests.ps1 and the
   README's pipenv install with no Pipfile anywhere.

The second commit removes what the first said about the layout rc had
before #28, being the steps for the old data submodules and Git LFS, the
committed Asn file, 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. The search pitfall now describes running outside the repository or
without the submodules, the only cases in which the Device Detection example
still searches.

The "Releases" section from #29 is added with the same text in the same
place. Every other section is unchanged. #28 rewrites the "Submodules" 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
  Read the data files from the data repository in cxx/data #28's head (5e5ba20), being both example_utils.py files, both
  gettingstarted_console.py files, both example_constants.py files, both
  ci/fetch-assets.ps1 files and the IP Intelligence example tests, and
  against the data repository at the commit cxx 4.5.103 pins (e448dcf) for
  the scripts and their options.
• git merge-tree merges this branch with Read the data files from the data repository in cxx/data #28's head, with Describe the rc approach to releases in AGENTS.md #29's head
  (a9732af) and with rc, each with no conflict, and the merged AGENTS.md
  names neither old data folder.
• 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

• python3 -m venv .venv and its activation. CI makes a virtual environment
  for the examples with python3 -m venv .virtualenv and calls its Python
  directly.
• python -m pip install -r requirements.txt setuptools, which joins what
  device-detection/setup.ps1 and ip-intelligence/ci/setup-environment.ps1
  install.
• resource_key=<key> in front of the IP Intelligence cloud example, as the
  Device Detection README writes it for its own.

Wrong outside AGENTS.md, left for another change

• device-detection/readme.md recommends Pipenv, and there is no Pipfile
  in the repository.

Still to do

• The output described has not been compared with a real run against the free
  files. A run from a fresh clone, following only AGENTS.md, is the check.