Documentation limits
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.
| Code | Limit | lint | pack | hub submit | install | What it says, for example |
|---|---|---|---|---|---|---|
readme.size | README.md at most 65,536 bytes (64 KiB) | error | error | error | warning | 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). |
readme.images | At most 20 images from the package | error | error | error | warning | 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). |
readme.image_size | Each image at most 1,048,576 bytes (1 MiB) | error | error | error | warning | 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). |
readme.images_total | The images from the package at most 5,242,880 bytes (5 MiB) together | error | error | error | warning | 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). |
readme.image_dimensions | At most 4,096 pixels a side | error | error | error | warning | 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). |
readme.image_format | PNG, JPEG, WebP or GIF by their bytes, with the extension of their format; no SVG and no data: address | error | error | error | warning | 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). |
readme.image_missing | An image is a file of the package, by a path relative to the README that stays in the plugin's folder | error | error | error | warning | 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). |
readme.diagrams | At most 10 Mermaid diagrams | error | error | error | warning | 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). |
readme.diagram_size | Each diagram at most 5,000 characters | error | error | error | warning | 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). |
readme.missing | A README.md at the plugin's root (not for one part on its own) | warning | warning | warning | warning | 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). |
readme.remote_image | An image or badge from another host is never loaded | warning | warning | warning | warning | README.md shows https://example.com/badge.png 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). |
readme.html | Raw HTML is dropped from the page | warning | warning | warning | warning | README.md has raw HTML (3 in all, the first <img> on line 12); the hub's page drops it. Use Markdown instead (readme.html). |
readme.image_alt | Every image has alt text | warning | warning | warning | warning | 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). |
A file the checks do not read (one over 4 MiB, below) 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'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.
| Code | Check | lint | pack | hub submit | install | What it says, for example |
|---|---|---|---|---|---|---|
licence.id | license: is an SPDX expression of known identifiers, at most 256 characters, never NONE or NOASSERTION | error | error | error | error | 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-<name> with its text in LICENSES/LicenseRef-<name>.txt (licence.id). |
licence.deprecated | license: names no identifier the SPDX License List deprecated | warning | warning | warning | warning | names GPL-2.0, which the SPDX License List deprecated; write GPL-2.0-only (licence.deprecated). |
licence.mismatch | Each licence file reads as the licence license: declares (-only and -or-later both match their family) | error | error | error | warning | 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). |
licence.missing | A licence file for each licence declared, or any licence file when none is | warning | warning | error | warning | 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). |
licence.undeclared | A licence file comes with license: (not for one part on its own) | warning | warning | warning | warning | LICENSE reads as MIT, but oz0-plugin.yaml declares no licence. Add license: MIT (licence.undeclared). |
licence.unrecognised | The engine recognises the file's text | warning | warning | warning | warning | 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). |
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.