> For the complete documentation index, see [llms.txt](https://docs.mediafier.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediafier.ai/platform/media-library.md).

# Media Library

Bundles, versions, files, and provenance — the media context agents act on.

> **Bundles, versions, files, and provenance — the actual shape of media work.** The Media Library is Mediafier's media-native persistence layer. It is what gives agents the operational context their decisions need.

***

## The shape of media work

Generic file stores aren't shaped for media work. Real media work needs structure: a **bundle** (a logical work unit — a title, an episode, a campaign), the **versions** of that bundle as it moves through ingest, QC, edit, and publish, the **files** that make up each version, and the **provenance** lineage that connects them all.

Mediafier's Media Library exposes that shape directly. Agents read and write through governed tools that match the operator's mental model, not through generic CRUD.

***

In Library card views, select either an item’s thumbnail or its name to open the same detail page. Play buttons, selection checkboxes and action menus remain separate controls.

## What customers can do here today

The library covers the full asset lifecycle through a set of governed tools, grouped by intent:

| Intent                | What the tools cover                                                                      |
| --------------------- | ----------------------------------------------------------------------------------------- |
| **Ingest**            | Initiate uploads, complete uploads, list active ingests, ingest from a workflow output.   |
| **Bundle lifecycle**  | Create, update, list, search, archive, restore, soft-delete, and unarchive bundles.       |
| **Version lifecycle** | Create draft versions, list versions, get version details, publish (immutable promotion). |
| **File management**   | List files in a version, fetch signed download URLs, retrieve metadata.                   |
| **Provenance**        | Attach provenance, fetch provenance, walk lineage chains.                                 |
| **Analysis enqueue**  | Hand a version to the content-intelligence pipeline for asynchronous enrichment.          |
| **MEDIA.md compose**  | Render the canonical media-as-code description for a published version.                   |
| **Projects**          | Organize items into a folder tree of Projects: create, nest, move, archive, and roll up.  |

Destructive operations (soft-delete, publish, provenance attach, revoke) carry an explicit approval-worthiness risk signal in discovery so planners and review surfaces flag them as high-impact. Operator-side review consumes that signal today.

***

## Projects: a folder tree for your work

Every item lives in exactly one Project, or in **Files** when it isn't filed yet. Projects nest, so an agency can keep each client's work together:

```
Acme Coffee              (client)
└── Spring launch        (campaign)
    └── 30s spot         (deliverable)
```

* **Nest up to six levels deep.** A Project can hold items and sub-projects. The labels (client, campaign, deliverable) are yours to choose; they help people and agents read the tree, and they change nothing else.
* **Names are unique within a parent.** Two clients can each have a "Spring launch". When a name is already taken in the same place, you can keep both, and the new one is named "Spring launch (2)", the way Finder and Drive do it.
* **Move a whole branch.** Moving a Project brings its sub-projects and items with it, and every move can be undone. Moving never copies or re-uploads media.
* **Archive a whole branch.** Archiving a Project archives everything under it in one step, and restoring it brings back exactly that set.
* **See everything under a Project at once.** Project cards show rolled-up counts, and a list can include every item in the sub-projects.
* **Ingredients, not copies.** When an item is assembled from others (a mix made from a voice track and a music bed), it lists its **Ingredients**, each pinned to the exact version used, and each ingredient shows where it is **Used in**. A shared music bed lives once and is used by many ads.

Access is organization-wide: everyone in your organization can see every Project. Agents use the same tools as the app, so a tree an agent builds is the tree people see.

***

## MEDIA.md — the README.md for media

Every asset can carry a **MEDIA.md** — a declarative, atomic, modular, versioned description of the asset itself. Think of it as the README.md of media: structured context an agent (and an operator) can read in seconds and act on.

A MEDIA.md captures the things a media operator actually cares about:

* What the asset is — title, type, format, runtime.
* How it was made — production timeline, contributors, tools used.
* What's in it — summary, scenes, key entities, brand-safety state.
* What can be done with it — functions, distribution options, language coverage.
* Who has acted on it — edit history, QC gates passed, publication state.

Agents read MEDIA.md and know what to do next.

***

## Provenance Passport

Every file and every version carries a **Provenance Passport** — the immutable record of where the content came from and what has been done to it. The passport answers questions like:

* Was any part of this generated by AI? Which model? What was the prompt?
* Was this transcoded? From what source format?
* Did a human approve a particular state transition?
* Where does this segment ultimately trace back to?

Provenance is **append-only**. New events are added; existing events are not edited or removed. The data layer enforces it.

***

## Why media-native persistence matters

The platform's broader pitch — turning media tools into agent-ready infrastructure — only works if the data the agents reason against matches the operator's reality: a versioned bundle with a passport and a MEDIA.md, not a flat list of files. That is the ground the Media Library covers.

***

## Where to go next

| If you're…                                | Read next                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------- |
| Looking for what the AI can do with media | [Content Intelligence](/platform/content-intelligence.md)                           |
| Studying decision memory across runs      | [Decision Tracing & Learning Loop](/platform/decision-tracing-and-learning-loop.md) |
| Building or tuning a domain super-agent   | [MediaClaw Super-Agents](/platform/mediaclaw-super-agents.md)                       |
| Connecting the library to your harness    | [MCP Access](/connect/mcp-access.md)                                                |