security-game/tools/README.md

# Gig Line Tools

Developer and release tooling for Gig Line. Nothing in this directory runs in
the game at runtime; the tools generate or audit committed assets, capture
visual evidence, and build/publish releases. They are intentionally kept outside
`src/` and outside the exported runtime scripts.

## File inventory

All tracked source files are listed here; generated `__pycache__/` and
`.ruff_cache/` contents are ignored.

| File | Kind |
| --- | --- |
| [`README.md`](README.md) | this guide |
| [`asset_pipeline.py`](asset_pipeline.py) | Python: image generation and audit |
| [`bake_ao.py`](bake_ao.py) | Python/Blender: AO baking |
| [`blender_assets.py`](blender_assets.py) | Python/Blender: character, gear and prop library |
| [`build_releases.sh`](build_releases.sh) | shell: release export/packaging |
| [`check_docs.py`](check_docs.py) | Python: documentation gate |
| [`check_screenshots.sh`](check_screenshots.sh) | shell: gallery capture/compare |
| [`describe_image.py`](describe_image.py) | Python: free-form vision review of captures/refs |
| [`export_venues.gd`](export_venues.gd) | GDScript: venue `.tres` export |
| [`export_venues.gd.uid`](export_venues.gd.uid) | Godot UID sidecar |
| [`generate_textures.py`](generate_textures.py) | Python: procedural/AI textures |
| [`make_normal_maps.py`](make_normal_maps.py) | Python: derived normal maps |
| [`model_pipeline.py`](model_pipeline.py) | Python/Blender: prop models and atlases |
| [`npc_baseline.py`](npc_baseline.py) | Python: NPC baseline/compare sheets |
| [`npc_pipeline.py`](npc_pipeline.py) | Python/Blender: NPC base and texture maps |
| [`npc_proportions.py`](npc_proportions.py) | Python: exported-GLB proportion audit |
| [`openrouter_judge.py`](openrouter_judge.py) | Python: shared OpenRouter judge client |
| [`publish_release.sh`](publish_release.sh) | shell: release upload/preflight |
| [`refboard.py`](refboard.py) | Python: licensed reference candidate board |
| [`refcollect.py`](refcollect.py) | Python: local-only image research fetcher |
| [`scene_concepts.py`](scene_concepts.py) | Python: concepts, texture processing, realism |
| [`screen_designs.py`](screen_designs.py) | Python: screen mockups, compare and judge |
| [`three_up.py`](three_up.py) | Python: photo/concept/capture boards |
| [`tests/`](tests/) | Python tooling tests, test README and package marker |
| [`tests/README.md`](tests/README.md) | test-run instructions |
| [`tests/__init__.py`](tests/__init__.py) | package marker for module-style discovery |

### Tests in `tests/`

| Test | Covers |
| --- | --- |
| [`test_asset_pipeline.py`](tests/test_asset_pipeline.py) | image roles, generation helpers and audit |
| [`test_blender_assets.py`](tests/test_blender_assets.py) | catalogue, contract, fit, texels and manifest |
| [`test_check_docs.py`](tests/test_check_docs.py) | README/link/image documentation gate |
| [`test_generate_textures.py`](tests/test_generate_textures.py) | texture generation helpers |
| [`test_model_pipeline.py`](tests/test_model_pipeline.py) | prop models, palette atlas and GLB output |
| [`test_model_review.py`](tests/test_model_review.py) | scorecard coverage for the 3D review |
| [`test_npc_baseline.py`](tests/test_npc_baseline.py) | baseline sheet/comparison selection |
| [`test_npc_pipeline.py`](tests/test_npc_pipeline.py) | NPC contract, textures and committed model |
| [`test_npc_proportions.py`](tests/test_npc_proportions.py) | exported proportion measurements |
| [`test_openrouter_judge.py`](tests/test_openrouter_judge.py) | model selection, retries and errors |
| [`test_refboard.py`](tests/test_refboard.py) | licence gate, recent filter and row output |
| [`test_refcollect.py`](tests/test_refcollect.py) | search parsing, retries and local downloads |
| [`test_scene_concepts.py`](tests/test_scene_concepts.py) | processing, promotion, references and judge |
| [`test_screen_designs.py`](tests/test_screen_designs.py) | design catalogue, compare and judge |
| [`test_three_up.py`](tests/test_three_up.py) | three-up composition and captions |

Run the suite from the repository root:

```bash
python3 -m pip install -r requirements-tools.txt
python3 -m unittest discover -s tools/tests -t tools -p 'test_*.py'
```

## Categories

### 1. Asset generation and authoring

These produce or modify committed assets. Prefer a **clean worktree**, inspect
the diff, and run the matching audit before committing generated files.

| Tool | Purpose | Typical command |
| --- | --- | --- |
| `blender_assets.py` | Catalogue/build/audit/inspect/fit/texel/sheet the character, gear and prop library. `build`/`render` need Blender; `audit`/`fit`/`inspect` are standalone. | `python3 tools/blender_assets.py audit` |
| `npc_pipeline.py` | Prepare AI fabric tiles, derive outfit palettes, build `npc_base`, audit the NPC contract. | `python3 tools/npc_pipeline.py audit` |
| `bake_ao.py` | Blender AO bake for library assets. | `flatpak run org.blender.Blender --background --python "$PWD/tools/bake_ao.py" -- --only npc_guard` |
| `npc_proportions.py` | Measure exported GLBs against the stylized proportion guide. | `python3 tools/npc_proportions.py report` |
| `npc_baseline.py` | Compose neutral baseline sheets and before/after comparisons. | `python3 tools/npc_baseline.py sheet --dir tmp/npc-baseline` |
| `asset_pipeline.py` | Generate, crop, resize, seam-fix and audit images by role. | `python3 tools/asset_pipeline.py audit assets/textures` |
| `generate_textures.py` | Procedural texture generation with an optional AI mode. | `python3 tools/generate_textures.py` |
| `make_normal_maps.py` | Derive tangent normal maps from albedo textures. | `python3 tools/make_normal_maps.py <texture.png>` |
| `model_pipeline.py` | Build low-poly props and single-material palette atlases. | `python3 tools/model_pipeline.py build` |
| `scene_concepts.py` | Generate concept frames, process/promote texture picks, and run the realism judge. | `python3 tools/scene_concepts.py audit` |
| `screen_designs.py` | Generate screen-design references and compare/judge captures. | `python3 tools/screen_designs.py compare` |
| `three_up.py` | Compose labelled real-photo/concept/capture boards. | `python3 tools/three_up.py compose --help` |
| `openrouter_judge.py` | Shared OpenRouter client for model selection, retries and JSON parsing. | normally imported by the judge tools |

### 2. Reference research and provenance

| Tool | Purpose | Notes |
| --- | --- | --- |
| `refboard.py` | Search Wikimedia Commons (search/geo/category), gate by licence and age, fetch candidates, emit sidecar rows. | Committed-board source; run with the licence gate. |
| `refcollect.py` | DuckDuckGo image search/fetch and local contact sheets. | **Local-only research**: downloads stay in `tmp/research/`, never committed. |
| `three_up.py` | Pair a real reference, generated concept and current capture in one review board. | The photos remain evidence, not shipped art. |

### 3. Validation and review

| Tool | Purpose | Typical command |
| --- | --- | --- |
| `check_docs.py` | Verify README coverage, local links and tracked-image links. | `python3 tools/check_docs.py` |
| `check_screenshots.sh` | Re-render the committed gallery and run the Pillow comparison. | `./tools/check_screenshots.sh` |
| `npc_baseline.py` | Baseline/compare character contact sheets. | see above |
| `npc_proportions.py` | Proportion gate on exported GLBs. | see above |
| `screen_designs.py compare/judge` | Screen-design drift gate and optional vision review. | `python3 tools/screen_designs.py compare` |
| `scene_concepts.py realism` | Optional realism-review and judge pass. | `python3 tools/scene_concepts.py realism --run <dir>` |

### 4. Runtime/content export

| Tool | Purpose | Typical command |
| --- | --- | --- |
| `export_venues.gd` | Export `content/venues/*.tres` from `ScenarioFactory`. | `godot --headless --path . --script res://tools/export_venues.gd` |

### 5. Build and release

| Tool | Purpose | Typical command |
| --- | --- | --- |
| `build_releases.sh` | Export Linux/Windows/macOS/Web and package the optional Desktop HQ zip. **Run from a clean worktree.** | `./tools/build_releases.sh` |
| `publish_release.sh` | Preflight artifacts/free space, write SHA-256 checksums, upload with rollback, optional retention pruning. | `PUBLISH_DRY_RUN=1 ./tools/publish_release.sh` |

The clean-worktree requirement is important: a normal working tree may contain
ignored `tmp/` and `build/` content that Godot can pack into the export.

### 6. Tests

All Python tooling tests live in [`tests/`](tests/). They use the repository's
`requirements-tools.txt` (Pillow) and do not start Godot or Blender. See
[`tests/README.md`](tests/README.md) for the exact discovery command.

## Project AI skills

Two project-authored skills now live under
[`../.agents/skills/`](../.agents/skills/) and are tracked in the repository:

- [`gig-line-blender-asset-contract`](../.agents/skills/gig-line-blender-asset-contract/SKILL.md) — contract, command order, failure playbook and verification for Blender/NPC/gear/prop work.
- [`gig-line-release-qa`](../.agents/skills/gig-line-release-qa/SKILL.md) — test/smoke matrix, visual gates, clean build, checksums, tag/publish and release records.

The third-party `blender-skills` pack remains local/gitignored. These project
skills are guidance only; they do not move scripts into `.agents`, add runtime
dependencies or replace the tools above.

### Remaining skill candidate

- **`gig-line-reference-provenance` (medium value).** Guide `refboard.py` vs
  `refcollect.py`: committed Wikimedia-sourced boards with sidecars versus
  local-only `tmp/research/` downloads, and the rule that generated concepts
  never override photo evidence. This is more of a policy skill than a command
  skill.

### Keep as scripts

- `asset_pipeline.py`, `generate_textures.py`, `make_normal_maps.py`,
  `model_pipeline.py` and `scene_concepts.py` are general generation/processing
  utilities. A skill should point to their documented commands rather than
  duplicate them; several call paid APIs and must stay human-triggered.
- `screen_designs.py` and `scene_concepts.py` judge modes are optional,
  network/budget-dependent review aids, not deterministic CI gates.
- `openrouter_judge.py` is an implementation detail imported by other tools.
- `check_docs.py` and `export_venues.gd` are short, single-purpose commands;
  documenting them in this README and `docs/assets/asset-tooling.md` is enough.
- `npc_baseline.py`, `npc_proportions.py` and `three_up.py` are better included
  as references/steps inside the proposed asset or release skill than exposed as
  separate skills; fragmenting them would increase routing mistakes.

Do **not** move scripts into `.agents/skills/`: the local Blender skill pack is
gitignored guidance, while these tools are tracked project code with tests and
CI-relevant contracts. A future skill should reference this directory and the
project docs, not fork the implementation.