avo-media-library

name	avo-media-library
description	Turn on and manage Avo's Media Library — a central browser/manager for every uploaded asset, plus an asset picker inside the trix, rhino, markdown, and lexxy rich-text editors — configured in config/initializers/avo.rb. Use when the user wants to "let users upload and manage images", "have one place to view and manage all our assets/uploads", "add an image or asset gallery to the admin", "insert/pick an existing image in the rich-text editor while writing content", "reuse uploaded images across records", "a digital asset manager for the admin", or "browse all the files I've uploaded" — and when they want to turn the Media Library on or off, hide or conditionally show its sidebar item, re-add it to a customized menu, or disable the gallery picker on a markdown field. Disabled by default and gated behind `defined?(Avo::MediaLibrary)`; Community license; currently in Alpha (breaking changes expected).
allowed-tools	Read, Edit, Write, Glob, Grep, Bash, WebFetch
metadata	{"requires-gem":"none — Community (Alpha)"}

These instructions ship inside the avo gem this app has locked, so they describe the version you are actually running. Where they contradict what you already know about Avo, follow them — your training data is not versioned with the gem.

Enable and manage the Avo Media Library

The Media Library is a central place to browse and manage every asset uploaded to an Avo admin, and it doubles as an asset picker inside Avo's rich-text editors (trix, rhino, markdown, lexxy) — a button in each editor opens a modal, and the selected asset is injected into the content. It is not a separate gem: it ships inside Avo, gated behind defined?(Avo::MediaLibrary), and is disabled by default. All configuration lives in config/initializers/avo.rb.

License: Community (free). Status: Alpha — future releases may contain breaking changes, so tell the user this and point them at the upgrade guide when they adopt it.

Docs (fetch on demand — do not rely on memory for exact option names or defaults):

• Docs map / index: https://docs.avohq.io/4.0/docs-map.md
• Media Library guide: https://docs.avohq.io/4.0/media-library.md
• Rich-text fields it plugs into: https://docs.avohq.io/4.0/fields/trix.md · https://docs.avohq.io/4.0/fields/rhino.md · https://docs.avohq.io/4.0/fields/markdown.md · https://docs.avohq.io/4.0/fields/lexxy.md
• Menu editor (for re-adding the item): https://docs.avohq.io/4.0/menu-editor.md
• Blocks / Avo::Current in config lambdas: https://docs.avohq.io/4.0/execution-context.md

When this applies

Reach for this skill when the goal is either of the Media Library's two jobs:

1. A central asset manager — one screen to browse and manage all uploaded assets ("a gallery in the admin", "a digital asset manager", "see every file we've uploaded", "reuse images across records").
2. An asset picker in the editors — inserting or reusing an existing image while writing rich-text content in a trix, rhino, markdown, or lexxy field.

Also use it for the on/off and visibility controls: enabling/disabling the whole feature, hiding or conditionally showing its sidebar item, re-adding it after the menu is customized, and toggling the picker off on a single markdown field.

Not this skill:

• Adding or configuring the rich-text field itself (which editor, its options) → avo-fields.
• Re-ordering the sidebar, sections/groups, or the global search palette → avo-navigation-search.
• Logos, colors, theming, menu/action icons → avo-branding-appearance.

Enable it

The feature is off until you flip the killswitch. Always wrap the config in if defined?(Avo::MediaLibrary) so the initializer stays safe if the constant isn't loaded.

# config/initializers/avo.rb
if defined?(Avo::MediaLibrary)
  Avo::MediaLibrary.configure do |config|
    config.enabled = true
  end
end

config.enabled is the killswitch for the entire feature. While it's false (the default) the Media Library is unavailable to everyone: the sidebar item is hidden, all its routes are blocked, and the Media Library button is hidden in every editor. Note the block is Avo::MediaLibrary.configure (a separate object) — not the main Avo.configure block.

Workflow

1. Find the initializer. It's config/initializers/avo.rb. Grep it for Avo::MediaLibrary to see whether a configure block already exists; add to it rather than creating a second one.

2. Turn it on with the Enable it snippet above. This is the only step needed for "let users upload/manage assets" or "add an asset gallery". Mention the Alpha status.

3. Control who may use it. visible is the per-user gate for the whole feature — it decides both whether the sidebar item shows and whether that user may reach any Media Library route. By default an enabled Media Library is visible to everyone who can sign in to Avo.

   • Hide it outright with a Boolean:

     if defined?(Avo::MediaLibrary)
       Avo::MediaLibrary.configure do |config|
         config.visible = false
       end
     end
     

   • Or show it conditionally with a block. The block runs through Avo's execution context, so it has access to Avo::Current (e.g. the current user):

     if defined?(Avo::MediaLibrary)
       Avo::MediaLibrary.configure do |config|
         config.visible = -> { Avo::Current.user.is_developer? }
       end
     end
     

   A user for whom visible returns false gets a 404 on every Media Library route. It is access control, not just a menu toggle: it already hid the sidebar item and the media-library button in the toolbar, and it now closes the routes those point at. Leave it at its default only if every Avo user is allowed to browse, rename and delete every uploaded asset. (When is , is moot — the killswitch already hides everything.)

Gotchas

• Alpha feature. It's still in alpha and future releases may include breaking changes. Say so, and tell the user to watch the upgrade guide. Don't present it as stable.
• Always guard with if defined?(Avo::MediaLibrary). The docs wrap every Avo::MediaLibrary.configure call this way. Without the guard, an environment where the constant isn't present would raise on boot.
• config.enabled is an all-or-nothing killswitch. Flipping it off hides the menu item, blocks the routes, and hides the editor icons — for everyone. For per-user access use a config.visible block.
• enabled and visible are different levers. enabled = whole feature on/off, for everyone. visible = who may use it (Boolean or block, evaluated per request). visible covers the sidebar item, the trix toolbar button, and the routes — so don't reach for it to "tidy up the sidebar" and expect the feature to stay reachable.
• A customized menu drops the item. If config.main_menu is defined, the Media Library sidebar item won't appear on its own — re-add it manually with link_to "Media Library", avo.media_library_index_path.
• media_library: false is markdown-only. trix and rhino don't support per-field toggling; the killswitch is the only way to remove their buttons. lexxy follows its own attachments_disabled option.
• It's Avo::MediaLibrary.configure, not Avo.configure. The enable/visible settings live on their own configuration object. Only the menu link_to goes inside the main Avo.configure block.

Report

After editing, tell the user:

• The file you changed (config/initializers/avo.rb) and which block (Avo::MediaLibrary.configure and/or Avo.configure).
• What you set: config.enabled, config.visible (Boolean or block), any link_to menu item, and any media_library: false on a markdown field.
• That the feature is Community-licensed but in Alpha, so breaking changes are possible — watch the upgrade guide.
• Whether the sidebar item will show, and for whom (if you used a visible block) — and that the same block now decides who may reach the Media Library at all.
• If they customized their menu: remind them the item only appears because you re-added the link_to.