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.

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.

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.