# Project: FreeExile 21 DRQ Asset Packages Completion & Pipeline Synchronization

## Architecture
- **Asset Pipeline Engine**:
  - `tools/asset_pipeline/design_pipeline_manager.py`: Core lifecycle manager (`dispatch_request`, `submit_for_review`, `qa_technical_audit`, `ceo_aesthetic_audit`).
  - `tools/asset_pipeline/design_pipeline_cli.py`: CLI frontend (`report`, `scan`, `dispatch`, `submit`, `qa-audit`, `ceo-audit`).
  - `tools/asset_pipeline/normal_map_utils.py`: Vectorized 3x3 Sobel normal map generator with transparent pixel padding $(128, 128, 255)$.
  - `tools/asset_pipeline/pbr_texture_synthesizer.py`: Emissive mask extraction and PBR material synthesis.
  - `tools/asset_pipeline/synthesize_21_drq_assets.py` & generators: Deterministic procedural synthesis of all 78 deliverables.
- **Asset Storage & Lifecycle Stages**:
  - `docs/design_requests/inbox/` (0 items) -> `docs/design_requests/approved/` (39 items, 21 new DRQs).
  - `assets/pending_review/<DRQ-ID>/`: Staging directory for newly synthesized deliverables.
  - `assets/approved/<DRQ-ID>/`: Official archive of approved deliverables (21 new directories, 78 deliverables).
  - `client/webapp/assets/<domain>/`: Production client runtime assets (78 deliverables synchronized bit-for-bit).

## Feature Inventory
| # | Feature / DRQ | Description | Milestone | Source |
|---|---------------|-------------|-----------|--------|
| 1 | `CLI-LOADING-SCREEN-ART` | Loading screen concept art & Bagua spinner | M1 | DRQ 01 |
| 2 | `CLI-LOGIN-PARALLAX-LAYERS` | 3-layer parallax login background | M1 | DRQ 02 |
| 3 | `CLI-TOUCH-CONTROLS-PROMOTION` | Virtual joystick atlas & touch HUD buttons | M1 | DRQ 03 |
| 4 | `CLI-WORLD-BACKGROUND-LAYERS` | Seamless Perlin fog texture & vignette mask | M1 | DRQ 04 |
| 5 | `ECO-BAZAAR-TRADE-PANELS` | Bazaar trading modal board & tax stamp | M2 | DRQ 05 |
| 6 | `ECO-CRAFTING-ORBS-CATALOG` | 6 crafting orbs atlas & Sobel normal map | M2 | DRQ 06 |
| 7 | `ECO-CURRENCY-BLOODSTONES` | 5-tier bloodstones, normal map, emissive mask & salvage dust | M2 | DRQ 07 |
| 8 | `ECO-LOOT-DROP-PARTICLES` | Loot beam gradients, sparkle particle & Metal shader | M2 | DRQ 08 |
| 9 | `NPC-CUTSCENE-STORYBOARD` | 3 chapter prologue splash arts & cinematic letterbox frame | M3 | DRQ 09 |
| 10 | `NPC-FERAL-ELDERS-AVATARS` | 5 Feral Elders avatar portraits & dialogue standees | M3 | DRQ 10 |
| 11 | `NPC-QUEST-SCROLL-VARIANTS` | 4 quest scroll themes & wax seal stamp badges | M3 | DRQ 11 |
| 12 | `SEC-ALERT-BADGES-QUARANTINE` | Security alert badges atlas & quarantine hazard banner | M4 | DRQ 12 |
| 13 | `SEC-SHIELD-ACTIVE-ANIMATION` | 8-frame shield loop, normal map & Metal pulse shader | M4 | DRQ 13 |
| 14 | `SEC-UI-FORENSIC-WATERMARK` | 1-2% alpha steganography tile & decoy bot hitboxes | M4 | DRQ 14 |
| 15 | `SRV-AGENT-ORB-ACTIVATION-VFX` | 3-tier light pillars, ground rune circle & Metal shader | M5 | DRQ 15 |
| 16 | `SRV-AOI-SYNC-TELEMETRY-VISUAL` | 30Hz tickrate badges, ping indicators & AoI line | M5 | DRQ 16 |
| 17 | `SRV-HARVEST-REPORT-OVERLAY` | Offline delegation summary modal & stat badges | M5 | DRQ 17 |
| 18 | `SYS-CRAFTING-STATION-UI` | Crafting station modal, slots & 15-tier affix badges | M6 | DRQ 18 |
| 19 | `SYS-HIDEOUT-SAFEHAVEN-PROPS` | Hideout props atlas, normal map & target dummy sprite | M6 | DRQ 19 |
| 20 | `SYS-MAP-DEVICE-ARENA` | 6-portal map device atlas, normal map & arena tiles | M6 | DRQ 20 |
| 21 | `SYS-PASSIVE-TREE-NODES` | Passive nodes atlas, normal map, emissive mask & constellation bg | M6 | DRQ 21 |
| 22 | Tech Art Validation Gate | Power-of-two ($2^n$), size budgets, normal map Blue mean >= 128 | M7 | R2 |
| 23 | 2-Tier Pipeline Approval | Stage 1 QA Technical Audit & Stage 2 CEO Aesthetic Audit | M7 | R3 |
| 24 | Client WebApp Asset Sync | Synchronize approved assets to `client/webapp/assets/` subdirs | M7 | R3 |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| M1 | Client Engine & UI Assets | DRQs 01-04 (13 deliverables in `assets/pending_review/`) | none | DONE |
| M2 | Economy, Currencies & Loot FX | DRQs 05-08 (16 deliverables, 2 normal maps, 1 emissive, 1 shader) | none | DONE |
| M3 | Narrative, NPCs & Quests | DRQs 09-11 (10 deliverables: splash art, portraits, scrolls) | none | DONE |
| M4 | Security, Forensics & Active Shield | DRQs 12-14 (10 deliverables, 1 normal map, 1 shader, steganography) | none | DONE |
| M5 | Server Engine, AI Totem & Telemetry | DRQs 15-17 (11 deliverables, 1 shader, telemetry, harvest UI) | none | DONE |
| M6 | Game Systems, Hideout & Passive Tree | DRQs 18-21 (18 deliverables, 3 normal maps, 1 emissive) | none | DONE |
| M7 | 2-Tier Audit, Lifecycle Transition & Sync | Audit 21 DRQs, transition to approved (39 total), sync to client | M1-M6 | DONE |

## Interface Contracts

### Tech Art Normal Map Specification
- Normal maps use Tangent-Space Sobel filtering with normalized $\vec{N} = (n_x, n_y, n_z)$.
- Quantization: $R = \lfloor(n_x \times 0.5 + 0.5) \times 255\rceil, G = \lfloor(n_y \times 0.5 + 0.5) \times 255\rceil, B = \lfloor(n_z \times 0.5 + 0.5) \times 255\rceil$.
- Transparent pixels ($\alpha = 0$): padded with flat tangent normal $(128, 128, 255)$ to guarantee Blue channel mean $\ge 128.0$. Verified: means range $247.75 - 253.39$.

### Emissive Mask Specification
- Saturation-Value Gating: GlowMask $(V \times S > 0.65) \lor (L > 220)$.
- Alpha channel matches Albedo Diffuse texture exactly.

### Metal Shader Specification
- Apple Metal Shading Language (MSL) format with SIMD16 alignment, 120 FPS ($8.33\text{ ms/frame}$) budget.

### Client Sync Destination Mapping
- Loading Screen: `client/webapp/assets/loading/`
- Parallax Login: `client/webapp/assets/banners/`
- Touch HUD: `client/webapp/assets/ui/combat/`
- World Atmosphere: `client/webapp/assets/map/`
- Trade Panels: `client/webapp/assets/ui/trade/`
- Currencies: `client/webapp/assets/currencies/`
- Loot Particles: `client/webapp/assets/savage_vfx/`
- Story Splash: `client/webapp/assets/banners/`
- NPC Elders: `client/webapp/assets/characters/npcs/`
- Quest Scrolls: `client/webapp/assets/ui/quests/`
- Security UI & Shield: `client/webapp/assets/ui/security/`
- Server Agent Orb VFX: `client/webapp/assets/savage_vfx/`
- Telemetry & Harvest UI: `client/webapp/assets/ui/`
- Crafting Station: `client/webapp/assets/ui/`
- Hideout Props & Arena: `client/webapp/assets/map/`
- Passive Tree Nodes: `client/webapp/assets/ui/passive_tree/`

## Code Layout
- Generator & synthesis scripts: `tools/asset_pipeline/`
- Staging directory: `assets/pending_review/<DRQ-ID>/`
- Approved directory: `assets/approved/<DRQ-ID>/`
- Client runtime directory: `client/webapp/assets/<subfolder>/`