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.

Images using the configured portrait or cover basename can also live in subfolders. cr4te selects the lexicographically first matching image directly inside the creator or project folder, or otherwise the lexicographically first matching image below that folder.

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.