# Folder Structure and File Naming

**Phase 7 · Iterate, assemble, publish**

## Why this matters

A GenAI film produces a lot of files. Stills, motion clips, audio stems, prompt logs, continuity packs, revision passes, release assets. Most of it is iteration — three versions of the same clip, two passes on the same VO, four thumbnails for one title. By the time you are at picture lock, the project folder is the difference between an afternoon of assembly and a week of archaeology.

A folder structure is a forcing function. It tells future-you what is canonical, what is draft, and what is dead. A naming convention does the same for individual files: which clip, which version, when was it made, what is it for. Without either, you ship with the wrong cut. With both, the project survives a six-month gap.

The rules below are not negotiable. Adopt them once. Apply them to every film after that. The cost is fifteen minutes of setup. The payoff is everything downstream.

## The canonical project folder

```text
ProjectName/
│
├── README.md
├── 00_workflow_overview.md
├── 01_playbook.md
├── 02_case_study.md
│
├── story/
│   ├── 01_logline.md
│   ├── 02_world.md
│   ├── 03_act_structure.md
│   └── 04_ending_design.md
│
├── continuity/
│   ├── characters/
│   │   ├── 01_hero_name.md
│   │   ├── 02_antagonist_name.md
│   │   └── 03_secondary_name.md
│   ├── locations/
│   │   └── 01_hero_location.md
│   └── reference_stills/
│       ├── hero01_face_v1.png
│       ├── hero01_face_v2.png
│       └── loc01_dawn_v1.png
│
├── clips/
│   ├── grid.md
│   ├── breakdowns/
│   │   ├── clip01_thesis.md
│   │   ├── clip02_intro.md
│   │   └── clip03_anomaly.md
│   ├── stills/
│   │   ├── clip01_thesis_v1.png
│   │   ├── clip01_thesis_v2.png
│   │   └── clip02_intro_v1.png
│   └── motion/
│       ├── clip01_thesis_v1.mp4
│       ├── clip01_thesis_v2.mp4
│       └── clip02_intro_v1.mp4
│
├── prompts/
│   ├── gpt_image/
│   │   ├── clip01_thesis_v1.md
│   │   └── clip02_intro_v1.md
│   ├── seedance/
│   │   ├── clip01_thesis_v1.md
│   │   └── clip02_intro_v1.md
│   └── negative_prompts.md
│
├── audio/
│   ├── vo/
│   │   ├── clip01_thesis_v1.wav
│   │   └── clip02_intro_v1.wav
│   ├── dialogue/
│   ├── motifs/
│   ├── beds/
│   └── sound_design.md
│
├── edit/
│   ├── project_files/
│   ├── exports/
│   │   ├── rough_2026-04-12.mp4
│   │   ├── master_v01.mp4
│   │   └── master_v07_final.mp4
│   └── notes.md
│
├── release/
│   ├── youtube/
│   │   ├── description.md
│   │   ├── thumbnail_v1.png
│   │   ├── thumbnail_v2.png
│   │   └── metadata.md
│   ├── festival/
│   │   └── submission_pack.md
│   └── press/
│       └── one_paragraph.md
│
└── archive/
    └── (dead drafts, abandoned versions, kept for reference)
```

Top-level files are project-wide documents. Subdirectories group by production phase. The `archive/` folder is where dead drafts go to die — keep it, but do not let it leak back into the working directories.

## File-naming rules

These are rules, not suggestions. Apply them to every file in the project.

### Rule 1 — Clip files: `clip##_purpose_v#.ext`

- `clip` followed by a two-digit clip number, zero-padded: `clip01`, `clip02`, `clip40`
- Underscore
- A short `purpose` slug — what the clip is, in one or two words. Snake case. No spaces.
- Underscore, `v`, version number: `v1`, `v2`, `v3`. Increment for every regenerated pass.
- Extension: `.md`, `.png`, `.mp4`, `.wav`, whatever fits.

Examples:
- `clip01_thesis_v1.md`
- `clip01_thesis_v2.png`
- `clip24_vale_broadcast_v3.mp4`
- `clip40_1_kitchen_v2.wav` (sub-clips use underscore-number, not dot)

### Rule 2 — Reference and continuity files: `type##_label_v#.ext`

- `hero01_face_v1.png` — first hero, face reference, version 1
- `loc01_dawn_v2.png` — first location, dawn variant, version 2
- `ui01_amber_v1.png` — first UI, amber palette, version 1

The two-letter or short-word prefix groups by type. Numbers disambiguate when you have multiple of the same type.

### Rule 3 — Dated files: ISO format only

Dates go `YYYY-MM-DD`. Always. Never `MM-DD-YYYY`, never `12_April_2026`, never `4-12`.

- `rough_2026-04-12.mp4`
- `revision_notes_2026-05-01.md`

ISO dates sort correctly when alphabetized. Other formats do not. This rule alone will save you hours.

### Rule 4 — Version suffixes are mandatory

Every file that can be regenerated gets a version suffix. Even if it is `v1` forever. The reason: the moment you skip the suffix on one file, you will overwrite the canonical version with a draft.

- Good: `master_v01.mp4`, `master_v02.mp4`, `master_v07_final.mp4`
- Bad: `master.mp4`, `master_final.mp4`, `master_FINAL_v2_REAL.mp4`

If you have a `_final` file, it is also a numbered version. The number wins ties.

### Rule 5 — No spaces. Ever.

Spaces in filenames break command lines, scripting, and half of upload pipelines. Use underscores. Use hyphens for word-internal separation if you need it.

- Good: `clip24_vale_broadcast_v3.mp4`
- Bad: `Clip 24 - Vale Broadcast v3.mp4`

### Rule 6 — Lowercase by default

ALL CAPS reads as shouting in a file list. Mixed case is inconsistent across operating systems (macOS is case-insensitive, Linux is not). Lowercase everything. Title-case only inside Markdown file contents, not in filenames.

### Rule 7 — No special characters

No `&`, `'`, `"`, `?`, `:`, `*`, `/`, `\`, `|`, `<`, `>`. They break in URLs, in zip files, on Windows. Stick to letters, numbers, underscores, hyphens, and dots.

### Rule 8 — Project root has a README

Every project's root folder has a `README.md` that names the project, the runtime target, the current cut version, and where the master lives. If a collaborator opens the folder cold, this is the first file they read.

## HangarX filled example

The HANGAR X project followed this structure. A few representative slices:

```
HangarX-Mirror-Protocol/
├── README.md
├── continuity/characters/
│   ├── 01_helix.md
│   ├── 02_vale.md
│   ├── 03_echo.md
│   └── 04_atlas_crane.md
├── clips/
│   ├── grid.md
│   ├── breakdowns/
│   │   ├── clip01_thesis.md
│   │   ├── clip02_helix_intro.md
│   │   ├── clip24_vale_broadcast.md
│   │   └── clip40_1_bridge.md
│   └── motion/
│       ├── clip01_thesis_v1.mp4
│       ├── clip01_thesis_v2.mp4
│       ├── clip02_helix_intro_v1.mp4
│       ├── clip02_helix_intro_v2.mp4
│       ├── clip02_helix_intro_v3.mp4  ← canonical
│       └── clip24_vale_broadcast_v4.mp4
└── edit/exports/
    ├── rough_2026-03-18.mp4
    ├── rough_2026-04-02.mp4
    ├── master_v01.mp4
    ├── master_v05.mp4
    └── master_v07_final.mp4
```

Notice the version counts. Clip 2 (HELIX intro) needed three passes — it was one of the four before/after revision targets. Clip 24 (VALE broadcast) needed four. Some clips landed on v1. The naming captures the production history without comment.

## Checklist

- [ ] Project root has a README naming the project, target runtime, and current master cut
- [ ] Every file uses snake_case, no spaces, no special characters
- [ ] Every regenerable file has a `v#` suffix
- [ ] Every clip file follows `clip##_purpose_v#.ext`
- [ ] Dates use ISO `YYYY-MM-DD` format everywhere
- [ ] `archive/` folder exists and dead drafts live there, not in working directories
- [ ] Continuity reference stills are grouped by type, not by clip
- [ ] Prompt files are grouped by model (gpt_image, seedance, etc.)
- [ ] Audio is grouped by function (vo, dialogue, motifs, beds), not by clip

## Common failure modes

- **`master_final_FINAL_v2.mp4`.** The version suffix is doing the work it was designed to prevent. Pick a number and trust it.
- **Hero stills scattered across `clips/stills/` instead of `continuity/reference_stills/`.** Continuity references are reusable across clips. Put them where they live, not where they were first used.
- **Prompts grouped by clip instead of by model.** Prompts get reused across clips. Group by model so you can scan for what works.
- **No README at the root.** Six months later, the project is illegible. Write the README before you do anything else.
- **Spaces in filenames "because it looks nicer."** It does not. It breaks scripts and confuses tools. No spaces.
- **Dates in regional format.** `12-04-26` is December 4th to some readers and April 12th to others. ISO format is unambiguous.
- **Archive folder used as a working directory.** Once a draft is in archive, it is dead. If you need it back, copy it forward into working — do not edit in archive.
