docs/ASSETS.md

# Required external assets

This public copy includes the APE-L\(_D\) checkpoint required by the main detector. It intentionally excludes generated artifacts, credential-bearing files, private data, historical experiment outputs, and full dataset image payloads.

## Minimum smoke test

To validate one Orienter inference example, provide:

| Asset | Expected location or interface | Required metadata |
| --- | --- | --- |
| One representative XR screenshot | a test-only folder matching the question manifest | image license/permission and expected image ID |
| Matching question/context fixture | JSONL consumed by `approach/run_vlm.py`, generated by `scripts/generate_questions.py` when screenshots are available | selected prompt, provider, model ID, filename convention, and expected schema |
| App metadata cache | an external path supplied through `--app-metadata-cache` | `app_id`, app name, app description, source URL, version/date, license/permission |
| APE-L\(_D\) checkpoint | bundled at `approach/ovod/APE/ape_d_model_final.pth` | official source, Apache-2.0 license, SHA-256, and size recorded in `docs/MODEL_MANIFEST.md` |
| Built APE extension | local build/install under the target CUDA environment | generated from source after cloning; compiled artifacts are intentionally not redistributed |
| One supported provider credential | `openrouter-run` or an equivalent process-scoped secret manager | access to the selected OpenRouter model and an explicit spending limit |
| Expected prediction | private comparison fixture | expected candidate labels and approximate boxes |

Run `python -B scripts/verify_assets.py --repo-root .` to validate the bundled checkpoint size. Add `--hash-checkpoint` for SHA-256 verification. When screenshots and metadata are mounted, pass `--questions`, `--images-dir`, and `--app-metadata-cache` to check image naming, image ID consistency, and metadata coverage. Pass `--embedding-cache /path/to/embedding_dict.json` to hash the external semantic cache against `evaluation/cache_manifest.json` before an offline evaluation.

The default Stage 2 runner also verifies the released checkpoint hash before loading it. Loading any different PyTorch checkpoint requires the explicit `--trust-custom-checkpoint` flag and should be done only after independent provenance and checksum verification.

## Full paper reproduction

Provide or publish all of the following as versioned assets:

1. The 1,552-image XR UI screenshot payload and a canonical versioned annotation release. Selected COCO-format evaluation ground-truth splits are included in this repository, but must be tied to the public dataset version and license.
2. App, genre, and context-sensitive split manifests, including the extra non-interactable context annotations.
3. Steam/application metadata used for global context, preferably as a pinned JSON/JSONL cache that avoids live-page drift. The public runner fails closed on missing cache entries when `--app-metadata-cache` is supplied.
4. The complete prompt templates, demonstration examples, and the random-selection/seed policy.
5. Exact model identifiers and access paths for every Orienter variant evaluated in the paper. The code defaults to OpenRouter `openai/gpt-5.6-sol`; exact paper profiles are included for GPT-4o-2024-08-06, Claude 3.5 Sonnet, and Gemini 1.5 Pro. If a provider retires a historical route, supply equivalent access through a custom profile or direct vendor credentials and document the substitution.
6. The bundled APE-L\(_D\) checkpoint identity, official source, revision, license, and checksum in `docs/MODEL_MANIFEST.md`.
7. A working CUDA/PyTorch/Detectron2 APE environment with the APE native extension built locally from the released source tree.
8. The reviewed `embedding-3` semantic cache identified by `evaluation/cache_manifest.json`. Mount it read-only and use offline mode for historical reproduction. Zhipu access is optional and should be enabled only to extend a separate cache copy when a new model produces an uncached category.
9. Expected per-split metrics or prediction checksums for a deterministic regression check.
10. Hardware, CUDA, PyTorch, Python, and package versions from the successful experiment environment. See `docs/ENVIRONMENT.md` for the current public build boundary.

## Credential names found in code

The following names are referenced by the main or optional baseline paths:

- `OPENAI_API_KEY`
- `OPENROUTER_API_KEY`
- `GOOGLE_API_KEY`
- `ANTHROPIC_API_KEY`
- `ZHIPU_API_KEY`
- `ARK_API_KEY`
- `DASHSCOPE_API_KEY`
- `DEEPSEEK_API_KEY`
- `THEB_API_KEY`
- `INTERNVL_API_KEY`

Only `OPENROUTER_API_KEY` is needed for the recommended Orienter inference path; the other variables belong to optional evaluation or baseline code. Never send credentials through Git, issue trackers, logs, or README examples. Rotate any credential that has previously appeared in a file or experiment log.

Stage 1 sends full screenshots to the configured remote provider; reflection additionally sends crops and annotated scenes. Do not submit private or unauthorized screenshots. Review the provider's data-handling terms and keep generated candidates, predictions, traces, metadata caches, and error files outside the public repository because they can reveal source-image content or filenames.

## Publication format

For each data/model asset, publish: human-readable name, stable URL, version/revision, SHA-256, license, expected local path, compressed/uncompressed size, and a minimal schema example. The bundled APE checkpoint should be published through Hugging Face/LFS-style large-file storage; keep private raw data and generated experiment outputs outside the public repository.