tarinai/docs/MAINTENANCE.md

# Maintenance

## Release process

1. Edit source files.
2. Bump `app_manifest.json` and `js/version.js` to the same version.
3. Regenerate static references: `python3 scripts/generate_app_files.py`.
4. Regenerate item icons if item visuals changed: `python3 scripts/generate_item_icons.py`.
5. Check versions: no stale `v=<old>` in `index.html`, CSS icon URLs, `service-worker.js`.
6. Validate syntax: `node --check js/*.js service-worker.js`. If Node is not installed on the local machine, document that explicitly in the handoff and use browser-console smoke checks instead.
7. Open `index.html` in a browser and verify startup, reset field selection, one tool placement, observe selection, family tree render, sound menu toggles, and `?debug=1`.
8. Zip from project root and run `zip -T`.

If `scripts/generate_app_files.py` cannot run locally, manually keep these in sync: `app_manifest.json`, `index.html` script/link tags, and `service-worker.js` `coreScriptNames`/CSS cache entries.

## Cache rules

`service-worker.js` must remain no-cache/no-store in `.htaccess`; versioned JS/CSS/WebP can be immutable. Register service worker with `updateViaCache: "none"`.

## Debugging

Use `?debug=1` for FPS, performance level, counts, cache/SW state, last audio ID, effect registry count, terrain/spatial version, and recent event-bus history.

Useful browser-console checks:

- `TARINAI_VERSION` and `TARINAI_APP.cacheName` confirm version/cache naming.
- `world.fieldType`, `world.tarinai.length`, `world.items.length`, and `world.ants.length` confirm the active simulation shape.
- `TarinaiEffectRegistry.debugSnapshot()` confirms registered item effects.
- `TarinaiDiseaseRegistry.debugSnapshot()` confirms disease metadata.
- `TarinaiFoodRegistry.debugSnapshot()` confirms food semantics.
- `toolCategories().map(c => c.id)` confirms the runtime tool palette registry.
- `TarinaiInputMode.snapshot()` confirms mobile classification and mode policy.
- `TarinaiEvents.recent(null, 20).map(e => e.type)` confirms domain-event emission.
- `validateFamilyTree()` checks reciprocal family links and rendered family tree node/link consistency.
- `familyTreeDiagnostics()` reports the latest async archive render state.

## Mobile input

The mobile mode controls are owned by `TarinaiInputMode` and are only for compact/no-hover/coarse-pointer touch-first devices. Desktop browsers, including touch-screen PCs, should not show the mobile controls unless the viewport or UA also indicates mobile/tablet.

The mode state is stored as `tarinai_mobile_input_mode_v1`; sound settings use `tarinai_audio_settings_v2`; log push settings use `tarinai_log_push_settings_v2`.

## Prompt archive

`docs/prompt.txt` is external user material. Do not rewrite, translate, trim, or delete it.