What you can do
You already opened Maya's homepage hero from Widgets and dropped Image onto the canvas — one of the ten built-in cards. The box is empty until a file is in the team library. This page is how she uploads that photograph once, then picks it in the composer.
Two everyday jobs:
- Put the hero photograph on the Production Default Widget. She uploads it on the team Images page, opens the widget, and clicks Select Image. The same file can sit on every environment's draft — the library belongs to the team, not to one widget.
- Add a short loop on a Video later. Clips live on Videos, a separate library. She uploads an MP4, WebM, or MOV, then picks it with Select Video. A Poster Image is still a picture — upload that under Images.
The files stay on her team. Other teams never see them, and there is no organization-wide library — the same team boundary as Component Libraries.
Ask AI can use a file that is already in the library. It cannot upload. Put the photograph on Images first, then ask — see Ask AI.
The upload page is not the only way in. Connect an agent through MCP and it can add the same photograph, from a public link or from a file on the computer, into this library. That is the convenient path when the file is already a URL, or you are already in the chat and do not want to open Upload and wait there. The page is still better when you want the grid and the progress bar. Either way you need Manage Media Assets. The steps are Images and videos with MCP.
How the library thinks
Images and videos are two libraries. The Image picker never lists clips. The Video picker never lists pictures. That is the idea people miss.
Here is the case that surprises people. Maya uploads the hero photograph, opens a Video, and looks for it under Select Video. The list is empty. The photo is on Images. If she wants a still on that clip, she uses Poster Image — that picker is the image library.
Optional defaults live on the file's detail page. When she picks the file in the composer, empty fields on that component fill in once — alt text, width, and height on an Image; playback and intrinsic size on a Video. Changing the defaults later does not rewrite files she already placed.
Video has no alt text. If the clip carries information the page depends on, put that in words nearby. Autoplay on the published page only works when the video is muted — browsers block autoplaying sound.
You need a Media Assets group. View Media Assets can open Images and Videos and pick files in the composer. Manage Media Assets can upload, edit defaults, and delete. The same groups cover both libraries. A RuleCMS admin account also works.
Upload Maya's hero photograph
Picture her homepage hero on the Production Default Widget — the widget created when the team was, in Production only. Today it is Text and an empty Image. This is the path from the team page to that photograph on the canvas.
- Open the organization → team. On the projects tab, under Team Resources, find the Images card. Click Manage Images. If you see Request your admin for access, you need View Media Assets.
- Click Upload. If that button is missing, you can browse but cannot add files — ask for Manage Media Assets.
- Under Select File, choose the photograph. The form accepts
.jpg,.jpeg,.png,.gif,.webp,.svg,.bmp,.tiff, and.ico, up to 10 MB. - Optionally add Tags — comma-separated, at most five, letters, numbers, and dashes, no spaces. They become lowercase. The team id is applied automatically so the file stays in this library.
- Click Upload. Stay on the page until you see Upload successful! A progress bar shows the transfer. Leaving the tab cancels it.
- Open the Production Default Widget. Click the Image. In Selected Component, click Select Image. The picker lists this team's pictures only. Choose the photograph. Empty alt text, width, and height can fill from defaults she saved on the file.
- Then publish. Live embeds do not change until you publish. That is a safe stop.
The Images page shows every picture for this team. Filter with Choose a tag. Click a card to open the detail page — preview, tags, and the optional defaults. Save attributes writes those defaults.
When you reach for video — or a default
The first path above is one photograph on the hero. These are the other levers, named as jobs.
| What you need | When you reach for it |
|---|---|
| A clip on the hero | Same team page, Videos card, Manage Videos, then Upload. Accepted files are .mp4, .webm, and .mov, up to 100 MB. Tags work the same way. In the composer, drag Video and click Select Video. Prefer a short loop so the page does not wait on a long file. |
| Poster Image | A still shown before play. It is an image. Upload it under Images, then pick it on the Video with Poster Image. The Video picker will not list it. |
| Image defaults | On the picture's detail page: Image Alt Text, Image Intrinsic Width, Image Intrinsic Height, plus sizes, loading, and fetch priority. Width and height start from the uploaded file until you save overrides. They prefill empty composer fields once when you pick the file. |
| Video defaults | On the clip's detail page: controls, autoplay, loop, muted, plays inline, preload, and intrinsic size. Set muted if you want autoplay. There is no alt field on video. |
| A plan dialog | Upload can open Image upload blocked or Video upload blocked when the team is over its media storage allowance, when the plan does not include video, or when a clip is larger than that plan allows. The dialog names the plan and what to do next. It does not invent a second size limit on top of the 10 MB / 100 MB form caps — those stay on Select File. |
What to read next
This page is the story and the first walkthrough. The Image and Video settings after you pick a file live on the pages below.
- Image — Alt text, intrinsic size, and the other Image settings once the photograph is on the canvas.
- Video — Playback, poster, and intrinsic size after you pick a clip.
- The Composer — The palette, the canvas, and Select Image in the Modify drawer.
- Widgets — Open Maya's hero from the dashboard. The Default Widget lives in Production.
- Publishing — Draft versus the snapshot a token fetches.
- Ask AI — Use a file that is already in the library. It cannot upload one.
- Images and videos with MCP — Add the same file from a link, or from the computer, without the upload page. The permission is still Manage Media Assets.
- Organizations & Teams — Grant the Media Assets groups on Manage Permissions.
- Component Libraries — Another team-scoped resource on the same Team Resources row.
- Development Integration — Preview a live Development draft that already uses the photograph.
How this fits
A media library does not replace a widget, and it does not replace the ten built-in cards — Text, Image, Video, Icon, Button, Divider, Embed, List, Accordion, Custom. It is the team's pictures and clips those cards pick from. Widgets is still how Maya opens the hero. Publishing is still how the site gets the snapshot.
The Default Widget lives in Production only. Promote copies the draft to the next environment. It does not publish. Copy To is only for extra named environments. The photograph she uploaded is already there for every environment on this team — she does not upload it again when she promotes.
Upload on Images or Videos. Pick with Select Image or Select Video. Publish when the hero looks right.