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

Tests in `tests/`

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

Run the suite from the repository root:

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/. They use the repository's requirements-tools.txt (Pillow) and do not start Godot or Blender. See tests/README.md for the exact discovery command.

Which tools could become AI skills?

A skill is a procedure and decision guide, not a script wrapper. The useful split is project-specific judgement that an AI repeatedly needs, not a second copy of every command.

Recommended: elevate as a project skill

gig-line-blender-asset-contract (high value). Bundle the ordering and contract around blender_assets.py, npc_pipeline.py, bake_ao.py, npc_proportions.py and npc_baseline.py: the 13-bone npc_base contract, tint slots, 8,000/8,000 character cap, gear attach space, AO/UV rules, audit → fit → measure → baseline sequence, and the “inspect the diff before committing” rule. This is the workflow most likely to be repeated by an AI and most likely to be damaged by improvising.
gig-line-release-and-visual-qa (high value). Capture the sequence check_docs.py → check_screenshots.sh → screen_designs.py compare/judge → clean-worktree build_releases.sh → PUBLISH_DRY_RUN → checksum/upload checks. Include the optional nature of the vision judge, the clean-worktree trap and the release rollback rules.
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/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.

README.md

Gig Line Tools