[jwrosewell]

Merge order

Merge this after #22, 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 #22 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
product readmes, the two run_examples.md files, the CI scripts and the
example sources. The step most likely to be missed is the native module, which
every on-premise example needs before it can load, because the examples use
the packages in this repository rather than the ones published to npm.

What changes

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

1. Prerequisites. Node.js 22 or 24 come from ci/options.json and
   SUPPORTED_NODE_MAJOR_VERSIONS in ip-intelligence/ensure-native-module.js,
   and node-gyp 12's Node.js range from the comment in
   ci/build-extension.ps1. The toolchain is the one the product readmes'
   "Build from Source On-Premise" sections give, with the apt-get line
   ci/build-extension.ps1 runs on Linux. 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 are links in cxx/data, and
   cxx/data/get-data-files.sh or get-data-files.ps1 downloads them, as
   Move the examples, tests and CI to the cxx data submodule #22's README says. On Windows the step runs the script with
   powershell -NoProfile -ExecutionPolicy Bypass -File, as
   getDataFilesCommand in each exampleUtils.js does, because the policy
   Windows sets by default can refuse a script file. The size checks are the
   minimums the data repository's
   Download scripts
   workflow checks.
3. Build. npm install is the README's. The Device Detection module is
   built as ci/build-extension.ps1 builds it, with
   npx --yes node-gyp@12 configure and build, then copied to the name
   deviceDetectionOnPremise.js loads, which the README describes.
   For IP Intelligence it uses ensure-native-module.js, which
   ip-intelligence/readme.md gives as the one command that does every step.
4. Run. Each example runs from its own folder with node gettingStarted.js,
   as run_examples.md says and as ci/run-integration-tests.ps1 runs the web
   examples. Both examples ask for their Lite file by name, and findFile in
   each exampleUtils.js reads a linked file from cxx/data, by a path
   relative to that file, and runs the download script when it is missing.
   51DEGREES_DD_PATH or 51DEGREES_IPI_PATH is looked at first.
5. Correct output, read from the two gettingStarted.js files, the
   exampleConstants.js and dataExtension.js of each shared package and
   checkDataFile and getLinkedFile in each exampleUtils.js. The IP
   Intelligence example runs on the Lite file, because getValueHelper
   catches the error for a property the file lacks and prints Unknown (...).
6. Cloud examples. The configurator links are the ones in
   device-detection/readme.md and ip-intelligence/readme.md. The key
   names come from each cloud package's examples/cloud/exampleUtils.js, and
   the Device Detection example reads 51d.json from the working folder
   (fs.readFileSync('51d.json')).
7. Pitfalls, each checked in the repository. The native module errors are
   moduleDirNotFound and nativeModuleNotFound in
   device-detection/fiftyone.devicedetection.shared/errorMessages.js, the
   warning about npm install is in both product readmes, win_warn_as_error
   is in both binding.51d files, the WSL note is ip-intelligence/readme.md's,
   and the CI links are in ci/fetch-assets.ps1 and the two
   tests/testHelper.js files.

The second commit removes what the first said about the layout rc had
before #22, being the steps for the old data submodules and Git LFS, the
choice between two layouts, the Git LFS pointer pitfall, the pitfall about the
10 second search, which these examples no longer make, 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 CI pitfall now says CI reads the Lite IP Intelligence file only
when it has no IP Intelligence licence, because #22's ci/fetch-assets.ps1
downloads the free files that no asset covers.

Every other section is unchanged, and the "Releases" section is kept as it
is. #22 rewrites the "Data files" 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
  Move the examples, tests and CI to the cxx data submodule #22's head (266c1b4), being both exampleUtils.js files, both
  gettingStarted.js files, ci/fetch-assets.ps1 and the Device Detection
  tests/testHelper.js, 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 Move the examples, tests and CI to the cxx data submodule #22's head, and with rc, with no
  conflict, and the merged run steps name neither old data submodule.
• 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

• node -p "process.platform + '-' + process.arch + '-' + process.versions.node.split('.')[0]",
  which prints the part of the module name that deviceDetectionOnPremise.js
  builds from os.platform(), process.arch and the major version, and the
  cp to that name, which the README describes in words.
• node ip-intelligence/ensure-native-module.js. ip-intelligence/readme.md
  says to run node ensure-native-module.js "from the repository root",
  which was the root of the repository the folder came from. The script
  finds the package from its own folder, so it runs from anywhere.
• The cd back to the root after each step, and the env 51DEGREES_IPI_PATH=...
  form, which follows from the variable names in the example sources.

Still to do

• The output described has not been compared with a real run of each example
  against the Lite files, and the native build has not been run from these
  steps. A run from a fresh clone, following only AGENTS.md, is the check.