---
title: "Documentation limits"
description: "Look up README, image, diagram and licence bounds."
canonical_url: "https://docs.oz0.ai/build/plugins/limits/documentation"
---
# Documentation limits

> Look up README, image, diagram and licence bounds.

For: tenant administrators and plugin authors.

Look up README, image, diagram and licence bounds.

## The README, its images and its diagrams

The scanner reads `README.md` at the plugin's root (or another case of that name) the way the hub's page renders it, with GitHub-flavoured Markdown, and measures each image from its bytes. The page shows the whole README: headings with a contents list, tables, callouts, task lists, footnotes, images from the package, Mermaid diagrams and highlighted code. It never shows raw HTML, remote images or badges (their alt text shows instead) or SVG.

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Limit
    </th>
    
    <th>
      lint
    </th>
    
    <th>
      pack
    </th>
    
    <th>
      hub submit
    </th>
    
    <th>
      install
    </th>
    
    <th>
      What it says, for example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code id="readme-size">
        readme.size
      </code>
    </td>
    
    <td>
      <code>
        README.md
      </code>
      
       at most 65,536 bytes (64 KiB)
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md is 81,920 bytes; the hub shows at most 65,536 (64 KiB). Keep the README to what the plugin does, how to set it up and its limits. Move long guides and references to your own site and link to them from the README (readme.size).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-images">
        readme.images
      </code>
    </td>
    
    <td>
      At most 20 images from the package
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md shows 24 images from the package; the hub shows at most 20. Keep the README to what the plugin does, how to set it up and its limits. Move long guides and references to your own site and link to them from the README (readme.images).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-image_size">
        readme.image_size
      </code>
    </td>
    
    <td>
      Each image at most 1,048,576 bytes (1 MiB)
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md shows docs/screen.png, which is 1,572,864 bytes; the hub shows images of at most 1,048,576 (1 MiB). Make it smaller, or show it on your own site and link to it from the README (readme.image_size).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-images_total">
        readme.images_total
      </code>
    </td>
    
    <td>
      The images from the package at most 5,242,880 bytes (5 MiB) together
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md shows images of 6,291,456 bytes together; the hub shows at most 5,242,880 (5 MiB). Keep the README to what the plugin does, how to set it up and its limits. Move long guides and references to your own site and link to them from the README (readme.images_total).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-image_dimensions">
        readme.image_dimensions
      </code>
    </td>
    
    <td>
      At most 4,096 pixels a side
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md shows docs/wide.png, which is 6,000 by 1,200 pixels; the hub shows images of at most 4,096 pixels a side. Scale it down (readme.image_dimensions).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-image_format">
        readme.image_format
      </code>
    </td>
    
    <td>
      PNG, JPEG, WebP or GIF by their bytes, with the extension of their format; no SVG and no <code>
        data:
      </code>
      
       address
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md shows docs/logo.svg: it is an SVG, which the hub does not show: use PNG, JPEG, WebP or GIF. The hub shows PNG, JPEG, WebP and GIF images whose extension agrees with their bytes, never SVG or data: addresses (readme.image_format).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-image_missing">
        readme.image_missing
      </code>
    </td>
    
    <td>
      An image is a file of the package, by a path relative to the README that stays in the plugin's folder
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md shows ../shared/arch.png, but it is not a path inside the plugin's folder. The hub shows only images the package holds, by a path relative to the README (readme.image_missing).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-diagrams">
        readme.diagrams
      </code>
    </td>
    
    <td>
      At most 10 Mermaid diagrams
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md has 12 Mermaid diagrams; the hub shows at most 10. Keep the README to what the plugin does, how to set it up and its limits. Move long guides and references to your own site and link to them from the README (readme.diagrams).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-diagram_size">
        readme.diagram_size
      </code>
    </td>
    
    <td>
      Each diagram at most 5,000 characters
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md has a Mermaid diagram of 6,200 characters on line 40; the hub shows diagrams of at most 5,000. Split it, or keep the README to what the plugin does, how to set it up and its limits. Move long guides and references to your own site and link to them from the README (readme.diagram_size).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-missing">
        readme.missing
      </code>
    </td>
    
    <td>
      A <code>
        README.md
      </code>
      
       at the plugin's root (not for one part on its own)
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      The plugin has no README.md. The hub's page shows the README as the plugin's documentation: say what the plugin does, how to set it up and its limits (readme.missing).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-remote_image">
        readme.remote_image
      </code>
    </td>
    
    <td>
      An image or badge from another host is never loaded
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md shows <code>
        https://example.com/badge.png
      </code>
      
       from another host; the hub never loads it and shows its alt text instead. Put the image in the package to show it (readme.remote_image).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-html">
        readme.html
      </code>
    </td>
    
    <td>
      Raw HTML is dropped from the page
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md has raw HTML (3 in all, the first &lt;img> on line 12); the hub's page drops it. Use Markdown instead (readme.html).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="readme-image_alt">
        readme.image_alt
      </code>
    </td>
    
    <td>
      Every image has alt text
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      README.md shows docs/screen.png on line 18 without alt text; say what it shows, for readers who cannot see it (readme.image_alt).
    </td>
  </tr>
</tbody>
</table>

A file the checks do not read (one over 4 MiB, [below](https://docs.oz0.ai/build/plugins/limits/artifacts#bundle-checked)) is measured by its size alone, so an image that large is reported as too large, never as missing.

## The licence

`license:` in `oz0-plugin.yaml` declares the plugin's licence as an SPDX expression of the [SPDX License List](https://spdx.org/licenses/)'s identifiers, such as `MIT`, `Apache-2.0` or `MIT OR Apache-2.0`, at most 256 characters, joined with `AND`, `OR` and `WITH`, or `LicenseRef-<name>` for a licence of your own. Each licence it names needs a file whose text reads as that licence: a file at the root whose name starts with `LICENSE`, `LICENCE` or `COPYING` in any case (such as `LICENSE`, `LICENSE.md`, `LICENSE-MIT` or `COPYING.LESSER`), or `LICENSES/<id>.txt` (the REUSE layout). The check reads at most 32 licence files.

The file `oz0 plugin new` writes is a placeholder, which counts as no licence file until you replace it with the licence's text.

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Check
    </th>
    
    <th>
      lint
    </th>
    
    <th>
      pack
    </th>
    
    <th>
      hub submit
    </th>
    
    <th>
      install
    </th>
    
    <th>
      What it says, for example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code id="licence-id">
        licence.id
      </code>
    </td>
    
    <td>
      <code>
        license:
      </code>
      
       is an SPDX expression of known identifiers, at most 256 characters, never <code>
        NONE
      </code>
      
       or <code>
        NOASSERTION
      </code>
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      oz0-plugin.yaml declares license: "MIT/X11", which is not an SPDX licence expression the engine reads: "MIT/X11" is not a licence identifier: letters, digits, dots and dashes. Use identifiers of the SPDX License List (spdx.org/licenses), joined with AND, OR or WITH, or LicenseRef-&lt;name> with its text in LICENSES/LicenseRef-&lt;name>.txt (licence.id).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="licence-deprecated">
        licence.deprecated
      </code>
    </td>
    
    <td>
      <code>
        license:
      </code>
      
       names no identifier the SPDX License List deprecated
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      names GPL-2.0, which the SPDX License List deprecated; write GPL-2.0-only (licence.deprecated).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="licence-mismatch">
        licence.mismatch
      </code>
    </td>
    
    <td>
      Each licence file reads as the licence <code>
        license:
      </code>
      
       declares (<code>
        -only
      </code>
      
       and <code>
        -or-later
      </code>
      
       both match their family)
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      LICENSE reads as Apache-2.0, but oz0-plugin.yaml declares license: MIT. Declare the licence the file holds, or put the declared licence's text in the file (licence.mismatch).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="licence-missing">
        licence.missing
      </code>
    </td>
    
    <td>
      A licence file for each licence declared, or any licence file when none is
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      error
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      The plugin has no licence file (a placeholder counts as none). Put the licence's text in LICENSE and declare it as license: in oz0-plugin.yaml; the hub lists no plugin without one (licence.missing).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="licence-undeclared">
        licence.undeclared
      </code>
    </td>
    
    <td>
      A licence file comes with <code>
        license:
      </code>
      
       (not for one part on its own)
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      LICENSE reads as MIT, but oz0-plugin.yaml declares no licence. Add license: MIT (licence.undeclared).
    </td>
  </tr>
  
  <tr>
    <td>
      <code id="licence-unrecognised">
        licence.unrecognised
      </code>
    </td>
    
    <td>
      The engine recognises the file's text
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      warning
    </td>
    
    <td>
      LICENSE.md holds a text the engine does not recognise, so it cannot say whether it is MIT; the hub's maintainers read it at review (licence.unrecognised).
    </td>
  </tr>
</tbody>
</table>

`licence.id` is an error at install too, since a manifest whose `license:` does not read is malformed. An imported Claude Code or Agent plugin whose own `plugin.json` gives a `license` that is not SPDX is the exception: its format allows any text, so it is not carried over, a warning at lint, pack and install and an error at hub submit; write an SPDX expression in its `plugin.json`, or set `license:` in an `oz0-plugin.yaml` overlay beside it, a file that starts with the line `import: {}`.

The hub's page says what the licence files read as and what `license:` declares, never that a licence is valid or that a use is allowed: its words for each result are on [List a plugin](https://docs.oz0.ai/build/plugins/list-a-plugin/review#the-licence).


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.