Library Structure

cr4te expects one input directory containing creator directories. Each creator can contain media directly and one level of project directories.

Basic Shape

Creators/
|-- Creator Name/
|   |-- cr4te.json
|   |-- README.md
|   |-- portrait.png
|   |-- creator-level-image.png
|   |-- Project Name/
|   |   |-- cr4te.json
|   |   |-- README.md
|   |   |-- cover.png
|   |   |-- audio.mp3
|   |   |-- booklet.pdf

Creator folders become creator pages. Project folders become project pages.

Creator and project folder names are their canonical identities. They determine output paths and creator-reference resolution.

Editable display_name and display_title fields in cr4te.json control visible labels, search, and user-facing sorting without changing canonical identity.

Collaboration Folder Names

When a creator metadata file has no explicit type, cr4te infers collaborations from the creator folder name using media_rules.collaboration_separators. The defaults are & and ,.

Examples detected as collaborations by default:

Marin & The Mesa/
Alice, Bob/

Names without those separators are not automatically detected as collaborations:

The Foobars/
Blackwater Jazz Quartett/

For bands or groups with ordinary names, set "type": "collaboration" in cr4te.json and run build again so the metadata file is reconciled with the collaboration branch.

Creator-Level Media

Media directly inside a creator folder belongs to the creator page. This is useful for portraits, general galleries, videos, documents, or text files that describe the creator rather than a specific project.

Named portrait and cover images can also live in subfolders. cr4te prefers the first matching image directly inside the creator or project folder before nested matches. Automatic portrait discovery can use a portrait-oriented fallback anywhere below the creator folder, including project folders, while portrait visibility controls where discovered portraits appear. Covers search only their project and may fall back to landscape-oriented and then arbitrary images. Named role candidates, same-stem video-poster candidates, and selected fallback images are reserved from galleries.

Project-Level Media

Media inside a project folder belongs to that project page. In the music domain, a project usually maps to an album. In other domains it might be a work, movie, book, scene, or general project.

README Files

README.md files are narrative content:

• Creator/README.md becomes creator description text.
• Creator/Project/README.md becomes project description text.

README.md is not treated as a regular text media item.

Metadata Files

cr4te.json files are editable structured metadata:

• Creator/cr4te.json describes a creator.
• Creator/Project/cr4te.json describes a project.

Generated scan output does not belong in metadata files.

Media Folders

Media can be grouped into subfolders. cr4te builds media groups from folder buckets. Root media uses the domain/page default section labels; nested media groups use the nested folder name as a section title.

Example:

Album/
|-- 01 - Track.mp3
|-- extras/
|   |-- cover-study.png
|   |-- booklet.pdf

Excluded Paths

cr4te skips hidden paths and paths whose parts start with the configured global exclude prefix. The default prefix is _.

Examples skipped by default:

_drafts/
.cache/
Project/extras/_unused.png

The configured metadata folder name, default meta, is also not treated as a project folder when it appears directly under a creator. It can still hold creator-level media, uses root-group section labels, and its media groups appear after the actual root group and before ordinary media-folder groups.

Search Depth

Media scanning is limited by media_rules.max_search_depth. The default is 5, which is enough for typical nested media folders without scanning arbitrarily deep archives.